Contractors 2 endpoints

GET /v1/contractors/{contractor_uuid}/onboarding_status

Retrieves a contractor’s onboarding status. The data returned helps inform the required onboarding steps and respective completion status.

scope: contractors:read

onboarding_status

Admin-facilitated onboarding

| onboarding_status | Description |
|:——————|————:|
| admin_onboarding_incomplete | Admin needs to enter basic information about the contractor. |
| admin_onboarding_review | All information has been completed and admin needs to confirm onboarding. |
| onboarding_completed | Contractor has been fully onboarded and verified. |

Contractor self-onboarding

onboarding_status Description
admin_onboarding_incomplete Admin needs to enter basic information about the contractor.
self_onboarding_not_invited Admin has the intention to invite the contractor to self-onboard (e.g., marking a checkbox), but the system has not yet sent the invitation.
self_onboarding_invited Contractor has been sent an invitation to self-onboard.
self_onboarding_started Contractor has started the self-onboarding process.
self_onboarding_review Admin needs to review contractors’s entered information and confirm onboarding.
onboarding_completed Contractor has been fully onboarded and verified.

onboarding_steps

onboarding_steps Requirement(s) to be completed
basic_details Add individual contractor’s first name, last name, social security number or Business name and EIN depending on the contractor type
add_address Add contractor address.
compensation_details Add contractor compensation.
payment_details Set up contractor’s direct deposit or set to check.
sign_documents Contractor forms (e.g., W9) are generated & signed.
file_new_hire_report Contractor new hire report is generated.
operationId: Contractors_getOnboardingStatus

Parameters

Name In Required Type Description
contractor_uuid path optional string

The UUID of the contractor
X-Gusto-API-Version header optional 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

200

Example response.
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
GET /v1/contractors/{contractor_uuid}/onboarding_status
PUT /v1/contractors/{contractor_uuid}/onboarding_status

Updates a contractor’s onboarding status.

scope: contractors:write

Below is a list of valid onboarding status changes depending on the intended action to be performed on behalf of the contractor.

Action current onboarding_status new onboarding_status
Mark a contractor as self-onboarding admin_onboarding_incomplete self_onboarding_not_invited
Invite an employee to self-onboard admin_onboarding_incomplete or self_onboarding_not_invited self_onboarding_invited
Cancel an employee’s self-onboarding self_onboarding_invited or self_onboarding_not_invited admin_onboarding_incomplete
Review an employee’s self-onboarded info self_onboarding_started self_onboarding_review
Finish an employee’s onboarding admin_onboarding_incomplete or self_onboarding_review onboarding_completed
operationId: Contractors_changeOnboardingStatus

Parameters

Name In Required Type Description
contractor_uuid path optional string

The UUID of the contractor
X-Gusto-API-Version header optional string

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

application/json
schema ContractorsChangeOnboardingStatusRequest
Property Type Required
onboarding_status string required

Responses

200

Example response.
404

Not Found

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

Unprocessable 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.
PUT /v1/contractors/{contractor_uuid}/onboarding_status

Departments 7 endpoints

GET /v1/companies/{company_uuid}/departments

Get all of the departments for a given company with the employees and contractors assigned to that department.

scope: departments:read

operationId: Departments_getAllWithEmployees

Parameters

Name In Required Type Description
company_uuid path optional string

The UUID of the company
X-Gusto-API-Version header optional 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

200

List of departments
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
GET /v1/companies/{company_uuid}/departments
POST /v1/companies/{company_uuid}/departments

Create a department

scope: departments:write

operationId: Departments_createDepartment

Parameters

Name In Required Type Description
company_uuid path optional string

The UUID of the company
X-Gusto-API-Version header optional string

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

application/json
schema DepartmentsCreateDepartmentRequest
Property Type Required
title string optional

Responses

201

Department Object Example
404

Not Found

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

Unprocessable 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.
POST /v1/companies/{company_uuid}/departments
DELETE /v1/departments/{department_uuid}

Delete a department. You cannot delete a department until all employees and contractors have been removed.

scope: departments:write

operationId: Departments_deleteDepartment

Parameters

