Calculate a reasonable salary for S Corp owner-employees

The Salary Estimates API enables embedded partners to provide S Corporation owner-employees with compliant salary calculations based on Bureau of Labor Statistics (BLS) data.

This API solves the critical challenge where S Corp owner-employees must pay themselves a "reasonable salary" to maintain IRS compliance.

Without proper salary calculations, S Corp owner-employees face the risks of underpayment (IRS audits or penalties) or overpayment (unnecessary tax burden), lack systematic documentation to assist with IRS audits, and might rely on costly external services or time-consuming manual research.

Key benefits of this API:

Provides integrated reasonable salary calculation based on BLS data
Offers competitive differentiation for partners serving S Corp customers
Reduces reliance on external calculation services
Enables immediate salary estimates without complex workflows

1. Retrieve occupations

Call GET /v1/salary_estimates/occupations to search the BLS data and find relevant occupation codes.
Use ?search={query} to filter occupations by name and description.

Sample request:

curl --request GET \
     --url https://api.gusto-demo.com/v1/salary_estimates/occupations?search=Operations%20Manager \
     --header 'X-Gusto-API-Version: 2024-04-01' \
     --header 'accept: application/json'

Sample response

[
  {
    "code": "111021",
    "name": "General and Operations Managers", 
    "description": "Plan, direct, or coordinate the operations of public or private sector organizations, overseeing multiple departments or locations."
  }
]

2. Create a salary estimate

Next, call the POST /v1/employees/{employee_uuid}/salary_estimates endpoint to create a new salary estimate with minimal required data:

zip_code: User's business location ZIP code
occupations: Array of BLS occupations.
- experience_level: A string value of one of the following: novice, intermediate, average, skilled, expert
- The time_percentage values across all occupations must add up to 1.0 (100%).
(Optional) annual_net_revenue: Company revenue after expenses

Sample request:

curl --request POST \
     --url https://api.gusto-demo.com/v1/employees/employee_id/salary_estimates \
     --header 'X-Gusto-API-Version: 2024-04-01' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "occupations": [
    {
      "experience_level": "novice",
      "primary": true
    }
  ]
}
'

Sample response

{
  "uuid": "7f5d3d93-6d6f-48c0-9f4e-cd12c2d3e4b2",
  "employee_uuid": "8c290660-b6c9-4ad7-9f6e-ea146aaf79e8",
  "employee_job_uuid": null,
  "annual_net_revenue": "500000",
  "zip_code": "94107",
  "result": 12000000,
  "accepted_at": null,
  "created_at": "2025-01-15T10:30:00.000-08:00",
  "updated_at": "2025-01-15T10:30:00.000-08:00",
  "occupations": [
    {
      "code": "15-1252",
      "name": "Software Developers, Systems Software",
      "description": "Research, design, develop, and test operating systems-level software.",
      "experience_level": "novice",
      "time_percentage": "1.0",
      "primary": true
    }
  ]
}

Save the uuid to use when retrieving, modifying, or accepting the salary estimate.

3. Retrieve the salary estimate

Retrieve a salary estimate by calling the GET /v1/salary_estimates/{estimate_uuid} endpoint.

Sample request:

curl --request GET \
     --url https://api.gusto-demo.com/v1/salary_estimates/uuid \
     --header 'X-Gusto-API-Version: 2024-04-01' \
     --header 'accept: application/json'

Sample response

{
  "uuid": "7f5d3d93-6d6f-48c0-9f4e-cd12c2d3e4b2",
  "employee_uuid": "8c290660-b6c9-4ad7-9f6e-ea146aaf79e8",
  "employee_job_uuid": null,
  "annual_net_revenue": "500000",
  "zip_code": "94107",
  "result": 12000000,
  "accepted_at": null,
  "created_at": "2025-01-15T10:30:00.000-08:00",
  "updated_at": "2025-01-15T10:30:00.000-08:00",
  "occupations": [
    {
      "code": "15-1252",
      "name": "Software Developers, Systems Software",
      "description": "Research, design, develop, and test operating systems-level software.",
      "experience_level": "novice",
      "time_percentage": "1.0",
      "primary": true
    }
  ]
}

