Update an employee benefit

put

https://api.gusto-demo.com/v1/employee_benefits/{employee_benefit_id}

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

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

scope: employee_benefits:write

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

employee_benefit_id

string

required

The UUID of the employee benefit.

Body Params

version

string

required

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

active

boolean

Whether the employee benefit is active.

employee_deduction

string

Defaults to 0.00

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

deduct_as_percentage

boolean

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

employee_deduction_annual_maximum

string | null

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

effective_date

date

The date the employee benefit will start.

expiration_date

date | null

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

contribution

object

An object representing the type and value of the company contribution.

elective

boolean

Defaults to false

Whether the company contribution is elective (aka "matching"). For tiered, elective_amount, and elective_percentage contribution types this is ignored and assumed to be true.

company_contribution_annual_maximum

string | null

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

limit_option

string | null

enum

Some benefits require additional information to determine their limit.

Family or Individual: Applicable to HSA benefit.

Joint Filing or Single or Married and Filing Separately: Applicable to Dependent Care FSA benefit.

Allowed:

catch_up

boolean

Defaults to false

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

coverage_amount

string | null

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

deduction_reduces_taxable_income

string | null

enum

Defaults to unset

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.

Allowed:

coverage_salary_multiplier

string

Defaults to 0.00

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_contribution

string

Defaults to 0.00

deprecated

The amount to be paid, per pay period, by the company.

contribute_as_percentage

boolean

Defaults to false

deprecated

Whether the company contribution amount should be treated as a percentage to be deducted from each payroll.

Headers

X-Gusto-API-Version

string

enum

Defaults to 2026-02-01

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

Allowed:

Responses

404

Not Found

The requested resource does not exist. Make sure the provided UUID is valid.

200Example response

422Unprocessable Entity This may happen when the body of your request contains errors such as invalid_attribute_value, or the request fails due to an invalid_operation. See the Errors Categories guide for more details.