Name In Required Type Description
department_uuid path optional string

The UUID of the department
X-Gusto-API-Version header optional 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

204

No Content
404

Not Found

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

Unprocessable 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.
DELETE /v1/departments/{department_uuid}
GET /v1/departments/{department_uuid}

Get a department given the UUID

scope: departments:read

operationId: Departments_getDepartmentByUuid

Parameters

Name In Required Type Description
department_uuid path optional string

The UUID of the department
X-Gusto-API-Version header optional 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

200

Department Object Example
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
GET /v1/departments/{department_uuid}
PUT /v1/departments/{department_uuid}

Update a department

scope: departments:write

operationId: Departments_updateDepartment

Parameters

Name In Required Type Description
department_uuid path optional string

The UUID of the department
X-Gusto-API-Version header optional string

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

application/json
schema DepartmentsUpdateDepartmentRequest
Property Type Required
title string optional
version string required

Responses

200

Department Object Example
404

Not Found

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

Unprocessable 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.
PUT /v1/departments/{department_uuid}
PUT /v1/departments/{department_uuid}/add

Add employees and contractors to a department

scope: departments:write

operationId: Departments_addPeopleToDepartment

Parameters

Name In Required Type Description
department_uuid path optional string

The UUID of the department
X-Gusto-API-Version header optional string

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

application/json
schema DepartmentsAddPeopleToDepartmentRequest
Property Type Required
version string optional
employees array optional
└ uuid string optional
contractors array optional
└ uuid string optional

Responses

200

Department Object Example
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
PUT /v1/departments/{department_uuid}/add
PUT /v1/departments/{department_uuid}/remove

Remove employees and contractors from a department

scope: departments:write

operationId: Departments_removePeopleFromDepartment

Parameters

Name In Required Type Description
department_uuid path optional string

The UUID of the department
X-Gusto-API-Version header optional string

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

application/json
schema DepartmentsRemovePeopleFromDepartmentRequest
Property Type Required
version string optional
employees array optional
└ uuid string optional
contractors array optional
└ uuid string optional

Responses

200

Department Object Example
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
PUT /v1/departments/{department_uuid}/remove

Earningtypes 4 endpoints

GET /v1/companies/{company_id}/earning_types

A payroll item in Gusto is associated to an earning type to name the type of earning described by the payroll item.

Default Earning Type

Certain earning types are special because they have tax considerations. Those earning types are mostly the same for every company depending on its legal structure (LLC, Corporation, etc.)

Custom Earning Type

Custom earning types are all the other earning types added specifically for a company.

scope: payrolls:read

operationId: EarningTypes_getAll

Parameters

Name In Required Type Description
company_id path optional string

The UUID of the company
X-Gusto-API-Version header optional 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

200

Example response
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
GET /v1/companies/{company_id}/earning_types
POST /v1/companies/{company_id}/earning_types

Create a custom earning type.

If an inactive earning type exists with the same name, this will reactivate it instead of creating a new one.

scope: payrolls:write

operationId: EarningTypes_createCustomEarningType

Parameters

Name In Required Type Description
company_id path optional string

The UUID of the company
X-Gusto-API-Version header optional string

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

application/json
schema EarningTypesCreateCustomEarningTypeRequest
Property Type Required
name string required

Responses

201

Example response
404

Not Found

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

Unprocessable 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.
POST /v1/companies/{company_id}/earning_types
DELETE /v1/companies/{company_id}/earning_types/{earning_type_uuid}

Deactivate an earning type.

scope: payrolls:write

operationId: EarningTypes_deactivateType

Parameters

Name In Required Type Description
company_id path optional string

The UUID of the company
earning_type_uuid path optional string

The UUID of the earning type
X-Gusto-API-Version header optional 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

204

No Content
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
DELETE /v1/companies/{company_id}/earning_types/{earning_type_uuid}
PUT /v1/companies/{company_id}/earning_types/{earning_type_uuid}

Update an earning type.

scope: payrolls:write

operationId: EarningTypes_updateType

Parameters

Name In Required Type Description
company_id path optional string

The UUID of the company
earning_type_uuid path optional string

