Create company benefits

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

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:

bash

{
  "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”.

bash

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
}
'

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.

bash

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>>'

4. (Optional) Add contribution exclusions

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

1. 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:

   bash

   [
     {  
       "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  
     }  
   ]
   

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

3. 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:

   bash

   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.

bash

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"
}
'

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.

---

Manage company bank accounts

Company forms