Create company benefits

Before using this guide you must have a company created. You can learn more by following the Onboard a Company guide.

1. Get supported benefits

Gusto currently supports 32 different types of external benefits.

To get a list of all supported benefits, use the GET v1/benefits endpoint. The endpoint will return an array of Company Benefit objects, each object returned exists in the following form:

{
  "benefit_type": 1,
  "name": "Medical Insurance",
  "description": "Deductions and contributions for Medical Insurance",
  "pretax": true,
  "posttax": false,
  "imputed": false,
  "healthcare": true,
  "retirement": false,
  "yearly_limit": false,
  "category": "Health"
}

📘
The benefit object in Gusto contains high level information about a particular benefit type and its tax considerations. When companies choose to offer a benefit, they are creating a Company Benefit object associated with a particular benefit.

2. Create a company benefit

Using the id of the benefit you want to add from Step 1, you can now create the company benefit. The POST /companies/{company_uuid}/company_benefits endpoint also requires a description which is a more specific description than the given one of the benefit. An example may be “Kaiser Permanente” or “Blue Cross/ Blue Shield”.

curl --request POST \
     --url https://api.gusto-demo.com/v1/companies/{company_uuid}/company_benefits \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <<COMPANY_API_TOKEN>>' \
     --header 'content-type: application/json' \
     --data '
{
     "active": true,
     "benefit_type": 1,
     "description": "Blue Cross/ Blue Shield",
     "responsible_for_employer_taxes": false,
     "responsible_for_employee_w2": false
}
'

const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/companies/{company_uuid}/company_benefits';
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer <<COMPANY_API_TOKEN>>'
  },
  body: JSON.stringify({
    active: true,
    benefit_id: 1,
    description: 'Blue Cross/ Blue Shield',
    responsible_for_employer_taxes: false,
    responsible_for_employee_w2: false
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

3. (Optional) Confirm benefit creation

You can always see what benefits a specific company has by using the GET /companies/{company_uuid}/company_benefits endpoint.

curl --request GET \
     --url 'https://api.gusto-demo.com/v1/companies/{company_uuid}/company_benefits?enrollment_count=true' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <<COMPANY_API_TOKEN>>'

const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/companies/{company_uuid}/company_benefits?enrollment_count=true';
const options = {
  method: 'GET',
  headers: {accept: 'application/json', authorization: 'Bearer <<COMPANY_API_TOKEN>>'}
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

4. (Optional) Add contribution exclusions

You can add contribution exclusions for 401(k) and Roth 401(k) company benefits. To do this:

Call the GET /company_benefits/{company_benefit_id}/contribution_exclusionsendpoint, which returns an array of contributions for the given company benefit.

For example the response might look like:

[
  {  
    "contribution_uuid": "b82e35c5-d7c6-4705-9e16-9f87499ade18",  
    "contribution_type": "Bonus",  
    "excluded": false  
  },  
  {  
    "contribution_uuid": "f5618c94-ed7d-4366-b2c4-ff05e430064f",  
    "contribution_type": "Cash Tips",  
    "excluded": false  
  },  
  {  
    "contribution_uuid": "60191999-004a-49d9-b163-630574433653",  
    "contribution_type": "Commission",  
    "excluded": false  
  },  
  {  
    "contribution_uuid": "75a7a827-1f2d-4d6f-94f2-514c1fc32b13",  
    "contribution_type": "Regular",  
    "excluded": false  
  },  
  {  
    "contribution_uuid": "eead3c7c-7964-4e3c-b609-670456127b09",  
    "contribution_type": "Life insurance imputed benefit",  
    "excluded": true  
  }  
]

Determine the contribution types you want to exclude or include from company contributions.

Call thePUT company_benefits/{company_benefit_id}/contribution_exclusions endpoint, which takes as body params the array of contribution types in the same structure as when you listed the company benefit’s contribution exclusions.

Set "excluded": true for contribution types you want to exclude and "excluded": false for contribution types you want included.

For example, your request might look like this:

curl --request PUT \
     --url https://api.gusto-demo.com/v1/company_benefits/company_benefit_id/contribution_exclusions \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "contribution_exclusions": [
    {
      "excluded": true,
      "contribution_type": "Bonus",
      "contribution_uuid": "b82e35c5-d7c6-4705-9e16-9f87499ade18"
    },
    {
      "excluded": false,
      "contribution_uuid": "f5618c94-ed7d-4366-b2c4-ff05e430064f",
      "contribution_type": "Cash Tips"
    }
  ]
}
'

5. Add benefits to employee

Once you have created the benefit at the company level, you can now give that benefit to an employee.

To give an employee a company benefit, create the benefit at the employee level using the POST employees/{employee_uuid}/employee_benefits endpoint.

When creating the benefit you will specify both the company contribution AND/OR the employee deduction amount. There are also several additional constraints and details that can be passed depending on the benefit.

curl --request POST \
     --url https://api.gusto-demo.com/v1/employees/{employee_uuid}/employee_benefits \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <<COMPANY_API_TOKEN>>' \
     --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"
}
'

const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/employees/{employee_uuid}/employee_benefits';
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer <<COMPANY_API_TOKEN>>'
  },
  body: JSON.stringify({
    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'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

Consider company contribution exclusions

Percentage-based company contributions are calculated as the [contribution percentage] * (the sum of all non-excluded contribution types).

Example

Let's say that you enroll an employee in a 401(k) benefit with a company contribution percentage of 10%. This employee earns pay of these types: regular, bonus, overtime, an imputed benefit, and time off pay, and there are company contribution exclusions for bonus and time off pay.

The company contributions would be 10% * (regular + overtime + imputed benefit).

Fixed amount contributions with exclusions

Fixed amount company contributions are calculated as the [contribution amount] - (the sum of the excluded contribution types).

📘
If you create an employee benefit with a fixed company contribution amount, it’s possible that the fixed amount will not be met depending on the contribution exclusions on that company benefit.

curl --request POST \
     --url https://api.gusto-demo.com/v1/employees/{employee_uuid}/employee_benefits \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <<COMPANY_API_TOKEN>>' \
     --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"
}
'

const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/employees/{employee_uuid}/employee_benefits';
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer <<COMPANY_API_TOKEN>>'
  },
  body: JSON.stringify({
    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'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));