The UUID of the earning type
X-Gusto-API-Version header optional string

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

application/json
schema EarningTypesUpdateTypeRequest
Property Type Required
name string optional

Responses

200

Example response
404

Not Found

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

Unprocessable 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.
PUT /v1/companies/{company_id}/earning_types/{earning_type_uuid}

Employeeaddresses 10 endpoints

GET /v1/employees/{employee_id}/home_addresses

The home address of an employee is used to determine certain tax information about them. Addresses are geocoded on create and update to ensure validity.

Supports home address effective dating and courtesy withholding.

scope: employees:read

operationId: EmployeeAddresses_getHomeAddresses

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
X-Gusto-API-Version header optional 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

200

List of employee addresses
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
GET /v1/employees/{employee_id}/home_addresses
POST /v1/employees/{employee_id}/home_addresses

The home address of an employee is used to determine certain tax information about them. Addresses are geocoded on create and update to ensure validity.

Supports home address effective dating and courtesy withholding.

scope: employees:write

operationId: EmployeeAddresses_createHomeAddress

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
X-Gusto-API-Version header optional string

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

application/json
schema EmployeeAddressesCreateHomeAddressRequest
Property Type Required
zip string optional
city string optional
state string optional
street_1 string optional
street_2 string optional
effective_date string optional
courtesy_withholding boolean optional

Responses

200

Example response
404

Not Found

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

Unprocessable 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.
POST /v1/employees/{employee_id}/home_addresses
GET /v1/employees/{employee_id}/work_addresses

Returns a list of an employee’s work addresses. Each address includes its effective date and a boolean
signifying if it is the currently active work address.

scope: employees:read

operationId: EmployeeAddresses_listWorkAddresses

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
X-Gusto-API-Version header optional 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

200

List of employee work addresses
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
GET /v1/employees/{employee_id}/work_addresses
POST /v1/employees/{employee_id}/work_addresses

The work address of an employee describes when an employee began working at an associated company location.

scope: employees:manage

operationId: EmployeeAddresses_createWorkAddress

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
X-Gusto-API-Version header optional string

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

application/json
schema EmployeeAddressesCreateWorkAddressRequest
Property Type Required
location_uuid string optional
effective_date string optional

Responses

201

Example response
404

Not Found

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

Unprocessable 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.
POST /v1/employees/{employee_id}/work_addresses
DELETE /v1/home_addresses/{home_address_uuid}

Used for deleting an employee’s home address. Cannot delete the employee’s active home address.

scope: employees:write

operationId: EmployeeAddresses_deleteHome

Parameters

Name In Required Type Description
home_address_uuid path optional string

The UUID of the home address
X-Gusto-API-Version header optional 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

204

No Content
404

Not Found

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

Unprocessable 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.
DELETE /v1/home_addresses/{home_address_uuid}
GET /v1/home_addresses/{home_address_uuid}

The home address of an employee is used to determine certain tax information about them. Addresses are geocoded on create and update to ensure validity.

Supports home address effective dating and courtesy withholding.

scope: employees:read

operationId: EmployeeAddresses_getHomeAddress

Parameters

Name In Required Type Description
home_address_uuid path optional string

The UUID of the home address
X-Gusto-API-Version header optional 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

200

Example response
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
GET /v1/home_addresses/{home_address_uuid}
PUT /v1/home_addresses/{home_address_uuid}

The home address of an employee is used to determine certain tax information about them. Addresses are geocoded on create and update to ensure validity.

Supports home address effective dating and courtesy withholding.

scope: employees:write

operationId: EmployeeAddresses_updateHomeAddress

Parameters

Name In Required Type Description
home_address_uuid path optional string

The UUID of the home address
X-Gusto-API-Version header optional string

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

application/json
schema EmployeeAddressesUpdateHomeAddressRequest
Property Type Required
zip string optional
city string optional
state string optional
version string required
street_1 string optional
street_2 string optional
effective_date string optional
courtesy_withholding boolean optional

Responses

200

Example response
404

Not Found

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

Unprocessable 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.
PUT /v1/home_addresses/{home_address_uuid}
DELETE /v1/work_addresses/{work_address_uuid}

