v1

latestOpenAPI 3.1.02026-07-243113441.2 MB

Company Benefits

Bulk update employee benefits for a company benefit

Employee benefits represent an employee enrolled in a particular company benefit. It includes information specific to that employee's enrollment.

Create or update(if the employee is already enrolled in the company benefit previously) an employee benefit for the company benefit.

Benefits containing PHI are only visible to applications with the employee_benefits:read:phi scope.

When the application has the employee_benefits:write:benefit_type_limited data scope, the application can only create or update employee benefits for benefit types that are permitted for the application.

scope: employee_benefits:write

put/v1/company_benefits/{company_benefit_id}/employee_benefits

Path parameters

company_benefit_idstring required

The UUID of the company benefit

Headers

X-Gusto-API-Version'2026-06-15'

Determines the date-based API version associated with your API call. If none is provided, your application's minimum API version is used.

Request body

Response

Success

versionstring

The current version of the object. See the versioning guide for information on how to use this field.

activeboolean

Whether the employee benefit is active.

employee_deductionstring

The amount to be deducted, per pay period, from the employee's pay.

deduct_as_percentageboolean

Whether the employee deduction amount should be treated as a percentage to be deducted from each payroll.

employee_deduction_annual_maximumstring nullable

The maximum employee deduction amount per year. A null value signifies no limit.

electiveboolean

Whether the company contribution is elective (aka matching). For "tiered" contribution types, this is always true.

company_contribution_annual_maximumstring nullable

The maximum company contribution amount per year. A null value signifies no limit.

limit_optionstring nullable

Some benefits require additional information to determine their limit.

Family and Individual are applicable to HSA benefit.

Joint Filing or Single and Married and Filing Separately are applicable to Dependent Care FSA benefit.

catch_upboolean nullable

Whether the employee should use a benefit's "catch up" rate. Only Roth 401k and 401k benefits use this value for employees over 50.

retirement_loan_identifierstring nullable

Identifier for a 401(k) loan assigned by the 401(k) provider

coverage_amountstring nullable

The amount that the employee is insured for. Note: company contribution cannot be present if coverage amount is set.

deduction_reduces_taxable_income'unset' | 'reduces_taxable_income' | 'does_not_reduce_taxable_income' nullable

Whether the employee deduction reduces taxable income or not. Only valid for Group Term Life benefits. Note: when the value is not "unset", coverage amount and coverage salary multiplier are ignored.

coverage_salary_multiplierstring nullable

The coverage amount as a multiple of the employee's salary. Only applicable for Group Term Life benefits. Note: cannot be set if coverage amount is also set.

company_contributionstring

The amount to be paid, per pay period, by the company. This field will not appear for tiered contribution types.

contribute_as_percentageboolean

Whether the company_contribution value should be treated as a percentage to be added to each payroll. This field will not appear for tiered contribution types.

effective_datestring date

The date the employee benefit will start.

expiration_datestring date nullable

The date the employee benefit will expire. A null value indicates the benefit will not expire.

employee_uuidstring

The UUID of the employee to which the benefit belongs.

company_benefit_uuidstring

The UUID of the company benefit.

uuidstring required

The UUID of the employee benefit.