Compensations contain information on how much is paid out for a job. Jobs may have many compensations, but only one that is active. The current compensation is the one with the most recent effective_date. By default the API returns only the current compensation - see the include query parameter for retrieving all compensations.

Note: Currently the API does not support creating multiple compensations per job - creating a compensation with the same job_uuid as another will fail with a relevant error.

Use flsa_status to determine if an employee is eligible for overtime.

scope: jobs:read

Compensations contain information on how much is paid out for a job. Jobs may have many compensations, but only one that is active. The current compensation is the one with the most recent effective_date.

scope: jobs:write

Company locations represent all addresses associated with a company. These can be filing addresses, mailing addresses, and/or work locations; one address may serve multiple, or all, purposes.

Since all company locations are subsets of locations, retrieving or updating an individual record should be done via the locations endpoints.

scope: companies:read

Company locations represent all addresses associated with a company. These can be filing addresses, mailing addresses, and/or work locations; one address may serve multiple, or all, purposes.

Since all company locations are subsets of locations, retrieving or updating an individual record should be done via the locations endpoints.

scope: companies.write

Get a location.

scope: companies:read

Update a location.

scope: companies.write

Get minimum wages for a location

scope: companies:read

Upon receiving a notification webhook event, use this endpoint to fetch the notification’s details. The notification details include basic suggested content that can help you build notifications in your platform.

Note: partners are responsible for the delivery and any custom state management of notifications in their application. Refer to our partner notification guide for more details.

If the notification UUID is not found, the response will be 404 Not Found. If the notification’s supporting data is no longer valid, the response will be 422 Unprocessable Entity.

scope: notifications:read

Pay periods are the foundation of payroll. Compensation, time & attendance, taxes, and expense reports all rely on when they happened. To begin submitting information for a given payroll, we need to agree on the time period.

By default, this endpoint returns pay periods starting from 6 months ago to the date today. Use the start_date and end_date parameters to change the scope of the response. End dates can be up to 3 months in the future and there is no limit on start dates.

Starting in version ‘2023-04-01’, the eligible_employees attribute was removed from the response. The eligible employees for a payroll are determined by the employee_compensations returned from the payrolls#prepare endpoint.

scope: payrolls:read

When a payroll admin terminates an employee and selects “Dismissal Payroll” as the employee’s final payroll, their last pay period will appear on the list.

This endpoint returns the unprocessed pay periods for past and future terminated employees in a given company.

scope: payrolls:read

The pay schedule object in Gusto captures the details of when employees work and when they should be paid. A company can have multiple pay schedules.

scope: pay_schedules:read

If a company does not have any pay schedules, this endpoint will create a single pay schedule and assign it to all employees. This is a common use case during company onboarding.

If a company has an existing active pay schedule and want to support multiple pay schedules, this endpoint will create a pay schedule that is not assigned to any employee.

Be sure to check state laws to know what schedule is right for your customers.

This endpoints assigns employees to specified pay schedules based on the pay schedule type.

scope: pay_schedules:write

This endpoints returns the employee changes, including pay period and transition pay periods, for changing the pay schedule.

scope: pay_schedules:write

This endpoint returns the current pay schedule assignment for a company, with pay schedule and employee/department mappings depending on the pay schedule type.

scope: pay_schedules:read

Provides a preview of a pay schedule with the specified parameters

scope: pay_schedules:write

The pay schedule object in Gusto captures the details of when employees work and when they should be paid. A company can have multiple pay schedules.

scope: pay_schedules:read

Updates a pay schedule.

scope: pay_schedules:write

Get payment speed for the company and fast payment limit (1-day is only applicable to partners that opt in).

scope: company_payment_configs:read

Update payment speed and fast payment limit for a company. At least one of payment_speed or fast_payment_limit parameters is required. 1-day option is only applicable to partners that opt in.

scope: company_payment_configs:write

Returns all approved Payroll Reversals for a Company.

scope: payrolls:read

Returns a list of payrolls for a company. You can change the payrolls returned by updating the processing_status, payroll_types, start_date, & end_date params.