Used for deleting an employee’s work address. Cannot delete the employee’s active work address.

scope: employees:manage

operationId: EmployeeAddresses_deleteWorkAddress

Parameters

Name In Required Type Description
work_address_uuid path optional string

The UUID of the work address
X-Gusto-API-Version header optional 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

204

No Content
404

Not Found

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

Unprocessable 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.
DELETE /v1/work_addresses/{work_address_uuid}
GET /v1/work_addresses/{work_address_uuid}

The work address of an employee is used for payroll tax purposes.

scope: employees:read

operationId: EmployeeAddresses_getWorkAddress

Parameters

Name In Required Type Description
work_address_uuid path optional string

The UUID of the work address
X-Gusto-API-Version header optional 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

200

Example response
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
GET /v1/work_addresses/{work_address_uuid}
PUT /v1/work_addresses/{work_address_uuid}

The work address of an employee is used for payroll tax purposes.

scope: employees:manage

operationId: EmployeeAddresses_updateWorkAddress

Parameters

Name In Required Type Description
work_address_uuid path optional string

The UUID of the work address
X-Gusto-API-Version header optional string

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

application/json
schema EmployeeAddressesUpdateWorkAddressRequest
Property Type Required
version string optional
location_uuid string optional
effective_date string optional

Responses

200

Example response
404

Not Found

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

Unprocessable 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.
PUT /v1/work_addresses/{work_address_uuid}

Employeebenefits 6 endpoints

DELETE /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.

scope: employee_benefits:write

operationId: EmployeeBenefits_deleteById

Parameters

Name In Required Type Description
employee_benefit_id path optional string

The UUID of the employee benefit.
X-Gusto-API-Version header optional 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

204

No Content
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
DELETE /v1/employee_benefits/{employee_benefit_id}
GET /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.

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

scope: employee_benefits:read

operationId: EmployeeBenefits_getEmployeeBenefitById

Parameters

Name In Required Type Description
employee_benefit_id path optional string

The UUID of the employee benefit.
X-Gusto-API-Version header optional 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

200

Example response
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
GET /v1/employee_benefits/{employee_benefit_id}
PUT /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.

scope: employee_benefits:write

operationId: EmployeeBenefits_updateBenefitRecord

Parameters

Name In Required Type Description
employee_benefit_id path optional string

The UUID of the employee benefit.
X-Gusto-API-Version header optional string

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

application/json
schema EmployeeBenefitsUpdateBenefitRecordRequest
Property Type Required
active boolean optional
version string required
catch_up boolean optional
elective boolean optional
contribution object optional
└ type string optional
└ value object optional
limit_option string optional
coverage_amount string optional
employee_deduction string optional
company_contribution string optional
deduct_as_percentage boolean optional
contribute_as_percentage boolean optional
coverage_salary_multiplier string optional
deduction_reduces_taxable_income string optional
employee_deduction_annual_maximum string optional
company_contribution_annual_maximum string optional

Responses

200

Example response
404

Not Found

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

Unprocessable 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.
PUT /v1/employee_benefits/{employee_benefit_id}
GET /v1/employees/{employee_id}/employee_benefits

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

Returns an array of all employee benefits for this employee

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

scope: employee_benefits:read

operationId: EmployeeBenefits_getAllForEmployee

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
page query optional number

The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.
per query optional number

Number of objects per page. For majority of endpoints will default to 25
X-Gusto-API-Version header optional 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

200

Example response
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
GET /v1/employees/{employee_id}/employee_benefits
POST /v1/employees/{employee_id}/employee_benefits

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

scope: employee_benefits:write

operationId: EmployeeBenefits_createBenefitRecord

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
X-Gusto-API-Version header optional string

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

application/json
schema EmployeeBenefitsCreateBenefitRecordRequest
Property Type Required
active boolean optional
catch_up boolean optional
elective boolean optional
contribution object optional
└ type string optional
└ value object optional
limit_option string optional
coverage_amount string optional
employee_deduction string optional
company_benefit_uuid string required
company_contribution string optional
deduct_as_percentage boolean optional
contribute_as_percentage boolean optional
coverage_salary_multiplier string optional
deduction_reduces_taxable_income string optional
employee_deduction_annual_maximum string optional
company_contribution_annual_maximum string optional

