Manage employee benefits

Benefits are the employer-offered programs (health, dental, retirement, commuter, etc.) that can involve employer contributions and employee payroll deductions.

Quick glossary

Company benefit: the company’s configured offering for a supported benefit type. Learn more about company benefits in the Manage company benefits guide.
Employee benefit: an employee’s enrollment in a company benefit, including employee deduction and company contribution details
Supported benefit: a benefit type that Gusto recognizes (for example, Medical Insurance). You can check the list of supported benefits using the GET /v1/benefits endpoint.

Create an employee benefit

Create an employee benefit by using the POST employees/{employee_id}/employee_benefits endpoint.

The body requires the parameter company_benefit_uuid. This is the uuid of the company benefit that you’ve previously created and wanted to assign into this employee benefit.

Sample request

curl --request POST \
     --url https://api.gusto-demo.com/v1/employees/employee_id/employee_benefits \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "active": true,
  "employee_deduction": "100.00",
  "deduct_as_percentage": false,
  "contribution": {
    "type": "amount",
    "value": "100.00"
  },
  "elective": false,
  "catch_up": false,
  "coverage_salary_multiplier": "0.00",
  "company_benefit_uuid": "f68abb42-431e-4392-bc3f-2795627e00f3"
}
'

Sample response

{
  "version": "09j3d29jqdpj92109j9j2d90dq",
  "employee_uuid": 908123091820398,
  "company_benefit_uuid": "54e37c27-43e6-4ae5-a5b2-e29895a133be",
  "active": true,
  "uuid": "e91ca856-a915-4339-9b18-29f9cd66b031",
  "employee_deduction": "100.00",
  "employee_deduction_annual_maximum": "200.00",
  "company_contribution_annual_maximum": "200.00",
  "limit_option": null,
  "deduct_as_percentage": false,
  "catch_up": false,
  "coverage_amount": null,
  "deduction_reduces_taxable_income": null,
  "coverage_salary_multiplier": "0.00",
  "contribution": {
    "type": "amount",
    "value": "100.00"
  }
}

Get an employee benefit

After you’ve created an employee benefit, you can confirm with the GET employee_benefits/{employee_benefit_id} endpoint.

Sample request

curl --request GET \
     --url https://api.gusto-demo.com/v1/employee_benefits/employee_benefit_id \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json'

Sample response

{
  "version": "09j3d29jqdpj92109j9j2d90dq",
  "employee_uuid": 908123091820398,
  "company_benefit_uuid": "54e37c27-43e6-4ae5-a5b2-e29895a133be",
  "active": true,
  "uuid": "e91ca856-a915-4339-9b18-29f9cd66b031",
  "employee_deduction": "100.00",
  "employee_deduction_annual_maximum": "200.00",
  "company_contribution_annual_maximum": "200.00",
  "limit_option": null,
  "deduct_as_percentage": false,
  "catch_up": false,
  "coverage_amount": null,
  "deduction_reduces_taxable_income": null,
  "coverage_salary_multiplier": "0.00",
  "contribution": {
    "type": "amount",
    "value": "100.00"
  }
}

Get all benefits for an employee

Get an array of all employee benefits for a given employee by using the GET employees/{employee_id}/employee_benefits endpoint.

Sample request

curl --request GET \
     --url https://api.gusto-demo.com/v1/employees/employee_id/employee_benefits \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json'

Sample response

[
  {
    "version": "09j3d29jqdpj92109j9j2d90dq",
    "employee_uuid": "8f9f3f68-8fd3-499d-ade7-4a052e56494e",
    "company_benefit_uuid": "54e37c27-43e6-4ae5-a5b2-e29895a133be",
    "active": true,
    "uuid": "e91ca856-a915-4339-9b18-29f9cd66b031",
    "employee_deduction": "100.00",
    "company_contribution": "100.00",
    "employee_deduction_annual_maximum": "200.00",
    "company_contribution_annual_maximum": "200.00",
    "limit_option": null,
    "deduct_as_percentage": false,
    "contribute_as_percentage": false,
    "catch_up": false,
    "coverage_amount": null,
    "deduction_reduces_taxable_income": null,
    "coverage_salary_multiplier": "0.00"
  }
]

Get all employee benefits for a company benefit

Get an array of all employee benefits enrolled for a given company benefit using the GET company_benefits/{company_benefit_id}/employee_benefits endpoint.

Sample request

curl --request GET \
     --url https://api.gusto-demo.com/v1/company_benefits/company_benefit_id/employee_benefits \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json'

Sample response

[
  {
    "version": "09j3d29jqdpj92109j9j2d90dq",
    "employee_uuid": "8f9f3f68-8fd3-499d-ade7-4a052e56494e",
    "company_benefit_uuid": "54e37c27-43e6-4ae5-a5b2-e29895a133be",
    "active": true,
    "uuid": "e91ca856-a915-4339-9b18-29f9cd66b031",
    "employee_deduction": "100.00",
    "company_contribution": "100.00",
    "employee_deduction_annual_maximum": "200.00",
    "company_contribution_annual_maximum": "200.00",
    "limit_option": null,
    "deduct_as_percentage": false,
    "contribute_as_percentage": false,
    "catch_up": false,
    "coverage_amount": null,
    "deduction_reduces_taxable_income": null,
    "coverage_salary_multiplier": "0.00"
  }
]

Delete an employee benefit

Delete an existing employee benefit by using the DELETE employee_benefits/{employee_benefit_id} endpoint.

Sample request

curl --request DELETE \
     --url https://api.gusto-demo.com/v1/employee_benefits/employee_benefit_id \
     --header 'X-Gusto-API-Version: 2025-06-15'
'

If the delete is successful, you’ll get a 204 response with no content.