Sign in

v1

latestOpenAPI 3.1.02026-07-243113441.2 MB
Company Benefits

Create a company benefit

Company benefits represent the benefits that a company is offering to employees. This ties together a particular supported benefit with the company-specific information for the offering of that benefit.

Note that company benefits can be deactivated only when no employees are enrolled.

When the application has the company_benefits:write:benefit_type_limited data scope, the application can only create company benefits for benefit types that are permitted for the application.

scope: company_benefits:write

post/v1/companies/{company_id}/company_benefits

Path parameters

company_idstring required

The UUID of the company

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

benefit_typeinteger

The ID of the benefit to which the company benefit belongs.

activeboolean

Whether this benefit is active for employee participation.

descriptionstring required

The description of the company benefit.For example, a company may offer multiple benefits with an ID of 1 (for Medical Insurance). The description would show something more specific like "Kaiser Permanente" or "Blue Cross/ Blue Shield".

responsible_for_employer_taxesboolean

Whether the employer is subject to pay employer taxes when an employee is on leave. Only applicable to third party sick pay benefits.

responsible_for_employee_w2boolean

Whether the employer is subject to file W-2 forms for an employee on leave. Only applicable to third party sick pay benefits.

catch_up_type'elective' | 'deemed' nullable

The type of catch-up contribution for this benefit, as required by Section 603 of the SECURE 2.0 Act. Only applicable to pre-tax 401(k) and 403(b) benefits.

Response

Created

versionstring

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

enrollment_countinteger

The number of employees enrolled in the benefit, only returned when enrollment_count query param is set to true.

company_uuidstring

The UUID of the company.

uuidstring required

The UUID of the company benefit.

benefit_typeinteger

The type of the benefit to which the company benefit belongs.

activeboolean

Whether this benefit is active for employee participation. Company benefits may only be deactivated if no employees are actively participating.

descriptionstring

The description of the company benefit. For example, a company may offer multiple benefits with an ID of 1 (for Medical Insurance). The description would show something more specific like “Kaiser Permanente” or “Blue Cross/ Blue Shield”.

source'internal' | 'external' | 'partnered'

The source of the company benefit. This can be "internal", "external", or "partnered". Company benefits created via the API default to "external". Certain partners can create company benefits with a source of "partnered".

partner_namestring nullable

The partner name of the partner that created the company benefit. For example, "XYZ Corp".

deletableboolean

Whether this company benefit can be deleted. Deletable will be set to true if the benefit has not been used in payroll, has no employee benefits associated, and the benefit is not owned by Gusto or a Partner

supports_percentage_amountsboolean

Whether employee deductions and company contributions can be set as percentages of payroll for an individual employee. This is determined by the type of benefit and is not configurable by the company.

responsible_for_employer_taxesboolean

Whether the employer is subject to pay employer taxes when an employee is on leave. Only applicable to third party sick pay benefits.

responsible_for_employee_w2boolean

Whether the employer is subject to file W-2 forms for an employee on leave. Only applicable to third party sick pay benefits.

catch_up_type'elective' | 'deemed' nullable

The type of catch-up contribution for this benefit, as required by Section 603 of the SECURE 2.0 Act. Only applicable to pre-tax 401(k) and 403(b) benefits.