Get attributes relevant for an employee’s state taxes.

The data required to correctly calculate an employee’s state taxes varies by both home and work location. This API returns information about each question that must be answered grouped by state. Mostly commonly, an employee lives and works in the same state and will only have questions for a single state. The response contains metadata about each question, the type of answer expected, and the current answer stored in Gusto for that question.

Answers are represented by an array. Today, this array can only be empty or contain exactly one element, but is designed to allow for forward compatibility with effective-dated fields. Until effective dated answers are supported, the valid_from and valid_up_to must always be "2010-01-01" and null respectively.

About filing new hire reports

Payroll Admins are responsible for filing a new hire report for each Employee. The file_new_hire_report question will only be listed if:

• the employee.onboarding_status is one of the following:
  • admin_onboarding_incomplete
  • self_onboarding_awaiting_admin_review
• that employee’s work state requires filing a new hire report

scope: employee_state_taxes:read

Update attributes relevant for an employee’s state taxes.

As described for the GET endpoint, the answers must be supplied in the effective-dated format, but currently only a single answer will be accepted - valid_from and valid_up_to must be "2010-01-01" and null respectively.

scope: employee_state_taxes:write

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

scope: employees:read

Create an employee.

scope: employees:manage

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

Get an employee.

scope: employees:read

Update an employee.

scope: employees:write

Returns a list of the employee’s custom fields.

scope: employees:read

This endpoint is currently supported but will eventually be deprecated; please use /v1/employees/{employee_id}/onboarding_status instead.

Call this endpoint as the very last step of employee onboarding to complete their onboarding. When successful, the employee’s onboarded attribute will be updated to true, indicating that they can be included in company’s payrolls.

Description

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

scope: employees:read

onboarding_status

Admin-facilitated onboarding

| onboarding_status | Description |
|:——————|————:|
| admin_onboarding_incomplete | Admin needs to complete the full employee-onboarding. |
| onboarding_completed | Employee has been fully onboarded and verified. |

Employee self-onboarding

| onboarding_status | Description |
|:——————|————:|
| admin_onboarding_incomplete | Admin needs to enter basic information about the employee. |
| self_onboarding_pending_invite | Admin has the intention to invite the employee to self-onboard (e.g., marking a checkbox), but the system has not yet sent the invitation. |
| self_onboarding_invited | Employee has been sent an invitation to self-onboard. |
| self_onboarding_invited_started | Employee has started the self-onboarding process. |
| self_onboarding_invited_overdue | Employee’s start date has passed, and employee has still not completed self-onboarding. |
| self_onboarding_completed_by_employee | Employee has completed entering in their information. The status should be updated via API to “self_onboarding_awaiting_admin_review” from here, once the Admin has started reviewing. |
| self_onboarding_awaiting_admin_review | Admin has started to verify the employee’s information. |
| onboarding_completed | Employee has been fully onboarded and verified. |

onboarding_steps

scope: employees:manage

Updates an employee’s onboarding status.
Below is a list of valid onboarding status changes depending on the intended action to be performed on behalf of the employee.

Get employee time off activities.

scope: employee_time_off_activities:read

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.

scope: events:read

Get an external payroll for a given company.

scope: external_payrolls:read

Creates a new external payroll for the company.

scope: external_payrolls:write

Get tax liabilities from aggregate external payrolls for a company.

scope: external_payrolls:read

Update tax liabilities for a company.

scope: external_payrolls:write

Finalizes tax liabilities for a company. All external payrolls edit action will be disabled.

scope: external_payrolls:write

Delete an external payroll.

scope: external_payrolls:write

Get an external payroll for a given company.

scope: external_payrolls:read

Update an external payroll with a list of external payroll items

scope: external_payrolls:write

Get tax suggestions for an external payroll. Earnings and/or benefits
data must be saved prior to the calculation in order to retrieve accurate
tax calculation.

scope: external_payrolls:read

Fetches attributes relevant for a company’s federal taxes.

scope: company_federal_taxes:read

Updates attributes relevant for a company’s federal taxes.
This information is required is to onboard a company for use with Gusto Embedded Payroll.

scope: company_federal_taxes:write

Generate a link to access a pre-built workflow in Gusto white-label UI. For security, all generated flows will expire within 1 hour of inactivity or 24 hours from creation time, whichever comes first.

scope: flows:write

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

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

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

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

Get a generated document given the request_uuid. The response will include the generation request’s status and, if complete, the relevant document urls.

scope: generated_documents:read

Delete a company’s holiday pay policy

scope: holiday_pay_policies:write

Get a company’s holiday pay policy

scope: holiday_pay_policies:read

Create a holiday pay policy for a company

scope: holiday_pay_policies:write

Update a company’s holiday pay policy

scope: holiday_pay_policies:write

Add employees to a company’s holiday pay policy

scope: holiday_pay_policies:write

Remove employees from a company’s holiday pay policy

scope: holiday_pay_policies:write

Preview a company’s paid holidays

scope: holiday_pay_policies:read

Get industry selection for the company.

scope: companies:read

Update the company industry selection by passing in industry classification codes: NAICS code, SICS code and industry title. Our UI is leveraging Middesk API to determine industry classification codes.

scope: companies:write

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.

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

Retrieve data for active companies used to calculate invoices for Gusto Embedded Payroll. A company is considered active for an invoice period if they are an active partner managed company, have run payroll or created contractor payments since becoming a partner managed company, and are not suspended at any point during the invoice period. This endpoint forces pagination, with 100 results returned at a time. You can learn more about our pagination here: pagination guide

📘 Token Authentication

This endpoint uses the organization level api token and the Token scheme with HTTP Authorization header

scope: invoices: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. This endpoint deletes a compensation for a job that hasn’t been processed on payroll.

scope: jobs:write

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

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

Get all of the jobs that an employee holds.

scope: jobs:read

Create a job.

scope: jobs:write

Deletes a specific job that an employee holds.

scope: jobs:write

Get a job.

scope: jobs:read

Update a job.

scope: jobs:write