By default, will return processed, regular payrolls for the past 6 months.

Notes:

• Dollar amounts are returned as string representations of numeric decimals, are represented to the cent.
• end_date can be at most 3 months in the future and start_date and end_date can’t be more than 1 year apart.

scope: payrolls:read

Creates a new, unprocessed, off-cycle payroll.

off_cycle_reason

• External benefits and deductions will be included when the off_cycle_reason is set to Correction.
• All benefits and deductions are blocked when the off_cycle_reason is set to Bonus.

scope: payrolls:run

This endpoint allows you to delete an unprocessed payroll.

By default the payroll and associated data is deleted synchronously. To request an asynchronous delete, use the async=true query parameter. In both cases validation of ability to delete will be performed and an Unprocessable Entity error will be returned if the payroll is not able to be deleted. A successful synchronous delete will return 204/No Content. When a payroll has been enqueued for asynchronous deletion, 202/Accepted will be returned.

scope: payrolls:run

Returns a payroll. If payroll is calculated or processed, will return employee_compensations and totals.

Notes:

• Hour and dollar amounts are returned as string representations of numeric decimals.
• Hours are represented to the thousands place; dollar amounts are represented to the cent.
• Every eligible compensation is returned for each employee. If no data has yet be inserted for a given field, it defaults to “0.00” (for fixed amounts) or “0.000” (for hours ).
• When include parameter with benefits value is passed, employee_benefits:read scope is required to return benefits
  • Benefits containing PHI are only visible with the employee_benefits:read:phi scope

scope: payrolls:read

This endpoint allows you to update information for one or more employees for a specific unprocessed payroll. You can think of the unprocessed
payroll object as a template of fields that you can update. You cannot modify the structure of the payroll object through this endpoint, only values
of the fields included in the payroll. If you do not include specific employee compensations or fixed/hourly compensations in your request body, they
will not be removed from the payroll.

scope: payrolls:write

Performs calculations for taxes, benefits, and deductions for an unprocessed payroll. The calculated payroll details provide a preview of the actual values that will be used when the payroll is run.

This calculation is asynchronous and a successful request responds with a 202 HTTP status. To view the details of the calculated payroll, use the GET /v1/companies/{company_id}/payrolls/{payroll_id} endpoint with include=taxes,benefits,deductions params.
In v2023-04-01, show_calculation=true is no longer required.

If the company is blocked from running payroll due to issues like incomplete setup, missing information or other compliance issues, the response will be 422 Unprocessable Entity with a categorization of the blockers as described in the error responses.

Transitions a processed payroll back to the unprocessed state. A payroll can be canceled if it meets both criteria:

• processed is true
• Current time is earlier than 3:30pm PT on the payroll_deadline

scope: payrolls:run

This endpoint will build the payroll and get it ready for making updates. This includes adding/removing eligible employees from the Payroll and updating the check_date, payroll_deadline, and payroll_status_meta dates & times.

Notes:

• Will null out calculated_at & totals if a payroll has already been calculated.
• Will return the version param used for updating the payroll

scope: payrolls:write

Submits an unprocessed payroll to be calculated and run. This submission is asynchronous and a successful request responds with a 202 HTTP status. Upon success, transitions the payroll to the processed state.

If the company is blocked from running payroll due to issues like incomplete setup, missing information or other compliance issues, the response will be 422 Unprocessable Entity with a categorization of the blockers as described in the error responses.

scope: payrolls:run

Returns a list of reasons that prevent the company from running payrolls. See the payroll blockers guide for a complete list of reasons.

The list is empty if there are no payroll blockers.

scope: payrolls:run

Submits a $0 payroll for employees associated with the pay schedule to skip payroll. This submission is asynchronous and a successful request responds with a 202 HTTP status. Upon success, the payroll is transitioned to the processed state.

If the company is blocked from running payroll due to issues like incomplete setup, missing information or other compliance issues, the response will be 422 Unprocessable Entity with a categorization of the blockers as described in the error responses.

scope: payrolls:run

Get an employee’s pay stubs

