Gusto

Returns scope and resource information associated with the current access token.

Get info about the current access token

Exchange a refresh token for a new access token.

The previous `refresh_token` will be revoked on the first usage of the new `access_token`.

The `expires_in` value is provided in seconds from when the `access_token` was generated.

Refresh access token

### Overview
The company provisioning API provides a way to create a Gusto company as part of your integration. When you successfully call the API, the API does the following:
* Creates a new company in Gusto.
* Creates a new user in Gusto.
* Makes the new user the primary payroll administrator of the new company.
* Sends a welcome email to the new user.
In the response, you will receive an account claim URL. Redirect the user to this URL to complete their account setup inside of Gusto

> 📘 Token Authentication
>
> This endpoint uses the [organization level api token and the Token scheme with HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/authentication#api-token-authentication).

Create a company

Get a company.         
The employees:read scope is required to return home_address and non-work locations.         
The company_admin:read scope is required to return primary_payroll_admin.         
The signatories:read scope is required to return primary_signatory.         

scope: `companies:read`

Get a company

Returns a list of the custom fields of the company. Useful when you need to know the schema of custom fields for an entire company

scope: `companies:read`

Get the custom fields of a company

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`

Create a company location

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`

Get company locations

Get a location

Update a location.

scope: `companies.write`

Update a location

Get minimum wages for a location

scope: `companies:read`

Get minimum wages for a location

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`

Get the pay schedules for a company

Get a pay schedule

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`

Get pay periods for a company

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`

Get termination pay periods for a company

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`

Get pay schedule assignments for a company

Create an employee.

scope: `employees:manage`

Create an employee

Get all of the employees, onboarding, active and terminated, for a given company.

scope: `employees:read`

Get employees of a company

Create a department

scope: `departments:write`

Create a department

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

scope: `departments:read`

Get all departments of a company

Get a department given the UUID

scope: `departments:read`


Get a department

Update a department

scope: `departments:write`

Update a department

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

scope: `departments:write`


Delete a department

Add employees and contractors to a department

scope: `departments:write`


Add people to a department

Remove employees and contractors from a department

scope: `departments:write`


Remove people from a department

Get an employee.

scope: `employees:read`


Get an employee

Update an employee.

scope: `employees:write`

Update an employee

Use this endpoint to delete an employee who is in onboarding. Deleting
an onboarded employee is not allowed. Please check out the Terminations api
if you need to terminate an onboarded employee.

scope: `employees:manage`

Delete an onboarding employee

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`

Create an employee termination

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`

Get terminations for an employee

Delete an employee termination.

scope: `employments:write`

Delete an employee termination

Update an employee termination

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

scope: `employments:write`

Create an employee rehire

Update an employee's rehire.

scope: `employments:write`

Update an employee rehire

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

scope: `employments:read`

Get an employee rehire

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

scope: `employments:write`

Delete an employee rehire

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

scope: `employments:read`

Get employment history for an employee

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`

Get an employee's 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`

Create an employee's home address

Get an employee's home address

Update an employee's home address

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

scope: `employees:write`

Delete an employee's home address

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`

Get an employee's work addresses

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

scope: `employees:manage`

Create an employee work address

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

scope: `employees:read`

Get an employee work address

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

scope: `employees:manage`

Update an employee work address

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

scope: `employees:manage`

Delete an employee's work address

Returns a list of the employee's custom fields.

scope: `employees:read`

Get an employee's custom fields

Create a job

Get all of the jobs that an employee holds.

scope: `jobs:read`

Get jobs for an employee

Get employee time off activities.

scope: `employee_time_off_activities:read`

Get employee time off activities

Get a job

Update a job

Deletes a specific job that an employee holds.

scope: `jobs:write`

Delete an individual job

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`

Get compensations for a job

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`

Create a compensation

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:read`


Get a compensation

Update a compensation

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`. This endpoint deletes a compensation for a job that hasn't been processed on payroll.

scope: `jobs:write`


Delete a compensation

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`

Create a custom earning type

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`

Get all earning types for a company

Update an earning type.

scope: `payrolls:write`

Update an earning type

Deactivate an earning type.

scope: `payrolls:write`

Deactivate an earning type

Create an individual or business contractor.

scope: `contractors:manage`

Create a contractor

Get all contractors, active and inactive, individual and business, for a company.

scope: `contractors:read`

Get contractors of a company

Get a contractor.

scope: `contractors:read`

Get a contractor

Update a contractor.

scope: `contractors:write`

> 🚧 Warning
>
> Watch out when changing a contractor's type (when the contractor is finished onboarding). Specifically, changing contractor type can be dangerous since Gusto won’t recognize and file two separate 1099s if they simply change from business to individual

Update a contractor

Create a webhook subscription to receive events of the specified subscription_types whenever there is a state change.

> 📘 Token Authentication
>
> This endpoint uses the [organization level api token and the Token scheme with HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/authentication#api-token-authentication).

scope: `webhook_subscriptions:write`

Create a webhook subscription

Returns all webhook subscriptions associated with the provided Partner API token.

> 📘 Token Authentication
>
> This endpoint uses the [organization level api token and the Token scheme with HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/authentication#api-token-authentication).

scope: `webhook_subscriptions:read`

List webhook subscriptions

Updates the Webhook Subscription associated with the provided UUID.

> 📘 Token Authentication
>
> This endpoint uses the [organization level api token and the Token scheme with HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/authentication#api-token-authentication).

scope: `webhook_subscriptions:write`


Update a webhook subscription

Returns the Webhook Subscription associated with the provided UUID.

> 📘 Token Authentication
>
> This endpoint uses the [organization level api token and the Token scheme with HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/authentication#api-token-authentication).

scope: `webhook_subscriptions:read`


Get a webhook subscription

Deletes the Webhook Subscription associated with the provided UUID.

> 📘 Token Authentication
>
> This endpoint uses the [organization level api token and the Token scheme with HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/authentication#api-token-authentication).

scope: `webhook_subscriptions:write`


Delete a webhook subscription

When a webhook subscription is created, a `verification_token` is POSTed to the registered webhook subscription URL. This `verify` endpoint needs to be called with `verification_token` before webhook events can be sent to the registered webhook URL.

Use the /v1/webhook_subscriptions/{webhook_subscription_uuid}/request_verification_token API to resend the `verification_token` to the Subscriber.

> 📘 Token Authentication
>
> This endpoint uses the [organization level api token and the Token scheme with HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/authentication#api-token-authentication).

scope: `webhook_subscriptions:write`


Verify the webhook subscription

Request that the webhook subscription `verification_token` be POSTed to the Subscription URL.

> 📘 Token Authentication
>
> This endpoint uses the [organization level api token and the Token scheme with HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/authentication#api-token-authentication).

scope: `webhook_subscriptions:read`


Request the webhook subscription verification_token

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`

Get all payrolls for a company

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`

Get a single payroll

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`

Update a payroll by ID

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`

Prepare a payroll for update

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`

Calculate accruing time off hours

Returns an object containing individual contractor payments, within a given time period, including totals.

scope: `payrolls:read`

Get contractor payments for a company

Returns a single contractor payments

scope: `payrolls:read`

Get a single contractor payment

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.

scope: `company_benefits:write`

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.

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

scope: `company_benefits:read`

Get benefits for a company

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 with_employee_benefits parameter with true value is passed, employee_benefits:read scope is required to return employee_benefits.

scope: `company_benefits:read`

Get a company benefit

Update a company benefit

The following must be true in order to delete a company benefit
  - There are no employee benefits associated with the company benefit
  - There are no payroll items associated with the company benefit
  - The benefit is not managed by a Partner or by Gusto (type must be 'External')

scope: `company_benefits:write`

Delete a company benefit

Returns all benefits supported by Gusto.

The benefit object in Gusto contains high level information about a particular benefit type and its tax considerations. When companies choose to offer a benefit, they are creating a Company Benefit object associated with a particular benefit.

scope: `benefits:read`

Get all benefits supported by Gusto

Returns a benefit supported by Gusto.

The benefit object in Gusto contains high level information about a particular benefit type and its tax considerations. When companies choose to offer a benefit, they are creating a Company Benefit object associated with a particular benefit.

scope: `benefits:read`

Get a supported benefit by ID

Returns summary benefit data for the requested company benefit id.

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

scope: `company_benefits:read`

Get company benefit summary by company benefit id.

Returns field requirements for the requested benefit type.

scope: `benefits:read`

Get benefit fields requirements by 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`

Create an employee benefit

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`

Get all benefits for an employee

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`

Get an employee benefit

Update an employee benefit

Delete an employee benefit

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

scope: `employee_benefits:write`

Create year-to-date benefit amounts from a different company

Garnishments, or employee deductions, are fixed amounts or percentages deducted from an employee’s pay. They can be deducted a specific number of times or on a recurring basis. Garnishments can also have maximum deductions on a yearly or per-pay-period bases. Common uses for garnishments are court-ordered payments for child support or back taxes. Some companies provide loans to their employees that are repaid via garnishments.

scope: `garnishments:write`

Create a garnishment

Garnishments, or employee deductions, are fixed amounts or percentages deducted from an employee’s pay. They can be deducted a specific number of times or on a recurring basis. Garnishments can also have maximum deductions on a yearly or per-pay-period bases. Common uses for garnishments are court-ordered payments for child support or back taxes. Some companies provide loans to their employees that are repaid via garnishments.

scope: `garnishments:read`

Get garnishments for an employee

Get a garnishment

Update a garnishment

Fetch all events, going back up to 30 days, that your partner application has the required scopes for. Note that a partner does NOT have to have verified webhook subscriptions in order to utilize this endpoint.

> 📘 Token Authentication
>
> This endpoint uses the [organization level api token and the Token scheme with HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/authentication#api-token-authentication).

scope: `events:read`

Get all events

Quickbooks

Rippling HR

BambooHR

Sage HR

ADP Workforce Now

Workable

Deel

Google Workspace

HiBob

Lightspeed R-Series

# Delete Employee

This scenario allows your application to delete a Employee from any external application. 
You will pass ID of the Employee you want to delete and Integration.app will handle the rest.

## How It Works

1. **Delete Employee API call**:
   - Call Integration.app REST API or SDK with ID of the Employee you want to delete and Integration.app will send the correct request to the external app.


Delete Employee

Deletes Employee in any external application

Personio

# Continuous Import of Employees to Your App

This scenario enables your application to continuously sync Employees from any external application to your app's API. It handles the initial import of Employees and keeps them synchronized when a Employee is created, updated, or deleted in the external application.

When receiving Employees data from the external application, the data is transformed into a format supported by your app's API. Additionally, if needed, your customers can customize the data mapping based on their specific external application setup.

## How It Works

1. **Initial Import**:
   - Perform the initial import by calling the Integration.app REST API or SDK in a loop from your code to retrieve data page by page.
   - Integration.app transforms the output into a consistent format compatible with your API, allowing you to save the data efficiently.

2. **Continuous Sync**:
   - Enable subscription via a single API or SDK call to continuously receive created, updated, or deleted events.
   - Integration.app manages all integration-specific logic, including subscribing to/unsubscribing from webhooks, custom polling of events, or performing periodic full syncs.
   - You will only receive the necessary events as real-time as supported by the external application's API.

Continuously Import Employees to my App

Import Employees and receive created/updated or deleted events

Gusto API Integration Profile

Configuration

How to set up Gusto application and get your Client ID and Client Secret

Create Gusto developer account

Create Organization

Generate Credentials

Configure the app parameters in the Integration.app platform

Testing

Supercharge your product integrations today