Responses

201

Example response
404

Not Found

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

Unprocessable 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.
POST /v1/employees/{employee_id}/employee_benefits
POST /v1/employees/{employee_id}/ytd_benefit_amounts_from_different_company

Year-to-date benefit amounts from a different company represents the amount of money added to an employee’s plan during a current year, made outside of the current contribution when they were employed at a different company.

This endpoint only supports passing outside contributions for 401(k) benefits.

scope: employee_benefits:write

operationId: EmployeeBenefits_createYtdBenefitAmountsFromDifferentCompany

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
X-Gusto-API-Version header optional string

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

application/json
schema EmployeeBenefitsCreateYtdBenefitAmountsFromDifferentCompanyRequest
Property Type Required
tax_year number required
benefit_type number optional
ytd_employee_deduction_amount string required
ytd_company_contribution_amount string required

Responses

204

No Content
404

Not Found

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

Unprocessable 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.
POST /v1/employees/{employee_id}/ytd_benefit_amounts_from_different_company

Employeeemployments 9 endpoints

GET /v1/employees/{employee_id}/employment_history

Retrieve the employment history for a given employee, which includes termination and rehire.

scope: employments:read

operationId: EmployeeEmployments_getHistory

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
X-Gusto-API-Version header optional 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

200

Example response
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
GET /v1/employees/{employee_id}/employment_history
DELETE /v1/employees/{employee_id}/rehire

Delete an employee rehire. An employee rehire cannot be deleted if it’s active (past effective date).

scope: employments:write

operationId: EmployeeEmployments_removeRehire

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
X-Gusto-API-Version header optional 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

204

No Content
404

Not Found

  • The requested resource does not exist. Make sure the provided ID/UUID is valid.
  • The employee’s employment is not in the right state.
DELETE /v1/employees/{employee_id}/rehire
GET /v1/employees/{employee_id}/rehire

Retrieve an employee’s rehire, which contains information on when the employee returns to work.

scope: employments:read

operationId: EmployeeEmployments_getRehire

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
X-Gusto-API-Version header optional 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

200

Example response
404

Not Found

  • The requested resource does not exist. Make sure the provided ID/UUID is valid.
  • The employee’s employment is not in the right state.
GET /v1/employees/{employee_id}/rehire
POST /v1/employees/{employee_id}/rehire

Rehire is created whenever an employee is scheduled to return to the company.

scope: employments:write

operationId: EmployeeEmployments_createRehire

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
X-Gusto-API-Version header optional string

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

application/json
schema Rehire-Body
Property Type Required
effective_date string required
employment_status string optional
work_location_uuid string required
file_new_hire_report boolean required
two_percent_shareholder boolean optional

Responses

201

Example response
404

Not Found

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

Unprocessable 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.
POST /v1/employees/{employee_id}/rehire
PUT /v1/employees/{employee_id}/rehire

Update an employee’s rehire.

scope: employments:write

operationId: EmployeeEmployments_updateRehire

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
X-Gusto-API-Version header optional string

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

application/json
schema EmployeeEmploymentsUpdateRehireRequest
Property Type Required
version string required
effective_date string required
employment_status string optional
work_location_uuid string required
file_new_hire_report boolean required
two_percent_shareholder boolean optional

Responses

200

Example response
404

Not Found

  • The requested resource does not exist. Make sure the provided ID/UUID is valid.
  • The employee’s employment is not in the right state.
422

Unprocessable 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.
PUT /v1/employees/{employee_id}/rehire
DELETE /v1/employees/{employee_id}/terminations

Delete an employee termination.

scope: employments:write

operationId: EmployeeEmployments_deleteTermination

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
X-Gusto-API-Version header optional 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

204

No Content
404

Not Found

  • The requested resource does not exist. Make sure the provided ID/UUID is valid.
  • The employee’s employment is not in the right state.
DELETE /v1/employees/{employee_id}/terminations
GET /v1/employees/{employee_id}/terminations

