GuidesAPI ReferenceChangelogAPI PolicyAPI StatusGusto Security
API Reference
v2023-09-01 is in the deprecation process and all prior versions have been deprecated. Click this banner to review our version upgrade guide.

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.

scope: employee_benefits:write

Path Params
string
required

The UUID of the company benefit

Body Params
array of objects
required

The list of employee benefits to create or update

employee_benefits*
Headers
string

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

Responses

Response body
array of objects
object
string

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

boolean
Defaults to true

Whether the employee benefit is active.

string
Defaults to 0.00

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

boolean
Defaults to false

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

string | null

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

object

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

boolean
Defaults to false

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

string | null

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

string | null

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.

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.

string

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

string | null

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

string | null
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.

unset reduces_taxable_income does_not_reduce_taxable_income

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.

string
Defaults to 0.00
deprecated

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

boolean
Defaults to false
deprecated

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.

string

The UUID of the employee to which the benefit belongs.

string

The UUID of the company benefit.

string
required

The UUID of the employee benefit.

404

Not Found

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

invalid_attribute_value, or the request fails due to an invalid_operation. See the Errors Categories guide for more details.

Language
Credentials