4. (Optional) Modify salary estimate

Modify an existing salary estimate to update parameters such as occupations or revenue by calling the PUT /v1/salary_estimates/{estimate_uuid} endpoint.

This endpoint receives a similar payload to the POST endpoint and allows iterative refinement before acceptance.

Sample request:

curl --request PUT \
     --url https://api.gusto-demo.com/v1/salary_estimates/uuid \
     --header 'X-Gusto-API-Version: 2024-04-01' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "occupations": [
    {
      "experience_level": "skilled",
      "primary": true
    }
  ]
}
'

Sample response

{
  "uuid": "7f5d3d93-6d6f-48c0-9f4e-cd12c2d3e4b2",
  "employee_uuid": "8c290660-b6c9-4ad7-9f6e-ea146aaf79e8",
  "employee_job_uuid": null,
  "annual_net_revenue": "500000",
  "zip_code": "94107",
  "result": 12000000,
  "accepted_at": null,
  "created_at": "2025-01-15T10:30:00.000-08:00",
  "updated_at": "2025-01-15T10:30:00.000-08:00",
  "occupations": [
    {
      "code": "15-1252",
      "name": "Software Developers, Systems Software",
      "description": "Research, design, develop, and test operating systems-level software.",
      "experience_level": "skilled",
      "time_percentage": "1.0",
      "primary": true
    }
  ]
}

5. (Optional) Accept estimate

Optionally accept a salary estimate to create formal audit documentation by calling the POST /v1/salary_estimates/{estimate_uuid}/accept endpoint.

📘
Once accepted, the estimate becomes read-only.

Sample request

curl --request POST \
     --url https://api.gusto-demo.com/v1/salary_estimates/uuid/accept \
     --header 'X-Gusto-API-Version: 2024-04-01' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

Sample response

{
  "uuid": "7f5d3d93-6d6f-48c0-9f4e-cd12c2d3e4b2",
  "employee_uuid": "8c290660-b6c9-4ad7-9f6e-ea146aaf79e8",
  "employee_job_uuid": null,
  "annual_net_revenue": "500000",
  "zip_code": "94107",
  "result": 12000000,
  "accepted_at": null,
  "created_at": "2025-01-15T10:30:00.000-08:00",
  "updated_at": "2025-01-15T10:30:00.000-08:00",
  "occupations": [
    {
      "code": "15-1252",
      "name": "Software Developers, Systems Software",
      "description": "Research, design, develop, and test operating systems-level software.",
      "experience_level": "skilled",
      "time_percentage": "1.0",
      "primary": true
    }
  ]
}

Error handling

Common error responses:

Error code	Description
`400`	Invalid occupation code or missing required fields
`404`	Salary estimate not found
`409`	Estimate already accepted (for modification or accept endpoints)
`422`	Invalid ZIP code or experience level values
`422`	Time percentages do not add up to 1.0

FAQ

How accurate are the salary calculations?
The API uses Bureau of Labor Statistics (BLS) data from the Occupational Employment and Wage Statistics (OEWS) program, which is updated annually and represents the most authoritative source for occupation-based salary data.

Can these calculations be used for compliance purposes?
The API provides BLS-based calculations that represent industry-standard methodology for determining reasonable compensation. The optional accept endpoint creates formal documentation suitable for audit purposes. However, partners may want to advise customers to consult with tax professionals for specific compliance guidance, as individual circumstances may vary.

What happens when I accept an estimate?
Acceptance creates a permanent, read-only record associated with a specific employee job. The estimate receives an acceptance timestamp and can be recovered as documentation for compliance purposes. No further modifications are allowed after acceptance.

How often is BLS data updated?
BLS occupation and wage data is updated annually, typically published in May with data from the previous calendar year. The API automatically uses the most current available data for all calculations.