Terminations are created whenever an employee is scheduled to leave the company. The only things required are an effective date (their last day of work) and whether they should receive their wages in a one-off termination payroll or with the rest of the company.

Note that some states require employees to receive their final wages within 24 hours (unless they consent otherwise,) in which case running a one-off payroll may be the only option.

scope: employments:read

operationId: EmployeeEmployments_listEmployeeTerminations

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
X-Gusto-API-Version header optional 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

200

Example response
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
GET /v1/employees/{employee_id}/terminations
POST /v1/employees/{employee_id}/terminations

Terminations are created whenever an employee is scheduled to leave the company. The only things required are an effective date (their last day of work) and whether they should receive their wages in a one-off termination payroll or with the rest of the company.

Note that some states require employees to receive their final wages within 24 hours (unless they consent otherwise,) in which case running a one-off payroll may be the only option.

scope: employments:write

operationId: EmployeeEmployments_createTermination

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
X-Gusto-API-Version header optional string

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

application/json
schema EmployeeEmploymentsCreateTerminationRequest
Property Type Required
effective_date string required
run_termination_payroll boolean optional

Responses

201

Example Response
404

Not Found

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

Unprocessable 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.
POST /v1/employees/{employee_id}/terminations
PUT /v1/terminations/{employee_id}

Terminations are created whenever an employee is scheduled to leave the company. The only things required are an effective date (their last day of work) and whether they should receive their wages in a one-off termination payroll or with the rest of the company.

Note that some states require employees to receive their final wages within 24 hours (unless they consent otherwise,) in which case running a one-off payroll may be the only option.

scope: employments:write

operationId: EmployeeEmployments_updateTermination

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
X-Gusto-API-Version header optional string

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

application/json
schema EmployeeEmploymentsUpdateTerminationRequest
Property Type Required
version string required
effective_date string required
run_termination_payroll boolean optional

Responses

200

Example Response
404

Not Found

  • The requested resource does not exist. Make sure the provided ID/UUID is valid.
  • The employee’s employment is not in the right state.
422

Unprocessable 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.
PUT /v1/terminations/{employee_id}

Employeeforms 5 endpoints

GET /v1/employees/{employee_id}/forms

Get a list of all employee’s forms

scope: employee_forms:read

operationId: EmployeeForms_getAllEmployeeForms

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
X-Gusto-API-Version header optional 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

200

Example response
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
GET /v1/employees/{employee_id}/forms
GET /v1/employees/{employee_id}/forms/{form_id}

Get an employee form

scope: employee_forms:read

operationId: EmployeeForms_getFormById

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
form_id path optional string

The UUID of the form
X-Gusto-API-Version header optional 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

200

Example response
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
GET /v1/employees/{employee_id}/forms/{form_id}
GET /v1/employees/{employee_id}/forms/{form_id}/pdf

Get the link to the form PDF

scope: employee_forms:read

operationId: EmployeeForms_getPdfLink

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
form_id path optional string

The UUID of the form
X-Gusto-API-Version header optional 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

200

Example response
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
GET /v1/employees/{employee_id}/forms/{form_id}/pdf
PUT /v1/employees/{employee_id}/forms/{form_id}/sign

Sign a company form

scope: employee_forms:sign

operationId: EmployeeForms_signForm

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
form_id path optional string

The UUID of the form
X-Gusto-API-Version header optional string

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

application/json
schema EmployeeFormsSignFormRequest
Property Type Required
agree boolean required
signature_text string required
signed_by_ip_address string required

Responses

200

Example response
404

Not Found

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

Unprocessable 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.
PUT /v1/employees/{employee_id}/forms/{form_id}/sign
POST /v1/sandbox/generate_w2

🚧 Demo action

This action is only available in the Demo environment

Generates a W2 document for testing purposes.

scope: employees:write

operationId: EmployeeForms_generateW2Document

Parameters

Name In Required Type Description
X-Gusto-API-Version header optional string

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

application/json
schema EmployeeFormsGenerateW2DocumentRequest
Property Type Required
year integer optional
employee_id string required

Responses

200

OK
404

Not Found

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

Unprocessable 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.
POST /v1/sandbox/generate_w2