scope: pay_stubs:read

Get an employee’s pay stub for the specified payroll. By default, an application/pdf response will be returned. No other content types are currently supported, but may be supported in the future.

scope: pay_stubs:read

This endpoint initiates the generation of employee checks for the payroll specified by payroll_id. A generation status and corresponding generated document request_uuid will be returned. Use the generated document GET endpoint with document_type: printable_payroll_checks and request_uuid to poll the check generation process and retrieve the generated check URL upon completion.

scope: generated_documents:write

Calculates gross up earnings for an employee’s payroll, given net earnings. This endpoint is only applicable to off-cycle unprocessed payrolls.

The gross up amount must then be mapped to the corresponding fixed compensation earning type to get the correct payroll amount. For example, for bonus off-cycles, the gross up amount should be set with the Bonus earning type in the payroll fixed_compensations field.

scope: payrolls:run

Returns a payroll receipt.

Notes:

• Hour and dollar amounts are returned as string representations of numeric decimals.
• Dollar amounts are represented to the cent.
• If no data has yet be inserted for a given field, it defaults to “0.00” (for fixed amounts).

scope: payrolls:read

Fetch all recovery cases for a company.

scope: recovery_cases:read

After resolving the underlying bank error, initiate a redebit for an open recovery case. This submission is asynchronous and a successful request responds with a 202 HTTP status.

It may take up to four business days for the ACH debit to process; in the meantime, the status of the recovery case will be in the initiated_redebit state. When funds are successfully redebited, the recovery case is transitioned to the recovered state.

If the company has exceeded maximum redebit attempts, or if the recovery case is not in a redebitable state, the response will be 422 Unprocessable Entity.

scope: recovery_cases:write

Returns company signatories. Currently we only support a single signatory per company.

scope: signatories:read

Create a company signatory with complete information.
A signatory can legally sign forms once the identity verification process is successful.

scope: signatories:manage

Create a signatory with minimal information. This signatory can be invited to provide more information through the PUT /v1/companies/{company_uuid}/signatories/{signatory_uuid} endpoint. This will start the identity verification process and allow the signatory to be verified to sign documents.

Delete a company signatory.

scope: signatories:manage

Update a signatory that has been either invited or created. If the signatory has been created with minimal information through the POST /v1/companies/{company_uuid}/signatories/invite endpoint, then the first update must contain all attributes specified in the request body in order to start the identity verification process.

scope: signatories:write

Returns objects describing the states that have tax requirements for the company

scope: company_tax_requirements:read

Get all tax requirements for a given state.

Metadata Examples

```json select
{
“type”: “select”,
“options”: [
{ “label”: “Semiweekly”, value: “Semi-weekly” },
{ “label”: “Monthly”, value: “Monthly” },
{ “label”: “Quarterly”, value: “Quarterly” },
]
}

```json radio
{
  "type": "radio",
  "options": [
    { "label": "No, we cannot reimburse",  value: false, short_label: "Not Reimbursable" },
    { "label": "Yes, we can reimburse",  value: true, short_label: "Reimbursable" },
  ]
}

```json account_number
{
“type”: “account_number”,
“mask”: “######-##’,
“prefix”: null
}

```json tax_rate
{
  "type": "tax_rate",
  "validation": {
    "type": "min_max",
    "min": "0.0004",
    "max": "0.081"
  }
}

scope: company_tax_requirements:read

Update State Tax Requirements

scope: company_tax_requirements:write

Get all time off policies for a company

scope: time_off_policies:read

Create a time off policy

scope: time_off_policies:write

Returns a list of accruing time off for each time off policy associated with the employee.

Factors affecting the accrued hours:

• the time off policy accrual method (whether they get pay per hour worked, per hour paid, with / without overtime, accumulate time off based on pay period / calendar year / anniversary)
• how many hours of work during this pay period
• how many hours of PTO / sick hours taken during this pay period (for per hour paid policies only)
• company pay schedule frequency (for per pay period)

If none of the parameters is passed in, the accrued time off hour will be 0.

scope: payrolls:read