Employeepaymentmethod 5 endpoints

GET /v1/employees/{employee_id}/bank_accounts

Returns all employee bank accounts.

scope: employee_payment_methods:read

operationId: EmployeePaymentMethod_listBankAccounts

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
page query optional number

The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.
per query optional number

Number of objects per page. For majority of endpoints will default to 25
X-Gusto-API-Version header optional string

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

application/json
schema EmployeePaymentMethodListBankAccountsRequest

Responses

200

Example response
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
GET /v1/employees/{employee_id}/bank_accounts
POST /v1/employees/{employee_id}/bank_accounts

Creates an employee bank account. An employee can have multiple
bank accounts. Note that creating an employee bank account will also update
the employee’s payment method.

scope: employee_payment_methods:write

operationId: EmployeePaymentMethod_createBankAccount

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
X-Gusto-API-Version header optional string

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

application/json
schema EmployeePaymentMethodCreateBankAccountRequest
Property Type Required
name string required
account_type string required
account_number string required
routing_number string required

Responses

201

Example response
404

Not Found

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

Unprocessable 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.
POST /v1/employees/{employee_id}/bank_accounts
DELETE /v1/employees/{employee_id}/bank_accounts/{bank_account_uuid}

Deletes an employee bank account. To update an employee’s bank
account details, delete the bank account first and create a new one.

scope: employee_payment_methods:write

operationId: EmployeePaymentMethod_deleteBankAccount

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
bank_account_uuid path optional string

The UUID of the bank account
X-Gusto-API-Version header optional 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

204

No Content
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
DELETE /v1/employees/{employee_id}/bank_accounts/{bank_account_uuid}
GET /v1/employees/{employee_id}/payment_method

Fetches an employee’s payment method. An employee payment method
describes how the payment should be split across the employee’s associated
bank accounts.

scope: employee_payment_methods:read

operationId: EmployeePaymentMethod_getBankAccounts

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
X-Gusto-API-Version header optional 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

200

Example response
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
GET /v1/employees/{employee_id}/payment_method
PUT /v1/employees/{employee_id}/payment_method

Updates an employee’s payment method. Note that creating an employee
bank account will also update the employee’s payment method.

scope: employee_payment_methods:write

operationId: EmployeePaymentMethod_updatePaymentMethod

Parameters

Name In Required Type Description
employee_id path optional string

The UUID of the employee
X-Gusto-API-Version header optional string

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

application/json
schema EmployeePaymentMethodUpdatePaymentMethodRequest
Property Type Required
type string required
splits array optional
└ name string optional
└ uuid string optional
└ priority integer optional
└ split_amount integer optional
version string required
split_by string optional

Responses

200

Example response
404

Not Found

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

Unprocessable 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.
PUT /v1/employees/{employee_id}/payment_method

Employeetaxsetup 2 endpoints

GET /v1/employees/{employee_uuid}/federal_taxes

Get attributes relevant for an employee’s federal taxes.

scope: employee_federal_taxes:read

operationId: EmployeeTaxSetup_getFederalTaxesById

Parameters

Name In Required Type Description
employee_uuid path optional string

The UUID of the employee
X-Gusto-API-Version header optional 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

200

Example response
404

Not Found

The requested resource does not exist. Make sure the provided ID/UUID is valid.
GET /v1/employees/{employee_uuid}/federal_taxes
PUT /v1/employees/{employee_uuid}/federal_taxes

Update attributes relevant for an employee’s federal taxes.

scope: employee_federal_taxes:write

operationId: EmployeeTaxSetup_updateFederalTaxes

Parameters

Name In Required Type Description
employee_uuid path optional string

The UUID of the employee
X-Gusto-API-Version header optional string

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

application/json
schema EmployeeTaxSetupUpdateFederalTaxesRequest
Property Type Required
version string required
two_jobs boolean optional
deductions string optional
other_income string optional
w4_data_type string optional
filing_status string optional
dependents_amount string optional
extra_withholding string optional

Responses

200

Example response
404

Not Found

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

Unprocessable 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.
PUT /v1/employees/{employee_uuid}/federal_taxes
Load more endpoints