openapi: 3.0.0
info:
title: Gusto API
description: Welcome to Gusto's Embedded Payroll API documentation!
version: '2024-03-01'
termsOfService: https://gusto.com/about/terms/developer-terms-of-service
contact:
name: Developer Relations
email: developer@gusto.com
x-konfig-ignore:
object-with-no-properties: true
potential-incorrect-type: true
servers:
- description: Demo
url: https://api.gusto-demo.com
- description: Production
url: https://api.gusto.com
tags:
- name: Payrolls
- name: Companies
- name: Pay Schedules
- name: Employees
- name: Employee Addresses
- name: Jobs and Compensations
- name: Employee Employments
- name: Contractors
- name: Company Benefits
- name: External Payrolls
- name: Time Off Policies
- name: Contractor Payments
- name: Holiday Pay Policies
- name: Departments
- name: Webhooks
- name: Employee Benefits
- name: Locations
- name: Employee Payment Method
- name: Employee Forms
- name: Signatories
- name: Bank Accounts
- name: Employee Tax Setup
- name: Earning Types
- name: Contractor Payment Method
- name: Company Forms
- name: Garnishments
- name: Contractor Forms
- name: Tax Requirements
- name: Introspection
- name: Payment Configs
- name: Federal Tax Details
- name: Industry Selection
- name: Recovery Cases
- name: Flows
- name: Generated Documents
- name: Notifications
- name: Events
- name: Invoices
- name: ACH Transactions
paths:
/v1/token_info:
get:
tags:
- Introspection
summary: Get info about the current access token
operationId: Introspection_getCurrentAccessTokenInfo
description: >-
Returns scope and resource information associated with the current
access token.
parameters:
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
description: Example response
content:
application/json:
schema:
$ref: >-
#/components/schemas/IntrospectionGetCurrentAccessTokenInfoResponse
examples:
Example:
value:
scope: companies:read companies:write employees:read
resource:
type: Company
uuid: 5eca5127-6048-43ad-91ee-b56a0c34bc85
x-gusto-integration-type:
- embedded
- app-integrations
/oauth/token:
post:
tags:
- Introspection
summary: Refresh access token
operationId: Introspection_exchangeRefreshToken
security:
- ApiKeyAuth: []
description: >-
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.
parameters:
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IntrospectionExchangeRefreshTokenRequest'
responses:
'200':
$ref: '#/components/responses/Authentication-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/partner_managed_companies:
post:
tags:
- Companies
summary: Create a partner managed company
operationId: Companies_createPartnerManagedCompany
security:
- ApiKeyAuth: []
description: >-
Create a partner managed company. When you successfully call the API, it
does the following:
* Creates a new company in Gusto
* Creates a new user using the provided email if the user does not
already exist.
* Makes the user the primary payroll administrator of the new company.
In response, you will receive oauth access tokens for the created
company.
IMPORTANT: the returned access and refresh tokens are reserved for this
company only. They cannot be used to access other companies AND
previously granted tokens cannot be used to access this company.
> 📘 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#retrieving-access-tokens)
parameters:
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompaniesCreatePartnerManagedCompanyRequest'
examples:
Example:
value:
user:
first_name: Frank
last_name: Ocean
email: frank@example.com
phone: '2345558899'
company:
name: Frank's Ocean, LLC
trade_name: Frank’s Ocean
ein: '123456789'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: >-
#/components/schemas/CompaniesCreatePartnerManagedCompanyResponse
examples:
Example:
value:
access_token: >-
de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54
refresh_token: >-
8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1
company_uuid: d525dd21-ba6e-482c-be15-c2c7237f1364
expires_in: 7200
'401':
description: Authorization information is missing or invalid.
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_id}:
get:
tags:
- Companies
summary: Get a company
operationId: Companies_getCompany
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Company-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/partner_managed_companies/{company_uuid}/migrate:
put:
tags:
- Companies
summary: Migrate company to embedded payroll
operationId: Companies_migrateToEmbeddedPayroll
description: >-
Migrate an existing Gusto customer to your embedded payroll product.
To use this endpoint, the customer will need to connect their Gusto
account to your application using
[OAuth2](https://docs.gusto.com/embedded-payroll/docs/oauth2) then view
and [accept the Embedded Payroll Terms of
Service](https://docs.gusto.com/embedded-payroll/reference/post-partner-managed-companies-company_uuid-accept_terms_of_service).
scope: `partner_managed_companies:write`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompaniesMigrateToEmbeddedPayrollRequest'
responses:
'200':
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/CompaniesMigrateToEmbeddedPayrollResponse'
examples:
Example:
value:
company_uuid: 39abf9b9-650b-4e67-89a0-389dc6ee8a71
migration_status: true
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/partner_managed_companies/{company_uuid}/accept_terms_of_service:
post:
tags:
- Companies
summary: Accept terms of service for a company user
operationId: Companies_acceptTermsOfService
description: >-
Accept the Gusto Embedded Payroll's [Terms of
Service](https://flows.gusto.com/terms).
The user must have a role in the company in order to accept the Terms of
Service.
scope: `terms_of_services:write`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompaniesAcceptTermsOfServiceRequest'
responses:
'200':
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/CompaniesAcceptTermsOfServiceResponse'
examples:
Example:
value:
latest_terms_accepted: true
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/partner_managed_companies/{company_uuid}/retrieve_terms_of_service:
post:
tags:
- Companies
summary: Retrieve terms of service status for a company user
operationId: Companies_getTermsOfServiceStatus
description: >-
Retrieve the user acceptance status of the Gusto Embedded Payroll's
[Terms of Service](https://flows.gusto.com/terms).
scope: `terms_of_services:read`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompaniesGetTermsOfServiceStatusRequest'
responses:
'200':
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/CompaniesGetTermsOfServiceStatusResponse'
examples:
Example:
value:
latest_terms_accepted: true
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/invoices/{invoice_period}:
get:
tags:
- Invoices
summary: Retrieve invoicing data for companies
operationId: Invoices_getInvoicingDataForCompanies
security:
- ApiKeyAuth: []
description: >-
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](https://docs.gusto.com/embedded-payroll/docs/pagination)
> 📘 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#retrieving-access-tokens)
scope: `invoices:read`
parameters:
- $ref: '#/components/parameters/invoice_period'
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perParam'
- description: >-
Filter companies returned in the active_companies response, will
return an error if company not active during provided invoice
period. i.e.
`?company_uuids=781922d8-e780-4b6b-bf74-ee303166d022,bbbca930-7322-491c-ba7f-98707a52a9c5`
schema:
type: string
in: query
name: company_uuids
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Invoice-Data-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_id}/federal_tax_details:
get:
tags:
- Federal Tax Details
summary: Get Federal Tax Details
operationId: FederalTaxDetails_getAttributes
description: |-
Fetches attributes relevant for a company's federal taxes.
scope: `company_federal_taxes:read`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Federal-Tax-Details-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
put:
tags:
- Federal Tax Details
summary: Update Federal Tax Details
operationId: FederalTaxDetails_updateAttributes
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: >-
Attributes related to federal tax details that can be updated via this
endpoint include:
content:
application/json:
schema:
$ref: '#/components/schemas/FederalTaxDetailsUpdateAttributesRequest'
examples:
Example:
value:
version: 6cb95e00540706ca48d4577b3c839fbe
tax_payer_type: LLP
taxable_as_scorp: false
filing_form: '944'
has_ein: true
ein_verified: false
legal_name: Acme Corp.
responses:
'200':
$ref: '#/components/responses/Federal-Tax-Details-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_id}/industry_selection:
get:
tags:
- Industry Selection
summary: Get a company industry selection
operationId: IndustrySelection_getCompanyIndustrySelection
description: |-
Get industry selection for the company.
scope: `companies:read`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Industry-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
put:
tags:
- Industry Selection
summary: Update a company industry selection
operationId: IndustrySelection_updateCompanyIndustrySelection
description: >-
Update the company industry selection by passing in industry
classification codes: [NAICS code](https://www.naics.com), [SICS
code](https://siccode.com/) and industry title. Our UI is leveraging
[Middesk API](https://docs.middesk.com/reference/introduction) to
determine industry classification codes.
scope: `companies:write`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/IndustrySelectionUpdateCompanyIndustrySelectionRequest
examples:
Example:
value:
title: Computer Training
naics_code: '611420'
sic_codes:
- '8243'
responses:
'200':
$ref: '#/components/responses/Industry-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_id}/admins:
post:
tags:
- Companies
summary: Create an admin for the company
operationId: Companies_createAdmin
description: >-
Creates a new admin for a company.
If the email matches an existing user, this will create an admin account
for the current user. Otherwise, this will create a new user.
scope: `company_admin:write`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompaniesCreateAdminRequest'
examples:
Example:
value:
first_name: John
last_name: Smith
email: jsmith99@gmail.com
responses:
'200':
$ref: '#/components/responses/Admin-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
get:
tags:
- Companies
summary: Get all the admins at a company
operationId: Companies_getAllAdmins
description: |-
Returns a list of all the admins at a company
scope: `company_admin:read`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perParam'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Admin-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/signatories:
post:
tags:
- Signatories
summary: Create a signatory
operationId: Signatories_createSignatoryWithCompleteInformation
description: >-
Create a company signatory with complete information.
A signatory can legally sign forms once the identity verification
process is successful.
scope: `signatories:manage`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/SignatoriesCreateSignatoryWithCompleteInformationRequest
responses:
'201':
$ref: '#/components/responses/Signatory-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
get:
tags:
- Signatories
summary: Get all company signatories
operationId: Signatories_getCompanySignatories
description: >-
Returns company signatories. Currently we only support a single
signatory per company.
scope: `signatories:read`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Signatory-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/signatories/invite:
post:
tags:
- Signatories
summary: Invite a signatory
operationId: Signatories_createInvite
description: >-
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.
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SignatoriesCreateInviteRequest'
responses:
'201':
$ref: '#/components/responses/Signatory-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/signatories/{signatory_uuid}:
put:
tags:
- Signatories
summary: Update a signatory
operationId: Signatories_update
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/signatory_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SignatoriesUpdateRequest'
responses:
'200':
$ref: '#/components/responses/Signatory-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
delete:
tags:
- Signatories
summary: Delete a signatory
operationId: Signatories_deleteSignatory
description: |-
Delete a company signatory.
scope: `signatories:manage`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/signatory_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'204':
description: No Content
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/onboarding_status:
get:
tags:
- Companies
summary: Get the company's onboarding status
operationId: Companies_getOnboardingStatus
description: >-
Get company's onboarding status.
The data returned helps inform the required onboarding steps and
respective completion status.
scope: `company_onboarding_status:read`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Company-Onboarding-Status-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/finish_onboarding:
put:
tags:
- Companies
summary: Finish company onboarding
operationId: Companies_finishOnboarding
description: >-
Finalize a given company's onboarding process.
### Approve a company in demo
After a company is finished onboarding, Gusto requires an additional
step to review and approve that company.
In production environments, this step is required for risk-analysis
purposes.
We provide the endpoint `PUT '/v1/companies/{company_uuid}/approve'` to
facilitate company approvals in the demo environment.
```shell
PUT '/v1/companies/89771af8-b964-472e-8064-554dfbcb56d9/approve'
# Response: Company object, with company_status: 'Approved'
```
scope: `companies:write`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Company-Onboarding-Status-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_id}/custom_fields:
get:
tags:
- Companies
summary: Get the custom fields of a company
operationId: Companies_getCustomFields
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perParam'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Company-Custom-Field-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/companies/{company_uuid}/flows:
post:
tags:
- Flows
summary: Create a flow
operationId: Flows_generateLink
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FlowsGenerateLinkRequest'
examples:
Example:
value:
flow_type: company_onboarding
responses:
'201':
$ref: '#/components/responses/Flow-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_id}/locations:
post:
tags:
- Locations
summary: Create a company location
operationId: Locations_createCompanyLocation
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: Create a company location.
content:
application/json:
schema:
$ref: '#/components/schemas/LocationsCreateCompanyLocationRequest'
examples:
Example:
value:
phone_number: '8009360383'
street_1: 425 2nd Street
street_2: Suite 602
city: San Francisco
state: CA
zip: '94107'
country: USA
application/xml:
schema:
$ref: '#/components/schemas/LocationsCreateCompanyLocationRequest1'
examples:
Example:
value:
phone_number: '8009360383'
street_1: 425 2nd Street
street_2: Suite 602
city: San Francisco
state: CA
zip: '94107'
country: USA
responses:
'201':
$ref: '#/components/responses/Location-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
get:
tags:
- Locations
summary: Get company locations
operationId: Locations_getCompanyLocations
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perParam'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Location-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/locations/{location_id}:
get:
tags:
- Locations
summary: Get a location
operationId: Locations_getById
description: |-
Get a location.
scope: `companies:read`
parameters:
- $ref: '#/components/parameters/location_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Location-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
put:
tags:
- Locations
summary: Update a location
operationId: Locations_updateLocation
description: |-
Update a location.
scope: `companies.write`
parameters:
- $ref: '#/components/parameters/location_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: Update a location
content:
application/json:
schema:
$ref: '#/components/schemas/LocationsUpdateLocationRequest'
examples:
Example:
value:
version: 1928d0c378e519e9c03fb959bc959a6b
phone_number: '8009360383'
street_1: 425 2nd Street
street_2: Suite 602
city: San Francisco
state: CA
zip: '94107'
country: USA
responses:
'200':
$ref: '#/components/responses/Location-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/locations/{location_uuid}/minimum_wages:
get:
tags:
- Locations
summary: Get minimum wages for a location
operationId: Locations_getMinimumWages
description: |-
Get minimum wages for a location
scope: `companies:read`
parameters:
- $ref: '#/components/parameters/location_uuid'
- $ref: '#/components/parameters/effective_date'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Minimum-Wage-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/companies/{company_id}/bank_accounts:
post:
tags:
- Bank Accounts
summary: Create a company bank account
operationId: BankAccounts_createVerificationDeposits
description: >-
This endpoint creates a new company bank account.
Upon being created, two verification deposits are automatically sent to
the bank account, and the bank account's verification_status is
'awaiting_deposits'.
When the deposits are successfully transferred, the verification_status
changes to 'ready_for_verification', at which point the verify endpoint
can be used to verify the bank account.
After successful verification, the bank account's verification_status is
'verified'.
scope: `company_bank_accounts:write`
> 🚧 Warning
>
> If a default bank account exists, it will be disabled and the new bank
account will replace it as the company's default funding method.
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/BankAccountsCreateVerificationDepositsRequest
examples:
Example:
value:
routing_number: '115092013'
account_type: Checking
account_number: '9775014007'
responses:
'201':
$ref: '#/components/responses/Company-Bank-Account-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
get:
tags:
- Bank Accounts
summary: Get all company bank accounts
operationId: BankAccounts_listCompanyBankAccounts
description: >-
Returns company bank accounts. Currently, we only support a single
default bank account per company.
scope: `company_bank_accounts:read`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Company-Bank-Account-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_id}/bank_accounts/{bank_account_uuid}/verify:
put:
tags:
- Bank Accounts
summary: Verify a company bank account
operationId: BankAccounts_verifyMicroDeposits
description: >-
Verify a company bank account by confirming the two micro-deposits sent
to the bank account. Note that the order of the two deposits specified
in request parameters does not matter. There's a maximum of 5
verification attempts, after which we will automatically initiate a new
set of micro-deposits and require the bank account to be verified with
the new micro-deposits.
### Bank account verification in demo
We provide the endpoint `POST
'/v1/companies/{company_id}/bank_accounts/{bank_account_uuid}/send_test_deposits'`
to facilitate bank account verification in the demo environment. This
endpoint simulates the micro-deposits transfer and returns them in the
response. You can call this endpoint as many times as you wish to
retrieve the values of the two micro deposits.
```
POST '/v1/companies/89771af8-b964-472e-8064-554dfbcb56d9/bank_accounts/ade55e57-4800-4059-9ecd-fa29cfeb6dd2/send_test_deposits'
{
"deposit_1": 0.02,
"deposit_2": 0.42
}
```
scope: `company_bank_accounts:write`
parameters:
- $ref: '#/components/parameters/bank_account_uuid'
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccountsVerifyMicroDepositsRequest'
examples:
Example:
value:
deposit_1: 0.02
deposit_2: 0.42
responses:
'200':
$ref: '#/components/responses/Company-Bank-Account-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/external_payrolls:
post:
tags:
- External Payrolls
summary: Create a new external payroll for a company
operationId: ExternalPayrolls_createNewPayroll
description: |-
Creates a new external payroll for the company.
scope: `external_payrolls:write`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalPayrollsCreateNewPayrollRequest'
examples:
Example:
value:
check_date: '2022-06-01'
payment_period_start_date: '2022-05-15'
payment_period_end_date: '2022-05-30'
responses:
'200':
$ref: '#/components/responses/External-Payroll-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
get:
tags:
- External Payrolls
summary: Get external payrolls for a company
operationId: ExternalPayrolls_listForCompany
description: |-
Get an external payroll for a given company.
scope: `external_payrolls:read`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/External-Payroll-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/external_payrolls/{external_payroll_id}:
get:
tags:
- External Payrolls
summary: Get an external payroll
operationId: ExternalPayrolls_getById
description: |-
Get an external payroll for a given company.
scope: `external_payrolls:read`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/external_payroll_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/External-Payroll-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
delete:
tags:
- External Payrolls
summary: Delete an external payroll
operationId: ExternalPayrolls_deletePayroll
description: |-
Delete an external payroll.
scope: `external_payrolls:write`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/external_payroll_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'204':
description: No Content
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
put:
tags:
- External Payrolls
summary: Update an external payroll
operationId: ExternalPayrolls_updatePayrollItems
description: |-
Update an external payroll with a list of external payroll items
scope: `external_payrolls:write`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/external_payroll_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalPayrollsUpdatePayrollItemsRequest'
examples:
Example:
value:
replace_fields: true
external_payroll_items:
- employee_uuid: 403c6ee3-5f58-40ef-a117-ff7175cd9ee3
earnings:
- hours: '0.0'
amount: '200.00'
earning_type: CompanyPayType
earning_id: 1
- hours: '0.0'
amount: '5000.00'
earning_type: CompanyEarningType
earning_id: 2
benefits:
- company_contribution_amount: '300.0'
employee_deduction_amount: '300.0'
benefit_id: 10
- company_contribution_amount: '50.0'
employee_deduction_amount: '100.0'
benefit_id: 21
taxes:
- amount: '20.0'
tax_id: 1
- amount: '100.0'
tax_id: 2
responses:
'200':
$ref: '#/components/responses/External-Payroll-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/external_payrolls/{external_payroll_id}/calculate_taxes:
get:
tags:
- External Payrolls
summary: Get tax suggestions for an external payroll
operationId: ExternalPayrolls_getTaxSuggestions
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/external_payroll_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/External-Payroll-Tax-Suggestions-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/external_payrolls/tax_liabilities:
get:
tags:
- External Payrolls
summary: Get tax liabilities
operationId: ExternalPayrolls_getTaxLiabilities
description: |-
Get tax liabilities from aggregate external payrolls for a company.
scope: `external_payrolls:read`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Tax-Liabilities-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
put:
tags:
- External Payrolls
summary: Update tax liabilities
operationId: ExternalPayrolls_updateTaxLiabilities
description: |-
Update tax liabilities for a company.
scope: `external_payrolls:write`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalPayrollsUpdateTaxLiabilitiesRequest'
examples:
Example:
value:
liability_selections:
- tax_id: 1
last_unpaid_external_payroll_uuid: 7985032c-ee3a-4e98-af27-d56551eb5f1c
unpaid_liability_amount: 50
- tax_id: 2
last_unpaid_external_payroll_uuid: 5ed14dbb-958f-47c8-b16e-c4fed82dc486
unpaid_liability_amount: 400
- tax_id: 8
last_unpaid_external_payroll_uuid: null
unpaid_liability_amount: 0
responses:
'200':
$ref: '#/components/responses/Tax-Liabilities-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/external_payrolls/tax_liabilities/finish:
put:
tags:
- External Payrolls
summary: Finalize tax liabilities options and convert into processed payrolls
operationId: ExternalPayrolls_finalizeTaxLiabilities
description: >-
Finalizes tax liabilities for a company. All external payrolls edit
action will be disabled.
scope: `external_payrolls:write`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'202':
description: Accepted
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/payment_configs:
get:
tags:
- Payment Configs
summary: Get a company's payment configs
operationId: PaymentConfigs_getCompanyPaymentConfigs
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Payment-Configs-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
put:
tags:
- Payment Configs
summary: Update a company's payment configs
operationId: PaymentConfigs_updateCompanyPaymentConfigs
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/PaymentConfigsUpdateCompanyPaymentConfigsRequest
examples:
Example:
value:
fast_payment_limit: '5000'
payment_speed: 2-day
responses:
'200':
$ref: '#/components/responses/Payment-Configs-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_id}/pay_schedules:
post:
tags:
- Pay Schedules
summary: Create a new pay schedule
operationId: PaySchedules_createNew
description: >-
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](https://www.dol.gov/agencies/whd/state/payday)** to know what
schedule is right for your customers.
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaySchedulesCreateNewRequest'
examples:
Example:
value:
version: 68934a3e9455fa72420237eb05902327
frequency: Twice per month
anchor_pay_date: '2021-10-15'
anchor_end_of_pay_period: '2021-10-15'
day_1: 15
day_2: 31
custom_name: demo pay schedule
auto_pilot: false
responses:
'200':
$ref: '#/components/responses/Pay-Schedule-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
get:
tags:
- Pay Schedules
summary: Get the pay schedules for a company
operationId: PaySchedules_listForCompany
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perParam'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Pay-Schedule-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/companies/{company_id}/pay_schedules/preview:
get:
tags:
- Pay Schedules
summary: Preview pay schedule dates
operationId: PaySchedules_previewPayScheduleDates
description: |-
Provides a preview of a pay schedule with the specified parameters
scope: `pay_schedules:write`
parameters:
- $ref: '#/components/parameters/company_id'
- description: >-
The frequency that employees on this pay schedule are paid with
Gusto.
name: frequency
in: query
schema:
type: string
enum:
- Every week
- Every other week
- Twice per month
- Monthly
- description: >-
The first date that employees on this pay schedule are paid with
Gusto.
name: anchor_pay_date
in: query
schema:
type: string
example: '2020-05-15'
- description: >-
The last date of the first pay period. This can be the same date as
the anchor pay date.
name: anchor_end_of_pay_period
in: query
schema:
type: string
example: '2020-05-08'
- description: >-
An integer between 1 and 31 indicating the first day of the month
that employees are paid. This field is only relevant for pay
schedules with the “Twice per month” and “Monthly” frequencies. It
will be null for pay schedules with other frequencies.
name: day_1
in: query
schema:
type: integer
required: false
- description: >-
An integer between 1 and 31 indicating the second day of the month
that employees are paid. This field is the second pay date for pay
schedules with the "Twice per month" frequency. For semi-monthly pay
schedules, set this field to 31. For months shorter than 31 days, we
will set the second pay date to the last day of the month. It will
be null for pay schedules with other frequencies.
name: day_2
in: query
schema:
type: integer
required: false
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: >-
#/components/schemas/PaySchedulesPreviewPayScheduleDatesResponse
examples:
Example:
value:
pay_periods:
- check_date: '2023-12-15'
end_date: '2023-12-31'
start_date: '2023-10-01'
run_payroll_by: '2023-12-13'
- check_date: '2024-03-15'
end_date: '2024-03-31'
start_date: '2024-01-01'
run_payroll_by: '2024-03-13'
- check_date: '2024-06-14'
end_date: '2024-06-30'
start_date: '2024-04-01'
run_payroll_by: '2024-06-12'
- check_date: '2024-09-13'
end_date: '2024-09-30'
start_date: '2024-07-01'
run_payroll_by: '2024-09-11'
holidays:
- '2023-10-09'
- '2023-11-11'
- '2023-11-23'
- '2023-12-25'
- '2024-01-01'
- '2024-01-15'
- '2024-02-19'
- '2024-05-27'
- '2024-06-19'
- '2024-07-04'
- '2024-09-02'
x-gusto-integration-type:
- embedded
/v1/companies/{company_id}/pay_schedules/{pay_schedule_id}:
get:
tags:
- Pay Schedules
summary: Get a pay schedule
operationId: PaySchedules_getDetails
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/pay_schedule_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Pay-Schedule-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
put:
tags:
- Pay Schedules
summary: Update a pay schedule
operationId: PaySchedules_updatePaySchedule
description: |-
Updates a pay schedule.
scope: `pay_schedules:write`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/pay_schedule_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaySchedulesUpdatePayScheduleRequest'
examples:
Example:
value:
version: 68934a3e9455fa72420237eb05902327
frequency: Twice per month
anchor_pay_date: '2021-10-15'
anchor_end_of_pay_period: '2021-10-15'
day_1: 15
day_2: 31
custom_name: demo pay schedule
auto_pilot: true
responses:
'200':
$ref: '#/components/responses/Pay-Schedule-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_id}/pay_periods:
get:
tags:
- Pay Schedules
summary: Get pay periods for a company
operationId: PaySchedules_getPayPeriods
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/start_date'
- $ref: '#/components/parameters/end_date'
- $ref: '#/components/parameters/payroll_types'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Pay-Period-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/companies/{company_id}/pay_periods/unprocessed_termination_pay_periods:
get:
tags:
- Pay Schedules
summary: Get termination pay periods for a company
operationId: PaySchedules_getUnprocessedTerminationPayPeriods
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Unprocessed-Termination-Pay-Period-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/companies/{company_id}/pay_schedules/assignments:
get:
tags:
- Pay Schedules
summary: Get pay schedule assignments for a company
operationId: PaySchedules_getAssignments
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Pay-Schedule-Assignment-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/companies/{company_id}/pay_schedules/assignment_preview:
post:
tags:
- Pay Schedules
summary: Preview pay schedule assignments for a company
operationId: PaySchedules_previewAssignmentsForCompany
description: >-
This endpoints returns the employee changes, including pay period and
transition pay periods, for changing the pay schedule.
scope: `pay_schedules:write`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Pay-Schedule-Assignment-Body'
examples:
Example:
value:
type: by_employee
employees:
employee_uuid: f0238368-f2cf-43e2-9a07-b0265f2cec69
pay_schedule_uuid: c277ac52-9871-4a96-a1e6-0c449684602a
responses:
'200':
$ref: '#/components/responses/Pay-Schedule-Assignment-Preview-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_id}/pay_schedules/assign:
post:
tags:
- Pay Schedules
summary: Assign pay schedules for a company
operationId: PaySchedules_assignEmployeesToSchedules
description: >-
This endpoints assigns employees to specified pay schedules based on the
pay schedule type.
scope: `pay_schedules:write`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Pay-Schedule-Assignment-Body'
examples:
Example:
value:
type: by_employee
employees:
employee_uuid: f0238368-f2cf-43e2-9a07-b0265f2cec69
pay_schedule_uuid: c277ac52-9871-4a96-a1e6-0c449684602a
responses:
'200':
description: No Content
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_id}/employees:
post:
tags:
- Employees
summary: Create an employee
operationId: Employees_createEmployee
description: |-
Create an employee.
scope: `employees:manage`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: Create an employee.
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeesCreateEmployeeRequest'
examples:
Example:
value:
first_name: Soren
middle_initial: A
last_name: Kierkegaard
date_of_birth: '1995-05-05'
email: knight0faith@example.com
ssn: '123456294'
responses:
'201':
$ref: '#/components/responses/Employee-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
get:
tags:
- Employees
summary: Get employees of a company
operationId: Employees_listCompanyEmployees
description: >-
Get all of the employees, onboarding, active and terminated, for a given
company.
scope: `employees:read`
parameters:
- $ref: '#/components/parameters/company_id'
- description: Filters employees by the provided boolean
schema:
type: boolean
in: query
name: terminated
- description: >-
Include the requested attribute(s) in each employee response,
multiple options are comma separated. Available options:
- all_compensations: Include all effective dated compensations for
each job instead of only the current compensation
- custom_fields: Include employees' custom fields
in: query
name: include
schema:
type: string
enum:
- all_compensations
- custom_fields
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perParam'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeesListCompanyEmployeesRequest'
responses:
'200':
$ref: '#/components/responses/Employee-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/companies/{company_uuid}/departments:
post:
tags:
- Departments
summary: Create a department
operationId: Departments_createDepartment
description: |-
Create a department
scope: `departments:write`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DepartmentsCreateDepartmentRequest'
examples:
Example:
value:
title: Stage Hand
responses:
'201':
$ref: '#/components/responses/Department-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
get:
tags:
- Departments
summary: Get all departments of a company
operationId: Departments_getAllWithEmployees
description: >-
Get all of the departments for a given company with the employees and
contractors assigned to that department.
scope: `departments:read`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Department-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/departments/{department_uuid}:
get:
tags:
- Departments
summary: Get a department
operationId: Departments_getDepartmentByUuid
description: |
Get a department given the UUID
scope: `departments:read`
parameters:
- $ref: '#/components/parameters/department_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Department-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
put:
tags:
- Departments
summary: Update a department
operationId: Departments_updateDepartment
description: |-
Update a department
scope: `departments:write`
parameters:
- $ref: '#/components/parameters/department_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DepartmentsUpdateDepartmentRequest'
examples:
Example:
value:
title: Backup Dancer
version: db0edd04aaac4506f7edab03ac855d56
responses:
'200':
$ref: '#/components/responses/Department-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
delete:
tags:
- Departments
summary: Delete a department
operationId: Departments_deleteDepartment
description: >
Delete a department. You cannot delete a department until all employees
and contractors have been removed.
scope: `departments:write`
parameters:
- $ref: '#/components/parameters/department_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'204':
description: No Content
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/departments/{department_uuid}/add:
put:
tags:
- Departments
summary: Add people to a department
operationId: Departments_addPeopleToDepartment
description: |
Add employees and contractors to a department
scope: `departments:write`
parameters:
- $ref: '#/components/parameters/department_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DepartmentsAddPeopleToDepartmentRequest'
responses:
'200':
$ref: '#/components/responses/Department-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/departments/{department_uuid}/remove:
put:
tags:
- Departments
summary: Remove people from a department
operationId: Departments_removePeopleFromDepartment
description: |
Remove employees and contractors from a department
scope: `departments:write`
parameters:
- $ref: '#/components/parameters/department_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/DepartmentsRemovePeopleFromDepartmentRequest
responses:
'200':
$ref: '#/components/responses/Department-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/employees/{employee_id}:
get:
tags:
- Employees
summary: Get an employee
operationId: Employees_getEmployeeById
description: |
Get an employee.
scope: `employees:read`
parameters:
- $ref: '#/components/parameters/employee_id'
- description: >-
Include the requested attribute(s) in each employee response,
multiple options are comma separated. Available options:
- all_compensations: Include all effective dated compensations for
each job instead of only the current compensation
- custom_fields: Include employees' custom fields
in: query
name: include
schema:
type: string
enum:
- all_compensations
- custom_fields
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Employee-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
put:
tags:
- Employees
summary: Update an employee
operationId: Employees_updateEmployee
description: |-
Update an employee.
scope: `employees:write`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: Update an employee.
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeesUpdateEmployeeRequest'
examples:
Example:
value:
version: db0edd04aaac4506f7edab03ac855d56
first_name: Soren
middle_initial: A
last_name: Kierkegaard
date_of_birth: '1995-05-05'
email: knight0faith@example.com
ssn: '123456294'
two_percent_shareholder: false
responses:
'200':
$ref: '#/components/responses/Employee-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
delete:
tags:
- Employees
summary: Delete an onboarding employee
operationId: Employees_deleteOnboardingEmployee
description: >-
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`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'204':
description: No Content
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/employees/{employee_id}/terminations:
post:
tags:
- Employee Employments
summary: Create an employee termination
operationId: EmployeeEmployments_createTermination
description: >-
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`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeEmploymentsCreateTerminationRequest'
examples:
Example:
value:
effective_date: '2020-06-30'
run_termination_payroll: true
responses:
'201':
$ref: '#/components/responses/Termination-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
get:
tags:
- Employee Employments
summary: Get terminations for an employee
operationId: EmployeeEmployments_listEmployeeTerminations
description: >-
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`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Termination-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
delete:
tags:
- Employee Employments
summary: Delete an employee termination
operationId: EmployeeEmployments_deleteTermination
description: |-
Delete an employee termination.
scope: `employments:write`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'204':
description: No Content
'404':
$ref: '#/components/responses/Employment-Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/terminations/{employee_id}:
put:
tags:
- Employee Employments
summary: Update an employee termination
operationId: EmployeeEmployments_updateTermination
description: >-
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`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeEmploymentsUpdateTerminationRequest'
examples:
Example:
value:
version: 1928d0c378e519e9c03fb959bc959a6b
effective_date: '2020-06-30'
run_termination_payroll: true
responses:
'200':
$ref: '#/components/responses/Termination-Object'
'404':
$ref: '#/components/responses/Employment-Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/employees/{employee_id}/rehire:
post:
tags:
- Employee Employments
summary: Create an employee rehire
operationId: EmployeeEmployments_createRehire
description: >-
Rehire is created whenever an employee is scheduled to return to the
company.
scope: `employments:write`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Rehire-Body'
examples:
Example:
value:
effective_date: '2023-06-30'
work_location_uuid: b6ae9d93-d4b8-4119-8c96-dba595dd8c30
file_new_hire_report: true
responses:
'201':
$ref: '#/components/responses/Rehire-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
put:
tags:
- Employee Employments
summary: Update an employee rehire
operationId: EmployeeEmployments_updateRehire
description: |-
Update an employee's rehire.
scope: `employments:write`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeEmploymentsUpdateRehireRequest'
examples:
Example:
value:
version: 1928d0c378e519e9c03fb959bc959a6b
effective_date: '2023-06-30'
work_location_uuid: b6ae9d93-d4b8-4119-8c96-dba595dd8c30
file_new_hire_report: true
responses:
'200':
$ref: '#/components/responses/Rehire-Object'
'404':
$ref: '#/components/responses/Employment-Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
get:
tags:
- Employee Employments
summary: Get an employee rehire
operationId: EmployeeEmployments_getRehire
description: >-
Retrieve an employee's rehire, which contains information on when the
employee returns to work.
scope: `employments:read`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Rehire-Object'
'404':
$ref: '#/components/responses/Employment-Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
delete:
tags:
- Employee Employments
summary: Delete an employee rehire
operationId: EmployeeEmployments_removeRehire
description: >-
Delete an employee rehire. An employee rehire cannot be deleted if it's
active (past effective date).
scope: `employments:write`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'204':
description: No Content
'404':
$ref: '#/components/responses/Employment-Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/employees/{employee_id}/employment_history:
get:
tags:
- Employee Employments
summary: Get employment history for an employee
operationId: EmployeeEmployments_getHistory
description: >-
Retrieve the employment history for a given employee, which includes
termination and rehire.
scope: `employments:read`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Employment-History-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/employees/{employee_id}/home_addresses:
get:
tags:
- Employee Addresses
summary: Get an employee's home addresses
operationId: EmployeeAddresses_getHomeAddresses
description: >-
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`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Employee-Address-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
post:
tags:
- Employee Addresses
summary: Create an employee's home address
operationId: EmployeeAddresses_createHomeAddress
description: >-
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`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeAddressesCreateHomeAddressRequest'
examples:
Example:
value:
street_1: 300 3rd Street
street_2: null
city: San Francisco
state: CA
zip: '94107'
effective_date: '2021-01-01'
courtesy_withholding: true
responses:
'200':
$ref: '#/components/responses/Employee-Address-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/home_addresses/{home_address_uuid}:
get:
tags:
- Employee Addresses
summary: Get an employee's home address
operationId: EmployeeAddresses_getHomeAddress
description: >-
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`
parameters:
- $ref: '#/components/parameters/home_address_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Employee-Address-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
put:
tags:
- Employee Addresses
summary: Update an employee's home address
operationId: EmployeeAddresses_updateHomeAddress
description: >-
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`
parameters:
- $ref: '#/components/parameters/home_address_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeAddressesUpdateHomeAddressRequest'
examples:
Example:
value:
version: fe75bd065ff48b91c35fe8ff842f986c
street_1: 300 3rd Street
street_2: null
city: San Francisco
state: CA
zip: '94107'
effective_date: '2021-01-01'
courtesy_withholding: true
responses:
'200':
$ref: '#/components/responses/Employee-Address-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
delete:
tags:
- Employee Addresses
summary: Delete an employee's home address
operationId: EmployeeAddresses_deleteHome
description: >-
Used for deleting an employee's home address. Cannot delete the
employee's active home address.
scope: `employees:write`
parameters:
- $ref: '#/components/parameters/home_address_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'204':
description: No Content
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/employees/{employee_id}/work_addresses:
get:
tags:
- Employee Addresses
summary: Get an employee's work addresses
operationId: EmployeeAddresses_listWorkAddresses
description: >-
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`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Employee-Work-Address-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
post:
tags:
- Employee Addresses
summary: Create an employee work address
operationId: EmployeeAddresses_createWorkAddress
description: >-
The work address of an employee describes when an employee began working
at an associated company location.
scope: `employees:manage`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeAddressesCreateWorkAddressRequest'
examples:
Example:
value:
location_uuid: 6a119be7-b4b0-4e27-aaa0-89d5f2524635
effective_date: '2023-05-15'
responses:
'201':
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Employee-Work-Address'
examples:
Example:
value:
uuid: 56260b3d-c375-415c-b77a-75d99f717193
employee_uuid: 7087a288-8349-4632-b92e-bc94fb79f29e
street_1: 644 Fay Vista
street_2: Suite 842
city: Richmond
state: VA
zip: '23218'
country: USA
active: false
effective_date: '2021-01-01'
courtesy_withholding: true
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/work_addresses/{work_address_uuid}:
get:
tags:
- Employee Addresses
summary: Get an employee work address
operationId: EmployeeAddresses_getWorkAddress
description: |-
The work address of an employee is used for payroll tax purposes.
scope: `employees:read`
parameters:
- $ref: '#/components/parameters/work_address_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Employee-Work-Address'
examples:
Example:
value:
version: 6a22da647ed391f184a212e6e83a541d
uuid: 34925ef7-6234-440d-83b8-788a24d0d69a
employee_uuid: 2363b9c0-6625-4425-9261-47627fd68783
location_uuid: aba6d0fd-7294-4997-b1a4-bc9268c45932
effective_date: '2023-05-15'
active: true
street_1: 977 Marks Viaduct
street_2: null
city: Pink Hill
state: NC
zip: '28572'
country: USA
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
put:
tags:
- Employee Addresses
summary: Update an employee work address
operationId: EmployeeAddresses_updateWorkAddress
description: |-
The work address of an employee is used for payroll tax purposes.
scope: `employees:manage`
parameters:
- $ref: '#/components/parameters/work_address_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeAddressesUpdateWorkAddressRequest'
examples:
Example:
value:
version: e6db1baa29d3df1eb307ff6a12c778da
location_uuid: 6a119be7-b4b0-4e27-aaa0-89d5f2524635
effective_date: '2023-05-15'
responses:
'200':
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Employee-Work-Address'
examples:
Example:
value:
version: 6a22da647ed391f184a212e6e83a541d
uuid: 34925ef7-6234-440d-83b8-788a24d0d69a
employee_uuid: 2363b9c0-6625-4425-9261-47627fd68783
location_uuid: aba6d0fd-7294-4997-b1a4-bc9268c45932
effective_date: '2023-05-15'
active: true
street_1: 977 Marks Viaduct
street_2: null
city: Pink Hill
state: NC
zip: '28572'
country: USA
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
delete:
tags:
- Employee Addresses
summary: Delete an employee's work address
operationId: EmployeeAddresses_deleteWorkAddress
description: >-
Used for deleting an employee's work address. Cannot delete the
employee's active work address.
scope: `employees:manage`
parameters:
- $ref: '#/components/parameters/work_address_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'204':
description: No Content
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/employees/{employee_id}/custom_fields:
get:
tags:
- Employees
summary: Get an employee's custom fields
operationId: Employees_getCustomFields
description: |-
Returns a list of the employee's custom fields.
scope: `employees:read`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perParam'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeesGetCustomFieldsResponse'
examples:
Example:
value:
custom_fields:
- description: Employee Level
id: ee515986-f3ca-49da-b576-2691b95262f9
company_custom_field_id: ea7e5d57-6abb-47d7-b654-347c142886c0
name: employee_level
type: text
value: '2'
selection_options: null
- description: What is your t-shirt size?
id: 3796e08d-c2e3-434c-b4de-4ce1893e7b59
company_custom_field_id: 299650e4-e970-4acf-9bf0-6f05585d20ba
name: t-shirt size
type: text
value: md
selection_options: null
- description: Which is your favorite fruit?
id: 3796e08d-c2e3-434c-b4de-4ce1893e7b59X
company_custom_field_id: 024ec137-6c92-43a3-b061-14a9720531d6
name: favorite fruit
type: radio
value: apple
selection_options:
- apple
- banana
- orange
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/employees/{employee_id}/onboarding_status:
get:
tags:
- Employees
summary: Get the employee's onboarding status
operationId: Employees_getOnboardingStatus
description: >-
# 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
| onboarding_steps | Requirement(s) to be completed |
|:-----------------|-------------------------------:|
| `personal_details` | Add employee's first name, last name, email, date
of birth, social security number |
| `compensation_details` | Associate employee to a job & compensation. |
| `add_work_address` | Add employee work address. |
| `add_home_address` | Add employee home address. |
| `federal_tax_setup` | Set up federal tax withholdings. |
| `state_tax_setup` | Set up state tax withholdings. |
| `direct_deposit_setup` | (optional) Set up employee's direct deposit.
|
| `employee_form_signing` | Employee forms (e.g., W4, direct deposit
authorization) are generated & signed. |
| `file_new_hire_report` | File a new hire report for this employee. |
| `admin_review` | Admin reviews & confirms employee details (only
required for Employee self-onboarding) |
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Employee-Onboarding-Status-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
put:
tags:
- Employees
summary: Update the employee's onboarding status
operationId: Employees_updateOnboardingStatus
description: >-
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.
| Action | current onboarding_status | new onboarding_status |
|:------------------|:------------:|----------:|
| Mark an employee as self-onboarding | `admin_onboarding_incomplete` |
`self_onboarding_pending_invite` |
| Invite an employee to self-onboard | `admin_onboarding_incomplete` or
`self_onboarding_pending_invite` | `self_onboarding_invited` |
| Cancel an employee's self-onboarding | `self_onboarding_invited` or
`self_onboarding_pending_invite` | `admin_onboarding_incomplete` |
| Review an employee's self-onboarded info |
`self_onboarding_completed_by_employee` |
`self_onboarding_awaiting_admin_review` |
| Finish an employee's onboarding | `admin_onboarding_incomplete` or
`self_onboarding_awaiting_admin_review` | `onboarding_completed` |
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeesUpdateOnboardingStatusRequest'
responses:
'200':
$ref: '#/components/responses/Employee-Onboarding-Status-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/employees/{employee_id}/finish_onboarding:
put:
tags:
- Employees
summary: Finish onboarding an employee
operationId: Employees_completeOnboarding
description: >-
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.
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Employee-Object'
x-gusto-integration-type:
- embedded
/v1/employees/{employee_uuid}/federal_taxes:
get:
tags:
- Employee Tax Setup
summary: Get an employee's federal taxes
operationId: EmployeeTaxSetup_getFederalTaxesById
description: |-
Get attributes relevant for an employee's federal taxes.
scope: `employee_federal_taxes:read`
parameters:
- $ref: '#/components/parameters/employee_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Employee-Federal-Tax-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
put:
tags:
- Employee Tax Setup
summary: Update an employee's federal taxes
operationId: EmployeeTaxSetup_updateFederalTaxes
description: |-
Update attributes relevant for an employee's federal taxes.
scope: `employee_federal_taxes:write`
parameters:
- $ref: '#/components/parameters/employee_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeTaxSetupUpdateFederalTaxesRequest'
examples:
Example:
value:
version: 56a489ce86ed6c1b0f0cecc4050a0b01
filing_status: Single
extra_withholding: '0.0'
two_jobs: true
dependents_amount: '0.0'
other_income: '0.0'
deductions: '0.0'
w4_data_type: rev_2020_w4
responses:
'200':
$ref: '#/components/responses/Employee-Federal-Tax-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/employees/{employee_uuid}/state_taxes:
get:
tags:
- Employee Tax Setup
summary: Get an employee's state taxes
operationId: EmployeeTaxSetup_getStateTaxes
description: >
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`
parameters:
- $ref: '#/components/parameters/employee_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Employee-State-Taxes-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
put:
tags:
- Employee Tax Setup
summary: Update an employee's state taxes
operationId: EmployeeTaxSetup_updateStateTaxes
description: >-
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`
parameters:
- $ref: '#/components/parameters/employee_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeTaxSetupUpdateStateTaxesRequest'
examples:
Employee-State-Taxes-Update-Example:
value:
states:
- state: CA
questions:
- key: filing_status
answers:
- value: M
valid_from: '2010-01-01'
valid_up_to: null
- key: withholding_allowance
answers:
- value: 2
valid_from: '2010-01-01'
valid_up_to: null
- key: additional_withholding
answers:
- value: '25.0'
valid_from: '2010-01-01'
valid_up_to: null
- key: file_new_hire_report
answers:
- value: true
valid_from: '2010-01-01'
valid_up_to: null
responses:
'200':
$ref: '#/components/responses/Employee-State-Taxes-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeTaxSetupUpdateStateTaxesResponse'
examples:
Employee-State-Taxes-Error-Response:
value:
- state: CA
questions:
- key: filing_status
answers:
- valid_from: '2010-01-01'
valid_up_to: null
errors:
- string
x-gusto-integration-type:
- embedded
/v1/employees/{employee_id}/bank_accounts:
post:
tags:
- Employee Payment Method
summary: Create an employee bank account
operationId: EmployeePaymentMethod_createBankAccount
description: >-
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`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/EmployeePaymentMethodCreateBankAccountRequest
examples:
Example:
value:
name: BoA Checking Account
routing_number: '266905059'
account_number: '5809431207'
account_type: Checking
responses:
'201':
$ref: '#/components/responses/Employee-Bank-Account-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
get:
tags:
- Employee Payment Method
summary: Get all employee bank accounts
operationId: EmployeePaymentMethod_listBankAccounts
description: |-
Returns all employee bank accounts.
scope: `employee_payment_methods:read`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perParam'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/EmployeePaymentMethodListBankAccountsRequest
responses:
'200':
$ref: '#/components/responses/Employee-Bank-Account-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/employees/{employee_id}/bank_accounts/{bank_account_uuid}:
delete:
tags:
- Employee Payment Method
summary: Delete an employee bank account
operationId: EmployeePaymentMethod_deleteBankAccount
description: |-
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`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/bank_account_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'204':
description: No Content
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/employees/{employee_id}/payment_method:
get:
tags:
- Employee Payment Method
summary: Get an employee's payment method
operationId: EmployeePaymentMethod_getBankAccounts
description: >-
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`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Employee-Payment-Method-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
put:
tags:
- Employee Payment Method
summary: Update an employee's payment method
operationId: EmployeePaymentMethod_updatePaymentMethod
description: |-
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`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: ''
content:
application/json:
schema:
$ref: >-
#/components/schemas/EmployeePaymentMethodUpdatePaymentMethodRequest
examples:
example-1:
value:
version: 63859768485e218ccf8a449bb60f14ed
type: Direct Deposit
split_by: Amount
splits:
- uuid: e88f9436-b74e-49a8-87e9-777b9bfe715e
name: BoA Checking Account
priority: 1
split_amount: 500
- uuid: 0d2b7f73-05d6-4184-911d-269edeecc30a
name: Chase Checking Account
priority: 2
split_amount: 1000
- uuid: 1531e824-8d9e-4bd8-9f90-0d04608125d7
name: US Bank Checking Account
priority: 3
split_amount: null
example-2:
value:
version: 63859768485e218ccf8a449bb60f14ed
type: Direct Deposit
split_by: Percentage
splits:
- uuid: e88f9436-b74e-49a8-87e9-777b9bfe715e
name: BoA Checking Account
priority: 1
split_amount: 60
- uuid: 0d2b7f73-05d6-4184-911d-269edeecc30a
name: Chase Checking Account
priority: 2
split_amount: 40
example-3:
value:
version: 63859768485e218ccf8a449bb60f14ed
type: Check
responses:
'200':
$ref: '#/components/responses/Employee-Payment-Method-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/employees/{employee_id}/jobs:
post:
tags:
- Jobs and Compensations
summary: Create a job
operationId: JobsAndCompensations_createJob
description: |-
Create a job.
scope: `jobs:write`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: Create a job.
content:
application/json:
schema:
$ref: '#/components/schemas/JobsAndCompensationsCreateJobRequest'
examples:
Example:
value:
title: Regional Manager
hire_date: '2020-12-21'
responses:
'201':
$ref: '#/components/responses/Job-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
get:
tags:
- Jobs and Compensations
summary: Get jobs for an employee
operationId: JobsAndCompensations_getEmployeeJobs
description: |-
Get all of the jobs that an employee holds.
scope: `jobs:read`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perParam'
- description: >-
Available options:
- all_compensations: Include all effective dated compensations for
each job instead of only the current compensation
in: query
name: include
schema:
type: string
enum:
- all_compensations
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Job-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/employees/{employee_uuid}/time_off_activities:
get:
tags:
- Employees
summary: Get employee time off activities
operationId: Employees_getTimeOffActivities
description: |-
Get employee time off activities.
scope: `employee_time_off_activities:read`
parameters:
- $ref: '#/components/parameters/employee_uuid'
- $ref: '#/components/parameters/time_off_type'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Time-Off-Activity-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/jobs/{job_id}:
get:
tags:
- Jobs and Compensations
summary: Get a job
operationId: JobsAndCompensations_getJobDetails
description: |-
Get a job.
scope: `jobs:read`
parameters:
- $ref: '#/components/parameters/job_id'
- description: >-
Available options:
- all_compensations: Include all effective dated compensations for
the job instead of only the current compensation
in: query
name: include
schema:
type: string
enum:
- all_compensations
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Job-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
put:
tags:
- Jobs and Compensations
summary: Update a job
operationId: JobsAndCompensations_updateJob
description: |-
Update a job.
scope: `jobs:write`
parameters:
- $ref: '#/components/parameters/job_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: Update a job.
content:
application/json:
schema:
$ref: '#/components/schemas/JobsAndCompensationsUpdateJobRequest'
examples:
Example:
value:
title: Regional Manager
version: gr78930htutrz444kuytr3s5hgxykuveb523fwl8sir
hire_date: '2020-12-21'
responses:
'200':
$ref: '#/components/responses/Job-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
delete:
tags:
- Jobs and Compensations
summary: Delete an individual job
operationId: JobsAndCompensations_deleteJobById
description: |-
Deletes a specific job that an employee holds.
scope: `jobs:write`
parameters:
- $ref: '#/components/parameters/job_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'204':
description: No Content
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/jobs/{job_id}/compensations:
get:
tags:
- Jobs and Compensations
summary: Get compensations for a job
operationId: JobsAndCompensations_getJobCompensations
description: >-
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`
parameters:
- $ref: '#/components/parameters/job_id'
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perParam'
- description: >-
Available options:
- all_compensations: Include all effective dated compensations for
each job instead of only the current compensation
in: query
name: include
schema:
type: string
enum:
- all_compensations
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Compensation-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
post:
tags:
- Jobs and Compensations
summary: Create a compensation
operationId: JobsAndCompensations_createCompensation
description: >-
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`
parameters:
- $ref: '#/components/parameters/job_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/JobsAndCompensationsCreateCompensationRequest
examples:
Exempt:
value:
rate: '60000.00'
payment_unit: Year
flsa_status: Exempt
Minimum Wage Adjusted:
value:
effective_date: '2023-01-01'
rate: '7.00'
payment_unit: Hour
flsa_status: Nonexempt
adjust_for_minimum_wage: true
minimum_wages:
- uuid: 340832db-ab28-4112-9e10-28dd1711835f
responses:
'201':
$ref: '#/components/responses/Compensation-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/compensations/{compensation_id}:
get:
tags:
- Jobs and Compensations
summary: Get a compensation
operationId: JobsAndCompensations_getCompensationById
description: >
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`
parameters:
- $ref: '#/components/parameters/compensation_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Compensation-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
put:
tags:
- Jobs and Compensations
summary: Update a compensation
operationId: JobsAndCompensations_updateCompensation
description: >-
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`
parameters:
- $ref: '#/components/parameters/compensation_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/JobsAndCompensationsUpdateCompensationRequest
examples:
Exempt:
value:
version: 98jr3289h3298hr9329gf9egskt3kagri32qqgiqe3872
rate: '60000.00'
payment_unit: Year
flsa_status: Exempt
Minimum Wage Adjusted:
value:
version: 98jr3289h3298hr9329gf9egskt3kagri32qqgiqe3872
rate: '7.00'
payment_unit: Hour
flsa_status: Nonexempt
adjust_for_minimum_wage: true
minimum_wages:
- uuid: 340832db-ab28-4112-9e10-28dd1711835f
responses:
'200':
$ref: '#/components/responses/Compensation-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
delete:
tags:
- Jobs and Compensations
summary: Delete a compensation
operationId: JobsAndCompensations_removeCompensation
description: >
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`
parameters:
- $ref: '#/components/parameters/compensation_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'204':
description: No Content
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/companies/{company_id}/earning_types:
post:
tags:
- Earning Types
summary: Create a custom earning type
operationId: EarningTypes_createCustomEarningType
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EarningTypesCreateCustomEarningTypeRequest'
examples:
Example:
value:
name: Gym Membership Stipend
responses:
'201':
$ref: '#/components/responses/Earning-Type-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
get:
tags:
- Earning Types
summary: Get all earning types for a company
operationId: EarningTypes_getAll
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Earning-Type-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/companies/{company_id}/earning_types/{earning_type_uuid}:
put:
tags:
- Earning Types
summary: Update an earning type
operationId: EarningTypes_updateType
description: |-
Update an earning type.
scope: `payrolls:write`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/earning_type_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EarningTypesUpdateTypeRequest'
examples:
Example:
value:
name: Gym Membership Stipend
responses:
'200':
$ref: '#/components/responses/Earning-Type-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
delete:
tags:
- Earning Types
summary: Deactivate an earning type
operationId: EarningTypes_deactivateType
description: |-
Deactivate an earning type.
scope: `payrolls:write`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/earning_type_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'204':
description: No Content
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/companies/{company_id}/contractors:
post:
tags:
- Contractors
summary: Create a contractor
operationId: Contractors_createNewContractor
description: |-
Create an individual or business contractor.
scope: `contractors:manage`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: Create an individual or business contractor.
content:
application/json:
schema:
$ref: '#/components/schemas/ContractorsCreateNewContractorRequest'
examples:
Create an Individual contractor:
value:
type: Individual
wage_type: Fixed
first_name: Johnson
last_name: Johnson
start_date: '2020-04-01'
self_onboarding: true
email: johnson@johnson.com
file_new_hire_report: true,
work_state: CA
Create a Business contractor:
value:
type: Business
wage_type: Fixed
business_name: Johnson-Johnson Contractors
start_date: '2020-04-01'
responses:
'201':
$ref: '#/components/responses/Contractor-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
get:
tags:
- Contractors
summary: Get contractors of a company
operationId: Contractors_getCompanyContractors
description: >-
Get all contractors, active and inactive, individual and business, for a
company.
scope: `contractors:read`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perParam'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Contractor-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/contractors/{contractor_id}:
get:
tags:
- Contractors
summary: Get a contractor
operationId: Contractors_getById
description: |-
Get a contractor.
scope: `contractors:read`
parameters:
- $ref: '#/components/parameters/contractor_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Contractor-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
put:
tags:
- Contractors
summary: Update a contractor
operationId: Contractors_updateContractor
description: >-
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
parameters:
- $ref: '#/components/parameters/contractor_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ContractorsUpdateContractorRequest'
examples:
Update an Individual Contractor:
value:
version: b48c46abfed1487b873b442334b3c4ff
start_date: '2021-01-01'
first_name: Chanel
last_name: Boyle
middle_initial: X
wage_type: Hourly
hourly_rate: '20.00'
is_active: true
Update a Business Contractor:
value:
version: b48c46abfed1487b873b442334b3c4ff
start_date: '2020-01-11'
business_name: Contracting Solutions
ein: '991113334'
wage_type: Fixed
is_active: false
responses:
'200':
$ref: '#/components/responses/Contractor-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
delete:
tags:
- Contractors
summary: Delete a contractor
operationId: Contractors_deleteContractor
description: |-
A contractor can only be deleted when there are no contractor payments.
scope: `contractors:manage`
parameters:
- $ref: '#/components/parameters/contractor_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'204':
description: No Content
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/contractors/{contractor_uuid}/bank_accounts:
post:
tags:
- Contractor Payment Method
summary: Create a contractor bank account
operationId: ContractorPaymentMethod_createBankAccount
description: >-
Creates a contractor bank account.
Note: We currently only support one bank account per contractor. Using
this endpoint on a contractor who already has a bank account will just
replace it.
scope: `contractor_payment_methods:write`
parameters:
- $ref: '#/components/parameters/contractor_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/ContractorPaymentMethodCreateBankAccountRequest
examples:
Example:
value:
name: BoA Checking Account
routing_number: '266905059'
account_number: '5809431207'
account_type: Checking
responses:
'201':
$ref: '#/components/responses/Contractor-Bank-Account-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
get:
tags:
- Contractor Payment Method
summary: Get all contractor bank accounts
operationId: ContractorPaymentMethod_listBankAccounts
description: |-
Returns all contractor bank accounts.
scope: `contractor_payment_methods:read`
parameters:
- $ref: '#/components/parameters/contractor_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Contractor-Bank-Account-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/webhook_subscriptions:
post:
tags:
- Webhooks
summary: Create a webhook subscription
operationId: Webhooks_createSubscription
security:
- ApiKeyAuth: []
description: >-
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`
parameters:
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksCreateSubscriptionRequest'
examples:
Example:
value:
url: https://partner-app.com/subscriber
subscription_types:
- Company
- Employee
responses:
'201':
$ref: '#/components/responses/Webhook-Subscription-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
get:
tags:
- Webhooks
summary: List webhook subscriptions
operationId: Webhooks_listSubscriptions
security:
- ApiKeyAuth: []
description: >-
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`
parameters:
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Webhook-Subscriptions-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/webhook_subscriptions/{webhook_subscription_uuid}:
put:
tags:
- Webhooks
summary: Update a webhook subscription
operationId: Webhooks_updateSubscription
security:
- ApiKeyAuth: []
description: >
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`
parameters:
- $ref: '#/components/parameters/webhook_subscription_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksUpdateSubscriptionRequest'
examples:
Example:
value:
subscription_types:
- Company
- Employee
responses:
'200':
$ref: '#/components/responses/Webhook-Subscription-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
get:
tags:
- Webhooks
summary: Get a webhook subscription
operationId: Webhooks_getSubscription
security:
- ApiKeyAuth: []
description: >
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`
parameters:
- $ref: '#/components/parameters/webhook_subscription_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Webhook-Subscription-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
delete:
tags:
- Webhooks
summary: Delete a webhook subscription
operationId: Webhooks_deleteSubscriptionByUuid
security:
- ApiKeyAuth: []
description: >
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`
parameters:
- $ref: '#/components/parameters/webhook_subscription_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'204':
description: The resource was deleted successfully.
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/webhook_subscriptions/{webhook_subscription_uuid}/verify:
put:
tags:
- Webhooks
summary: Verify the webhook subscription
operationId: Webhooks_verifySubscriptionToken
security:
- ApiKeyAuth: []
description: >
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`
parameters:
- $ref: '#/components/parameters/webhook_subscription_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksVerifySubscriptionTokenRequest'
examples:
Example:
value:
verification_token: asefasedfe23e234easd
responses:
'200':
$ref: '#/components/responses/Webhook-Subscription-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/webhook_subscriptions/{webhook_subscription_uuid}/request_verification_token:
get:
tags:
- Webhooks
summary: Request the webhook subscription verification_token
operationId: Webhooks_requestVerificationToken
security:
- ApiKeyAuth: []
description: >
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`
parameters:
- $ref: '#/components/parameters/webhook_subscription_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
description: >-
No Content. The `verification_token` is POSTed to the Subscription
URL.
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/contractors/{contractor_uuid}/forms:
get:
tags:
- Contractor Forms
summary: Get all contractor forms
operationId: ContractorForms_listAll
description: |-
Get a list of all contractor's forms
scope: `contractor_forms:read`
parameters:
- $ref: '#/components/parameters/contractor_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/ContractorFormsListAllResponse'
examples:
Example:
value:
- title: 'Form 1099: 2020'
description: Form 1099 records your annual income as a contractor.
uuid: 48cdd5ec-a4dd-4840-a424-ad79f38d8408
name: US_1099
draft: false
requires_signing: false
year: 2020
quarter: null
contractor_uuid: 123dd616-6dbc-4724-938a-403f6217a933
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/contractors/{contractor_uuid}/forms/{form_id}:
get:
tags:
- Contractor Forms
summary: Get a contractor form
operationId: ContractorForms_getByIdForm
description: |-
Get a contractor form
scope: `contractor_forms:read`
parameters:
- $ref: '#/components/parameters/contractor_uuid'
- $ref: '#/components/parameters/form_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Form_1099'
examples:
Example:
value:
title: 'Form 1099: 2020'
description: Form 1099 records your annual income as a contractor.
uuid: 48cdd5ec-a4dd-4840-a424-ad79f38d8408
name: US_1099
draft: false
requires_signing: false
year: 2020
quarter: null
contractor_uuid: 123dd616-6dbc-4724-938a-403f6217a933
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/contractors/{contractor_uuid}/forms/{form_id}/pdf:
get:
tags:
- Contractor Forms
summary: Get the contractor form pdf
operationId: ContractorForms_getPdfLink
description: |-
Get the link to the form PDF
scope: `contractor_forms:read`
parameters:
- $ref: '#/components/parameters/contractor_uuid'
- $ref: '#/components/parameters/form_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Form-Object-Pdf'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/sandbox/generate_1099:
post:
tags:
- Contractor Forms
summary: Generate a 1099 form [DEMO]
operationId: ContractorForms_create1099Form
description: |-
> 🚧 Demo action
>
> This action is only available in the Demo environment
Generates a 1099 document for testing purposes.
scope: `contractors:write`
parameters:
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContractorFormsCreate1099FormRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Form_1099'
examples:
Example:
value:
title: 'Form 1099: 2022'
description: Form 1099 records your annual income as a contractor.
year: 2022
quarter: null
contractor_uuid: b68484a9-4487-4ee5-bafc-4245133a426c
uuid: 29afb141-2256-431d-90e0-1c7344222342
name: US_1099
draft: false
requires_signing: false
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/sandbox/generate_w2:
post:
tags:
- Employee Forms
summary: Generate a W2 form [DEMO]
operationId: EmployeeForms_generateW2Document
description: |-
> 🚧 Demo action
>
> This action is only available in the Demo environment
Generates a W2 document for testing purposes.
scope: `employees:write`
parameters:
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeFormsGenerateW2DocumentRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeFormsGenerateW2DocumentResponse'
examples:
Example:
value:
title: 'Draft Form W-2: 2021'
description: Form W-2 records your annual wages and taxes.
employee_uuid: 19394e76-a866-4570-b237-9a26b0163907
uuid: bf5b2496-26df-436e-b465-eae4ed5c8021
name: US_W-2
draft: false
requires_signing: false
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/contractors/{contractor_uuid}/payment_method:
get:
tags:
- Contractor Payment Method
summary: Get a contractor's payment method
operationId: ContractorPaymentMethod_getContractorPaymentMethod
description: >-
Fetches a contractor's payment method. A contractor payment method
describes how the payment should be split across the contractor's
associated
bank accounts.
scope: `contractor_payment_methods:read`
parameters:
- $ref: '#/components/parameters/contractor_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Contractor-Payment-Method-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
put:
tags:
- Contractor Payment Method
summary: Update a contractor's payment method
operationId: ContractorPaymentMethod_updateBankAccount
description: |-
Updates a contractor's payment method. Note that creating a contractor
bank account will also update the contractor's payment method.
scope: `contractor_payment_methods:write`
parameters:
- $ref: '#/components/parameters/contractor_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: ''
content:
application/json:
schema:
$ref: >-
#/components/schemas/ContractorPaymentMethodUpdateBankAccountRequest
examples:
example-1:
value:
version: 63859768485e218ccf8a449bb60f14ed
type: Direct Deposit
example-3:
value:
version: 63859768485e218ccf8a449bb60f14ed
type: Check
responses:
'200':
$ref: '#/components/responses/Contractor-Payment-Method-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/contractors/{contractor_uuid}/onboarding_status:
get:
tags:
- Contractors
summary: Get the contractor's onboarding status
operationId: Contractors_getOnboardingStatus
description: >-
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. |
parameters:
- $ref: '#/components/parameters/contractor_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Contractor-Onboarding-Status-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
put:
tags:
- Contractors
summary: Change the contractor's onboarding status
operationId: Contractors_changeOnboardingStatus
description: >-
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` |
parameters:
- $ref: '#/components/parameters/contractor_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContractorsChangeOnboardingStatusRequest'
responses:
'200':
$ref: '#/components/responses/Contractor-Onboarding-Status-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/contractors/{contractor_uuid}/address:
get:
tags:
- Contractors
summary: Get a contractor address
operationId: Contractors_getAddress
description: >-
The address of a contractor is used to determine certain tax information
about them. Addresses are geocoded on create and update to ensure
validity.
scope: `contractors:read`
parameters:
- $ref: '#/components/parameters/contractor_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Contractor-Address-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
put:
tags:
- Contractors
summary: Update a contractor's address
operationId: Contractors_updateAddress
description: >-
The address of a contractor is used to determine certain tax information
about them. Addresses are geocoded on create and update to ensure
validity.
scope: `contractors:write`
parameters:
- $ref: '#/components/parameters/contractor_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContractorsUpdateAddressRequest'
examples:
Example:
value:
version: fe75bd065ff48b91c35fe8ff842f986c
street_1: 300 3rd Street
street_2: null
city: San Francisco
state: CA
zip: '94107'
responses:
'200':
$ref: '#/components/responses/Contractor-Address-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_id}/payrolls:
post:
tags:
- Payrolls
summary: Create an off-cycle payroll
operationId: Payrolls_createOffCyclePayroll
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayrollsCreateOffCyclePayrollRequest'
responses:
'200':
$ref: '#/components/responses/Payroll-Update-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
get:
tags:
- Payrolls
summary: Get all payrolls for a company
operationId: Payrolls_getCompanyPayrolls
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- description: >-
Whether to include processed and/or unprocessed payrolls in the
response, defaults to processed, for multiple attributes comma
separate the values, i.e.
`?processing_statuses=processed,unprocessed`
schema:
type: string
enum:
- unprocessed
- processed
in: query
name: processing_statuses
- description: >-
Whether to include regular and/or off_cycle payrolls in the
response, defaults to regular, for multiple attributes comma
separate the values, i.e. `?payroll_types=regular,off_cycle`
schema:
type: string
enum:
- regular
- off_cycle
- external
in: query
name: payroll_types
- description: >-
Include the requested attribute in the response. In v2023-04-01
totals are no longer included by default. For multiple attributes
comma separate the values, i.e.
`?include=totals,payroll_status_meta`
schema:
type: string
enum:
- totals
- payroll_status_meta
in: query
name: include
- description: Return payrolls whose pay period is after the start date
schema:
type: string
in: query
name: start_date
- description: Return payrolls whose pay period is before the end date
schema:
type: string
in: query
name: end_date
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Payroll-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/companies/{company_id}/payroll_reversals:
get:
tags:
- Payrolls
summary: Get approved payroll reversals
operationId: Payrolls_approvedReversals
description: |-
Returns all approved Payroll Reversals for a Company.
scope: `payrolls:read`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perParam'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Payroll-Reversal-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_id}/payrolls/{payroll_id}:
get:
tags:
- Payrolls
summary: Get a single payroll
operationId: Payrolls_getSinglePayroll
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/payroll_id'
- description: >-
Include the requested attribute in the response, for multiple
attributes comma separate the values, i.e.
`?include=benefits,deductions,taxes`
schema:
type: string
enum:
- benefits
- deductions
- taxes
- payroll_status_meta
in: query
name: include
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Payroll-Show-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
put:
tags:
- Payrolls
summary: Update a payroll by ID
operationId: Payrolls_updatePayrollById
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/payroll_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayrollsUpdatePayrollByIdRequest'
responses:
'200':
$ref: '#/components/responses/Payroll-Update-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
delete:
tags:
- Payrolls
summary: Delete a payroll
operationId: Payrolls_deleteUnprocessedPayroll
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/payroll_id'
- description: When true, request an asynchronous delete of the payroll.
name: async
in: query
schema:
type: boolean
- $ref: '#/components/parameters/VersionHeader'
responses:
'202':
description: Accepted
'204':
description: No Content
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
description: Unprocessable Entity
x-gusto-integration-type:
- embedded
/v1/companies/{company_id}/payrolls/{payroll_id}/prepare:
put:
tags:
- Payrolls
summary: Prepare a payroll for update
operationId: Payrolls_prepareForUpdate
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/payroll_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Payroll-Update-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/payrolls/{payroll_uuid}/receipt:
get:
tags:
- Payrolls
summary: Get a single payroll receipt
operationId: Payrolls_getSingleReceipt
description: >-
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`
parameters:
- $ref: '#/components/parameters/payroll_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Payroll-Receipt'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/payrolls/{payroll_id}/employees/{employee_id}/calculate_accruing_time_off_hours:
post:
tags:
- Time Off Policies
summary: Calculate accruing time off hours
operationId: TimeOffPolicies_calculateAccruingTimeOffHours
description: >-
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`
parameters:
- $ref: '#/components/parameters/payroll_id'
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/TimeOffPoliciesCalculateAccruingTimeOffHoursRequest
examples:
Example:
value:
regular_hours_worked: 30.25
overtime_hours_worked: 10
double_overtime_hours_worked: 0
pto_hours_used: 5.5
sick_hours_used: 0
responses:
'200':
$ref: '#/components/responses/Accruing-Time-Off-Hour-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/companies/{company_uuid}/payrolls/blockers:
get:
tags:
- Payrolls
summary: Get all payroll blockers for a company
operationId: Payrolls_getAllPayrollBlockers
description: >-
Returns a list of reasons that prevent the company from running
payrolls. See the [payroll blockers
guide](https://docs.gusto.com/embedded-payroll/docs/payroll-blockers)
for a complete list of reasons.
The list is empty if there are no payroll blockers.
scope: `payrolls:run`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Payroll-Blocker-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/payrolls/skip:
post:
tags:
- Payrolls
summary: Skip a payroll
operationId: Payrolls_skipPayroll
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayrollsSkipPayrollRequest'
examples:
Example:
value:
payroll_type: Regular
start_date: '2023-05-26'
end_date: '2023-06-25'
pay_schedule_uuid: 85100524-4b42-4d2d-bd62-9d864f9aea64
responses:
'202':
description: Accepted
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/PayrollsSkipPayrollResponse'
examples:
Example:
value:
errors:
- error_key: base
category: payroll_blocker
message: >-
Company must complete all onboarding requirements in
order to run payroll.
metadata:
key: needs_onboarding
x-gusto-integration-type:
- embedded
/v1/payrolls/{payroll_uuid}/gross_up:
post:
tags:
- Payrolls
summary: Calculate gross up
operationId: Payrolls_calculateGrossUp
description: >-
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`
parameters:
- $ref: '#/components/parameters/payroll_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayrollsCalculateGrossUpRequest'
examples:
Example:
value:
employee_uuid: be48c41e-142d-4116-9430-5aba2313fac7
net_pay: '1000.00'
responses:
'200':
$ref: '#/components/responses/Gross-Up-Pay'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/PayrollsCalculateGrossUpResponse'
examples:
Example:
value:
errors:
- error_key: base
category: payroll_blocker
message: >-
Company must complete all onboarding requirements in
order to run payroll.
metadata:
key: needs_onboarding
x-gusto-integration-type:
- embedded
/v1/contractor_payments/{contractor_payment_uuid}/receipt:
get:
tags:
- Contractor Payments
summary: Get a single contractor payment receipt
operationId: ContractorPayments_getSingleReceipt
description: >-
Returns a contractor payment receipt.
Notes:
* Receipts are only available for direct deposit payments and are only
available once those payments have been funded.
* Payroll Receipt requests for payrolls which do not have receipts
available (e.g. payment by check) will return a 404 status.
* 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`
parameters:
- $ref: '#/components/parameters/contractor_payment_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Contractor-Payment-Receipt'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/contractor_payments/{contractor_payment_uuid}/fund:
put:
tags:
- Contractor Payments
summary: Fund a contractor payment [DEMO]
operationId: ContractorPayments_fundContractorPayment
description: >-
> 🚧 Demo action
>
> This action is only available in the Demo environment
Simulate funding a contractor payment. Funding only occurs automatically
in the production environment when bank transactions are generated. Use
this action in the demo environment to transition a contractor payment's
`status` from `Unfunded` to `Funded`. A `Funded` status is required for
generating a contractor payment receipt.
scope: `payrolls:run`
parameters:
- $ref: '#/components/parameters/contractor_payment_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Contractor-Payment-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_id}/payrolls/{payroll_id}/calculate:
put:
tags:
- Payrolls
summary: Calculate a payroll
operationId: Payrolls_calculateGrossUp
description: >-
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.
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/payroll_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'202':
description: Accepted
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/PayrollsCalculateGrossUp422Response'
examples:
Example:
value:
errors:
- error_key: base
category: payroll_blocker
message: >-
Company must complete all onboarding requirements in
order to run payroll.
metadata:
key: needs_onboarding
x-gusto-integration-type:
- embedded
/v1/companies/{company_id}/payrolls/{payroll_id}/submit:
put:
tags:
- Payrolls
summary: Submit payroll
operationId: Payrolls_submitPayroll
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/payroll_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'202':
description: Accepted
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/PayrollsSubmitPayrollResponse'
examples:
Example:
value:
errors:
- error_key: base
category: payroll_blocker
message: >-
Company must complete all onboarding requirements in
order to run payroll.
metadata:
key: needs_onboarding
x-gusto-integration-type:
- embedded
/v1/companies/{company_id}/payrolls/{payroll_id}/cancel:
put:
tags:
- Payrolls
summary: Cancel a payroll
operationId: Payrolls_cancelPayrollTransition
description: >
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`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/payroll_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Payroll-Show-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_id}/contractor_payments:
post:
tags:
- Contractor Payments
summary: Create a contractor payment
operationId: ContractorPayments_createPayment
description: >-
Pay a contractor. Information needed depends on the contractor's wage
type (hourly vs fixed)
scope: `payrolls:run`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContractorPaymentsCreatePaymentRequest'
responses:
'200':
$ref: '#/components/responses/Contractor-Payment-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
get:
tags:
- Contractor Payments
summary: Get contractor payments for a company
operationId: ContractorPayments_getWithinTimePeriodTotals
description: >-
Returns an object containing individual contractor payments, within a
given time period, including totals.
scope: `payrolls:read`
parameters:
- $ref: '#/components/parameters/company_id'
- description: The time period for which to retrieve contractor payments
schema:
type: string
example: '2020-01-01'
in: query
name: start_date
required: true
- description: The time period for which to retrieve contractor payments
schema:
type: string
example: '2020-12-31'
in: query
name: end_date
required: true
- description: >-
The UUID of the contractor. When specified, will load all payments
for that contractor.
schema:
type: string
in: query
name: contractor_uuid
- description: >-
Display contractor payments results group by check date if set to
true.
schema:
type: boolean
in: query
name: group_by_date
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perParam'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
description: A JSON object containing contractor payments information
content:
application/json:
schema:
$ref: >-
#/components/schemas/ContractorPaymentsGetWithinTimePeriodTotalsResponse
examples:
Example:
value:
total:
reimbursements: '110.0'
wages: '1840.0'
contractor_payments:
- contractor_id: 1234
reimbursement_total: '110.0'
wage_total: '1840.0'
payments:
- id: 04552eb9-7829-4b18-ae96-6983552948df
bonus: '20.0'
date: '2020-10-19'
hours: '40.0'
payment_method: Direct Deposit
reimbursement: '100.0'
hourly_rate: '18.0'
may_cancel: true
wage: '0.0'
wage_type: Hourly
wage_total: '740.00'
contractor_id: 1234
contractor_uuid: bc57832c-d8bc-43a7-ae99-3a03380ff037
- id: 25cfeb96-17fc-4fdf-8941-57f3fb9eea00
bonus: '100.0'
date: '2020-10-19'
hours: '0.00'
payment_method: Direct Deposit
reimbursement: '10.0'
hourly_rate: '0.0'
may_cancel: true
wage: '1000.0'
wage_type: Fixed
wage_total: '1100.0'
contractor_id: 1234
contractor_uuid: bc57832c-d8bc-43a7-ae99-3a03380ff037
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/companies/{company_id}/contractor_payments/{contractor_payment_id}:
get:
tags:
- Contractor Payments
summary: Get a single contractor payment
operationId: ContractorPayments_getSinglePayment
description: |-
Returns a single contractor payments
scope: `payrolls:read`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/contractor_payment_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Contractor-Payment-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
delete:
tags:
- Contractor Payments
summary: Cancel a contractor payment
operationId: ContractorPayments_cancelPayment
description: >-
Cancels and deletes a contractor payment. If the contractor payment has
already started processing, the payment cannot be cancelled.
scope: `payrolls:run`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/contractor_payment_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'204':
description: No Content
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
x-internal: false
/v1/companies/{company_id}/forms:
get:
tags:
- Company Forms
summary: Get all company forms
operationId: CompanyForms_getAllForms
description: |-
Get a list of all company's forms
scope: `company_forms:read`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Form-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/forms/{form_id}:
get:
tags:
- Company Forms
summary: Get a company form
operationId: CompanyForms_getFormById
description: |-
Get a company form
scope: `company_forms:read`
parameters:
- $ref: '#/components/parameters/form_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Form-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/forms/{form_id}/pdf:
get:
tags:
- Company Forms
summary: Get a company form pdf
operationId: CompanyForms_getPdfLink
description: |-
Get the link to the form PDF
scope: `company_forms:read`
parameters:
- $ref: '#/components/parameters/form_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Form-Object-Pdf'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/forms/{form_id}/sign:
put:
tags:
- Company Forms
summary: Sign a company form
operationId: CompanyForms_signForm
description: |-
Sign a company form
scope: `company_forms:sign`
parameters:
- $ref: '#/components/parameters/form_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyFormsSignFormRequest'
examples:
Example:
value:
signature_text: Jane Smith
agree: true
signed_by_ip_address: 192.168.0.1
responses:
'200':
$ref: '#/components/responses/Form-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/employees/{employee_id}/forms:
get:
tags:
- Employee Forms
summary: Get all employee forms
operationId: EmployeeForms_getAllEmployeeForms
description: |-
Get a list of all employee's forms
scope: `employee_forms:read`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Form-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/employees/{employee_id}/forms/{form_id}:
get:
tags:
- Employee Forms
summary: Get an employee form
operationId: EmployeeForms_getFormById
description: |-
Get an employee form
scope: `employee_forms:read`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/form_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Form-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/employees/{employee_id}/forms/{form_id}/pdf:
get:
tags:
- Employee Forms
summary: Get the employee form pdf
operationId: EmployeeForms_getPdfLink
description: |-
Get the link to the form PDF
scope: `employee_forms:read`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/form_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Form-Object-Pdf'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/employees/{employee_id}/forms/{form_id}/sign:
put:
tags:
- Employee Forms
summary: Sign an employee form
operationId: EmployeeForms_signForm
description: |-
Sign a company form
scope: `employee_forms:sign`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/form_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeFormsSignFormRequest'
examples:
Example:
value:
signature_text: Jane Smith
agree: true
signed_by_ip_address: 192.168.0.1
responses:
'200':
$ref: '#/components/responses/Form-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/payrolls/{payroll_id}/employees/{employee_id}/pay_stub:
get:
tags:
- Payrolls
summary: Get an employee pay stub (pdf)
operationId: Payrolls_getEmployeePayStub
description: >-
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`
parameters:
- $ref: '#/components/parameters/payroll_id'
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
description: OK
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/employees/{employee_id}/pay_stubs:
get:
tags:
- Payrolls
summary: Get an employee's pay stubs
operationId: Payrolls_getEmployeePayStubs
description: |-
Get an employee's pay stubs
scope: `pay_stubs:read`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Employee-Pay-Stubs-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/generated_documents/{document_type}/{request_uuid}:
get:
tags:
- Generated Documents
summary: Get a generated document
operationId: GeneratedDocuments_getDocumentByRequestUuid
description: >-
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`
parameters:
- $ref: '#/components/parameters/document_type'
- $ref: '#/components/parameters/request_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Generated-Document'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/payrolls/{payroll_id}/generated_documents/printable_payroll_checks:
post:
tags:
- Payrolls
summary: Generate payroll printable checks (pdf)
operationId: Payrolls_generatePrintableChecks
description: >-
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`
parameters:
- $ref: '#/components/parameters/payroll_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayrollsGeneratePrintableChecksRequest'
responses:
'200':
$ref: '#/components/responses/Payroll-Check'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_id}/company_benefits:
post:
tags:
- Company Benefits
summary: Create a company benefit
operationId: CompanyBenefits_createBenefit
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyBenefitsCreateBenefitRequest'
responses:
'201':
$ref: '#/components/responses/Company-Benefit-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
get:
tags:
- Company Benefits
summary: Get benefits for a company
operationId: CompanyBenefits_getBenefitsForCompany
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_id'
- description: Whether to return employee enrollment count
schema:
type: boolean
in: query
name: enrollment_count
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Company-Benefit-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/company_benefits/{company_benefit_id}:
get:
tags:
- Company Benefits
summary: Get a company benefit
operationId: CompanyBenefits_getBenefitById
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_benefit_id'
- description: Whether to return employee benefits associated with the benefit
schema:
type: boolean
in: query
name: with_employee_benefits
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Company-Benefit-With-Employee-Benefits-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
put:
tags:
- Company Benefits
summary: Update a company benefit
operationId: CompanyBenefits_updateBenefit
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_benefit_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyBenefitsUpdateBenefitRequest'
examples:
Example:
value:
version: 98jr3289h3298hr9329gf9egskt3kagri32qqgiqe3872
active: false
responses:
'200':
$ref: '#/components/responses/Company-Benefit-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
delete:
tags:
- Company Benefits
summary: Delete a company benefit
operationId: CompanyBenefits_deleteBenefit
description: |-
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`
parameters:
- $ref: '#/components/parameters/company_benefit_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'204':
description: No content
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyBenefitsDeleteBenefitResponse'
examples:
Example:
value:
errors:
base:
- type: error type
message: This is an error message
full_message: This is a more descriptive error message
x-gusto-integration-type:
- embedded
- app-integrations
/v1/benefits:
get:
tags:
- Company Benefits
summary: Get all benefits supported by Gusto
operationId: CompanyBenefits_listSupportedBenefits
description: >-
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`
parameters:
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Supported-Benefit-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/benefits/{benefit_id}:
get:
tags:
- Company Benefits
summary: Get a supported benefit by ID
operationId: CompanyBenefits_getSupportedBenefitById
description: >-
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`
parameters:
- $ref: '#/components/parameters/benefit_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Supported-Benefit-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/company_benefits/{company_benefit_id}/summary:
get:
tags:
- Company Benefits
summary: Get company benefit summary by company benefit id.
operationId: CompanyBenefits_getBenefitSummaryById
description: >-
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`
parameters:
- $ref: '#/components/parameters/company_benefit_id'
- description: The start date for which to retrieve company benefit summary
schema:
type: string
example: '2022-01-01'
in: query
name: start_date
- description: The end date for which to retrieve company benefit summary
schema:
type: string
example: '2022-12-31'
in: query
name: end_date
- description: Display employee payroll item summary
schema:
type: boolean
in: query
name: detailed
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Benefit-Summary-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/benefits/{benefit_id}/requirements:
get:
tags:
- Company Benefits
summary: Get benefit fields requirements by ID
operationId: CompanyBenefits_getBenefitFieldsRequirementsById
description: |-
Returns field requirements for the requested benefit type.
scope: `benefits:read`
parameters:
- $ref: '#/components/parameters/benefit_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Benefit-Type-Requirements-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/employees/{employee_id}/employee_benefits:
post:
tags:
- Employee Benefits
summary: Create an employee benefit
operationId: EmployeeBenefits_createBenefitRecord
description: >-
Employee benefits represent an employee enrolled in a particular company
benefit. It includes information specific to that employee’s enrollment.
scope: `employee_benefits:write`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeBenefitsCreateBenefitRecordRequest'
examples:
Example:
value:
company_benefit_uuid: f68abb42-431e-4392-bc3f-2795627e00f3
active: true
employee_deduction: '100.00'
contribution:
type: amount
value: '100.00'
responses:
'201':
$ref: '#/components/responses/Employee-Benefit-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
get:
tags:
- Employee Benefits
summary: Get all benefits for an employee
operationId: EmployeeBenefits_getAllForEmployee
description: >-
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`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perParam'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Employee-Benefit-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/employee_benefits/{employee_benefit_id}:
get:
tags:
- Employee Benefits
summary: Get an employee benefit
operationId: EmployeeBenefits_getEmployeeBenefitById
description: >-
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`
parameters:
- $ref: '#/components/parameters/employee_benefit_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Employee-Benefit-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
put:
tags:
- Employee Benefits
summary: Update an employee benefit
operationId: EmployeeBenefits_updateBenefitRecord
description: >-
Employee benefits represent an employee enrolled in a particular company
benefit. It includes information specific to that employee’s enrollment.
scope: `employee_benefits:write`
parameters:
- $ref: '#/components/parameters/employee_benefit_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeBenefitsUpdateBenefitRecordRequest'
examples:
Example:
value:
version: 09j3d29jqdpj92109j9j2d90dq
employee_deduction: '250.00'
responses:
'200':
$ref: '#/components/responses/Employee-Benefit-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
delete:
tags:
- Employee Benefits
summary: Delete an employee benefit
operationId: EmployeeBenefits_deleteById
description: >-
Employee benefits represent an employee enrolled in a particular company
benefit. It includes information specific to that employee’s enrollment.
scope: `employee_benefits:write`
parameters:
- $ref: '#/components/parameters/employee_benefit_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'204':
description: No Content
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/employees/{employee_id}/ytd_benefit_amounts_from_different_company:
post:
tags:
- Employee Benefits
summary: Create year-to-date benefit amounts from a different company
operationId: EmployeeBenefits_createYtdBenefitAmountsFromDifferentCompany
description: >-
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`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
$ref: >-
#/components/requestBodies/post-employee-ytd-benefit-amounts-from-different-company
responses:
'204':
description: No Content
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/employees/{employee_id}/garnishments:
post:
tags:
- Garnishments
summary: Create a garnishment
operationId: Garnishments_createGarnishment
description: >-
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`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GarnishmentsCreateGarnishmentRequest'
examples:
Example:
value:
description: Back taxes
amount: '150.00'
court_ordered: true
recurring: true
deduct_as_percentage: false
responses:
'201':
$ref: '#/components/responses/Garnishment-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
get:
tags:
- Garnishments
summary: Get garnishments for an employee
operationId: Garnishments_getEmployeeGarnishments
description: >-
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`
parameters:
- $ref: '#/components/parameters/employee_id'
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perParam'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Garnishment-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/garnishments/{garnishment_id}:
get:
tags:
- Garnishments
summary: Get a garnishment
operationId: Garnishments_getGarnishment
description: >-
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`
parameters:
- $ref: '#/components/parameters/garnishment_id'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Garnishment-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
put:
tags:
- Garnishments
summary: Update a garnishment
operationId: Garnishments_updateGarnishment
description: >-
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`
parameters:
- $ref: '#/components/parameters/garnishment_id'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GarnishmentsUpdateGarnishmentRequest'
examples:
Example:
value:
version: 52b7c567242cb7452e89ba2bc02cb476
active: false
responses:
'200':
$ref: '#/components/responses/Garnishment-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/plaid/processor_token:
post:
tags:
- Bank Accounts
summary: Create a bank account from a plaid processor token
operationId: BankAccounts_createFromPlaidToken
description: >-
This endpoint creates a new **verified** bank account by using a plaid
processor token to retrieve its information.
scope: `plaid_processor:write`
> 📘
> To create a token please use the [plaid
api](https://plaid.com/docs/api/processors/#processortokencreate) and
select "gusto" as processor.
> 🚧 Warning - Company Bank Accounts
>
> If a default company bank account exists, it will be disabled and the
new bank account will replace it as the company's default funding
method.
parameters:
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccountsCreateFromPlaidTokenRequest'
examples:
Create a company bank account:
value:
owner_type: Company
owner_id: ef279fbd-0fc6-4cf1-a977-6939d621c429
processor_token: processor-sandbox-0asd1-a92nc
responses:
'201':
description: A JSON object containing bank information
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccountsCreateFromPlaidTokenResponse'
examples:
Example:
value:
uuid: 1263eae5-4411-48d9-bd6d-18ed93082e65
company_uuid: e2c4c0ce-2986-48b9-86cf-ec27f6ed9a36
account_type: Checking
routing_number: '851070439'
hidden_account_number: XXXX4087
verification_status: verified
verification_type: plaid_external
name: Employer Funding Account
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/tax_requirements/{state}:
get:
tags:
- Tax Requirements
summary: Get State Tax Requirements
operationId: TaxRequirements_getStateRequirements
description: |
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`
parameters:
- $ref: '#/components/parameters/company_uuid'
- description: 2-letter US state abbreviation
schema:
type: string
name: state
in: path
required: true
- description: >-
When true, return "new" requirement sets with valid `effective_from`
dates that are available to save new effective dated values.
schema:
type: boolean
in: query
name: scheduling
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Tax-Requirements-State'
examples:
Example Tax Requirements for GA:
value:
company_uuid: 6c14eac3-0da2-474d-bda1-786b3602d381
state: GA
requirement_sets:
- state: GA
key: registrations
label: Registrations
effective_from: null
requirements:
- description: >-
If you have run payroll in the past in GA, find
your withholding number on notices received from
the Georgia Department of Revenue, or call the
agency at (877) 423-6711. If you don’t have a
number yet, you should register the
business online. The last two characters of
your ID must be upper case letters.
key: 71653ec0-00b5-4c66-a58b-22ecf21704c5
applicable_if: []
label: Withholding Number
value: 1233214-AB
metadata:
type: text
- description: >-
If you have run payroll in the past in GA, find
your DOL account number on notices received from
the Georgia Department of Labor, or call the
agency at (404) 232-3300. If you don’t have an
account number yet, please follow
the instructions here to register your
business with the Georgia Dept. of Labor.
key: 6c0911ab-5860-412e-bdef-6437cd881df5
applicable_if: []
label: DOL Account Number
value: 474747-88
metadata:
type: text
- state: GA
key: taxrates
label: Tax Rates
effective_from: '2022-01-01'
requirements:
- description: >-
Haven't received your assigned rate yet? Find
the new employer rate and enter it here.
key: e0ac2284-8d30-4100-ae23-f85f9574868b
applicable_if: []
label: Total Tax Rate
value: '0.05'
metadata:
type: tax_rate
validation:
type: min_max
min: '0.0004'
max: '0.081'
- state: GA
key: depositschedules
label: Deposit Schedules
effective_from: '2022-01-01'
requirements:
- description: >-
Georgia rejects payments made on the wrong
schedule. GA employers receive their schedule on a
registration verification letter after registering
with the Georgia Dept. of Revenue. If you are
unsure, call the agency at (877) 423-6711. If you
did not register your business yet, please register the
business with the Georgia Dept. of Revenue.
key: 6ddfcbeb-94d3-4003-bfc2-8c6e1ca9f70c
applicable_if: []
label: Deposit Schedule
value: Semi-weekly
metadata:
type: select
options:
- label: Semiweekly
value: Semi-weekly
- label: Monthly
value: Monthly
- label: Quarterly
value: Quarterly
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
put:
tags:
- Tax Requirements
summary: Update State Tax Requirements
operationId: TaxRequirements_updateStateTaxes
description: |-
Update State Tax Requirements
scope: `company_tax_requirements:write`
parameters:
- $ref: '#/components/parameters/company_uuid'
- description: 2-letter US state abbreviation
schema:
type: string
name: state
in: path
required: true
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TaxRequirementsUpdateStateTaxesRequest'
examples:
Example:
value:
requirement_sets:
- key: registrations
effective_from: null
state: GA
requirements:
- key: 71653ec0-00b5-4c66-a58b-22ecf21704c5
value: 1233214-AB
- key: 6c0911ab-5860-412e-bdef-6437cd881df5
value: 474747-22
- key: taxrates
effective_from: '2022-01-01'
state: GA
requirements:
- key: e0ac2284-8d30-4100-ae23-f85f9574868b
value: '0.05'
- key: depositschedules
effective_from: '2022-01-01'
state: GA
requirements:
- key: 6ddfcbeb-94d3-4003-bfc2-8c6e1ca9f70c
value: Semi-weekly
responses:
'200':
description: OK
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/tax_requirements:
get:
tags:
- Tax Requirements
summary: Get All Tax Requirement States
operationId: TaxRequirements_getStates
description: >-
Returns objects describing the states that have tax requirements for the
company
scope: `company_tax_requirements:read`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TaxRequirementsGetStatesResponse'
examples:
Company with requirements in CA and GA:
value:
- state: CA
setup_complete: true
- state: GA
setup_complete: false
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/contractor_payments/preview:
get:
tags:
- Contractor Payments
summary: Preview contractor payment debit date
operationId: ContractorPayments_previewDebitDate
description: >-
Returns a debit_date dependent on the ACH payment speed of the company.
If the payment method is Check or Historical payment, the debit_date
will be the same as the check_date.
scope: `payrolls:read`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: a list of contractor payments.
content:
application/json:
schema:
$ref: '#/components/schemas/ContractorPaymentsPreviewDebitDateRequest'
application/xml:
schema:
$ref: '#/components/schemas/ContractorPaymentsPreviewDebitDateRequest1'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: >-
#/components/schemas/ContractorPaymentsPreviewDebitDateResponse
examples:
Example:
value:
expected_debit_date: '2022-08-16'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
description: Unprocessable Entity (WebDAV)
content:
application/json:
schema:
$ref: >-
#/components/schemas/ContractorPaymentsPreviewDebitDate422Response
examples:
example-1:
value:
errors:
check_date:
- type: Invalid Attribute
message: >-
You cannot issue historical payments for the future,
please choose a date in the past.
full_message: >-
You cannot issue historical payments for the future,
please choose a date in the past.
x-gusto-integration-type:
- embedded
/v1/time_off_policies/{time_off_policy_uuid}:
get:
tags:
- Time Off Policies
summary: Get a time off policy
operationId: TimeOffPolicies_getPolicy
description: |-
Get a time off policy
scope: `time_off_policies:read`
parameters:
- $ref: '#/components/parameters/time_off_policy_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Time-Off-Policy-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
put:
tags:
- Time Off Policies
summary: Update a time off policy
operationId: TimeOffPolicies_updatePolicy
description: |-
Update a time off policy
scope: `time_off_policies:write`
parameters:
- $ref: '#/components/parameters/time_off_policy_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: >-
Can update any attributes of the time off policy except policy_type,
is_active, complete & employees
content:
application/json:
schema:
$ref: '#/components/schemas/TimeOffPoliciesUpdatePolicyRequest'
examples:
example:
value:
name: Hourly Vacation Policy
accrual_method: per_hour_paid
accrual_rate: '4.0'
accrual_rate_unit: '80.0'
paid_out_on_termination: true
accrual_waiting_period_days: 30
carryover_limit_hours: '200.0'
max_accrual_hours_per_year: '120.0'
max_hours: '240.0'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Time-Off-Policy'
examples:
Unlimited Vacation Policy:
value:
uuid: 3f746cd0-dd08-408f-b712-8180c7c621e9
company_uuid: de83cff2-8e7a-448e-a28c-14258a9971c3
name: Unlimited Vacation Policy
policy_type: vacation
accrual_method: unlimited
accrual_rate: null
accrual_rate_unit: null
paid_out_on_termination: false
accrual_waiting_period_days: null
carryover_limit_hours: null
max_accrual_hours_per_year: null
max_hours: null
is_active: true
complete: true
employees: []
Hourly Vacation Policy:
value:
uuid: d86223a1-ec67-4204-8d6a-0f36499c02d0
company_uuid: f43bcd64-7f57-4d4e-9c1a-7c90bab8a358
name: Test Vacation Hourly Policy
policy_type: vacation
accrual_method: per_hour_paid
accrual_rate: '4.0'
accrual_rate_unit: '80.0'
paid_out_on_termination: true
accrual_waiting_period_days: 30
carryover_limit_hours: '200.0'
max_accrual_hours_per_year: '120.0'
max_hours: '240.0'
is_active: true
complete: true
employees: []
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/time_off_policies:
get:
tags:
- Time Off Policies
summary: Get all time off policies
operationId: TimeOffPolicies_getAllPolicies
description: |-
Get all time off policies for a company
scope: `time_off_policies:read`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Time-Off-Policy-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
post:
tags:
- Time Off Policies
summary: Create a time off policy
operationId: TimeOffPolicies_createPolicy
description: |-
Create a time off policy
scope: `time_off_policies:write`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: Requires a policy name, a policy_type, and an accrual_method
content:
application/json:
schema:
$ref: '#/components/schemas/TimeOffPoliciesCreatePolicyRequest'
examples:
Unlimited Policy:
value:
name: Unlimited Vacation Policy
policy_type: vacation
accrual_method: unlimited
Hourly Policy:
value:
name: Test Vacation Hourly Policy
policy_type: vacation
accrual_method: per_hour_paid
accrual_rate: '4.0'
accrual_rate_unit: '80.0'
paid_out_on_termination: true
accrual_waiting_period_days: 30
carryover_limit_hours: '200.0'
max_accrual_hours_per_year: '120.0'
max_hours: '240.0'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Time-Off-Policy'
examples:
Unlimited Vacation Policy:
value:
uuid: 3f746cd0-dd08-408f-b712-8180c7c621e9
company_uuid: de83cff2-8e7a-448e-a28c-14258a9971c3
name: Unlimited Vacation Policy
policy_type: vacation
accrual_method: unlimited
accrual_rate: null
accrual_rate_unit: null
paid_out_on_termination: false
accrual_waiting_period_days: null
carryover_limit_hours: null
max_accrual_hours_per_year: null
max_hours: null
is_active: true
complete: true
employees: []
Hourly Vacation Policy:
value:
uuid: d86223a1-ec67-4204-8d6a-0f36499c02d0
company_uuid: f43bcd64-7f57-4d4e-9c1a-7c90bab8a358
name: Test Vacation Hourly Policy
policy_type: vacation
accrual_method: per_hour_paid
accrual_rate: '4.0'
accrual_rate_unit: '80.0'
paid_out_on_termination: true
accrual_waiting_period_days: 30
carryover_limit_hours: '200.0'
max_accrual_hours_per_year: '120.0'
max_hours: '240.0'
is_active: true
complete: true
employees: []
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/time_off_policies/{time_off_policy_uuid}/add_employees:
put:
tags:
- Time Off Policies
summary: Add employees to a time off policy
operationId: TimeOffPolicies_addEmployeesToPolicy
description: >-
Add employees to a time off policy. Employees are required to have at
least one job to be added to a time off policy. Accepts starting
balances for non-unlimited policies
scope: `time_off_policies:write`
parameters:
- $ref: '#/components/parameters/time_off_policy_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: A list of employee objects containing the employee uuid
content:
application/json:
schema:
$ref: '#/components/schemas/TimeOffPoliciesAddEmployeesToPolicyRequest'
examples:
Unlimited Policy:
value:
employee:
- uuid: 56c672b4-3918-45cd-a3bb-a62ae0ff1307
- uuid: 28e7a45d-32dd-4925-a82a-9a3ccc6d302c
- uuid: f60650da-ba18-417a-b2ab-3c9b6f0fe4f2
Fixed/Hourly Policy:
value:
employee:
- uuid: 56c672b4-3918-45cd-a3bb-a62ae0ff1307
balance: '40.0'
- uuid: 28e7a45d-32dd-4925-a82a-9a3ccc6d302c
balance: '40.0'
- uuid: f60650da-ba18-417a-b2ab-3c9b6f0fe4f2
balance: '20.0'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Time-Off-Policy'
examples:
Unlimited Policy:
value:
uuid: 3f746cd0-dd08-408f-b712-8180c7c621e9
company_uuid: de83cff2-8e7a-448e-a28c-14258a9971c3
name: test policy
policy_type: vacation
accrual_method: unlimited
accrual_rate: null
accrual_rate_unit: null
paid_out_on_termination: false
accrual_waiting_period_days: null
carryover_limit_hours: null
max_accrual_hours_per_year: null
max_hours: null
is_active: true
complete: true
employees:
- uuid: 05ed3150-591e-4f8b-bfd5-55d478edd2d8
Hourly Policy:
value:
uuid: 3f746cd0-dd08-408f-b712-8180c7c621e9
company_uuid: de83cff2-8e7a-448e-a28c-14258a9971c3
name: test policy
policy_type: vacation
accrual_method: per_hour_paid
accrual_rate: '4.0'
accrual_rate_unit: '80.0'
paid_out_on_termination: true
accrual_waiting_period_days: 30
carryover_limit_hours: '200.0'
max_accrual_hours_per_year: '120.0'
max_hours: '240.0'
is_active: true
complete: true
employees:
- uuid: 56c672b4-3918-45cd-a3bb-a62ae0ff1307
balance: '40.0'
- uuid: 28e7a45d-32dd-4925-a82a-9a3ccc6d302c
balance: '40.0'
- uuid: f60650da-ba18-417a-b2ab-3c9b6f0fe4f2
balance: '20.0'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/time_off_policies/{time_off_policy_uuid}/remove_employees:
put:
tags:
- Time Off Policies
summary: Remove employees from a time off policy
operationId: TimeOffPolicies_removeEmployees
description: |-
Remove employees from a time off policy
scope: `time_off_policies:write`
parameters:
- $ref: '#/components/parameters/time_off_policy_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: A list of employee objects containing the employee uuid
content:
application/json:
schema:
$ref: '#/components/schemas/TimeOffPoliciesRemoveEmployeesRequest'
examples:
example:
value:
employee:
- uuid: 56c672b4-3918-45cd-a3bb-a62ae0ff1307
- uuid: 28e7a45d-32dd-4925-a82a-9a3ccc6d302c
- uuid: f60650da-ba18-417a-b2ab-3c9b6f0fe4f2
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Time-Off-Policy'
examples:
example:
value:
uuid: 3f746cd0-dd08-408f-b712-8180c7c621e9
company_uuid: de83cff2-8e7a-448e-a28c-14258a9971c3
name: test policy
policy_type: vacation
accrual_method: unlimited
accrual_rate: null
accrual_rate_unit: null
paid_out_on_termination: false
accrual_waiting_period_days: null
carryover_limit_hours: null
max_accrual_hours_per_year: null
max_hours: null
is_active: true
complete: true
employees:
- uuid: 05ed3150-591e-4f8b-bfd5-55d478edd2d8
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/holiday_pay_policy:
get:
tags:
- Holiday Pay Policies
summary: Get a company's holiday pay policy
operationId: HolidayPayPolicies_getCompanyPolicy
description: |-
Get a company's holiday pay policy
scope: `holiday_pay_policies:read`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Holiday-Pay-Policy-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
post:
tags:
- Holiday Pay Policies
summary: Create a holiday pay policy for a company
operationId: HolidayPayPolicies_createCompanyPolicy
description: |-
Create a holiday pay policy for a company
scope: `holiday_pay_policies:write`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/HolidayPayPoliciesCreateCompanyPolicyRequest
examples:
Example:
value:
federal_holidays:
mlk_day:
selected: true
memorial_day:
selected: true
independence_day:
selected: true
veterans_day:
selected: true
thanksgiving:
selected: true
christmas_day:
selected: true
responses:
'200':
$ref: '#/components/responses/Holiday-Pay-Policy-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
put:
tags:
- Holiday Pay Policies
summary: Update a company's holiday pay policy
operationId: HolidayPayPolicies_updatePolicy
description: |-
Update a company's holiday pay policy
scope: `holiday_pay_policies:write`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/HolidayPayPoliciesUpdatePolicyRequest'
examples:
Example:
value:
version: 1b37938b017c7fd7116bada007072290
federal_holidays:
mlk_day:
selected: true
memorial_day:
selected: true
independence_day:
selected: true
veterans_day:
selected: true
thanksgiving:
selected: true
christmas_day:
selected: true
responses:
'200':
$ref: '#/components/responses/Holiday-Pay-Policy-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
delete:
tags:
- Holiday Pay Policies
summary: Delete a company's holiday pay policy
operationId: HolidayPayPolicies_deletePolicy
description: |-
Delete a company's holiday pay policy
scope: `holiday_pay_policies:write`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'204':
description: No Content
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/holiday_pay_policy/add:
put:
tags:
- Holiday Pay Policies
summary: Add employees to a company's holiday pay policy
operationId: HolidayPayPolicies_addEmployeesToPolicy
description: |-
Add employees to a company's holiday pay policy
scope: `holiday_pay_policies:write`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/HolidayPayPoliciesAddEmployeesToPolicyRequest
examples:
Example:
value:
version: 1b37938b017c7fd7116bada007072290
employees:
- uuid: 1ca3cd25-3eda-48c6-ac88-f0e7fb91a15a
- uuid: fe977550-6621-4cfc-b4af-60b6af58c8ef
responses:
'200':
$ref: '#/components/responses/Holiday-Pay-Policy-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/holiday_pay_policy/remove:
put:
tags:
- Holiday Pay Policies
summary: Remove employees from a company's holiday pay policy
operationId: HolidayPayPolicies_removeEmployees
description: |-
Remove employees from a company's holiday pay policy
scope: `holiday_pay_policies:write`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/HolidayPayPoliciesRemoveEmployeesRequest'
examples:
Example:
value:
version: 1b37938b017c7fd7116bada007072290
employees:
- uuid: 1ca3cd25-3eda-48c6-ac88-f0e7fb91a15a
- uuid: fe977550-6621-4cfc-b4af-60b6af58c8ef
responses:
'200':
$ref: '#/components/responses/Holiday-Pay-Policy-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/paid_holidays:
get:
tags:
- Holiday Pay Policies
summary: Preview a company's paid holidays
operationId: HolidayPayPolicies_previewCompanyPaidHolidays
description: |-
Preview a company's paid holidays
scope: `holiday_pay_policies:read`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/HolidayPayPoliciesPreviewCompanyPaidHolidaysRequest
examples:
Example:
value:
year: '2023'
responses:
'200':
$ref: '#/components/responses/Paid-Holidays-Object'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/time_off_policies/{time_off_policy_uuid}/balance:
put:
tags:
- Time Off Policies
summary: Update employee time off hour balances
operationId: TimeOffPolicies_updateEmployeeBalance
description: |-
Updates time off hours balances for employees for a time off policy
scope: `time_off_policies:write`
parameters:
- $ref: '#/components/parameters/time_off_policy_uuid'
- $ref: '#/components/parameters/VersionHeader'
requestBody:
description: >-
A list of employee objects containing the employee uuid and time off
hours balance
content:
application/json:
schema:
$ref: '#/components/schemas/TimeOffPoliciesUpdateEmployeeBalanceRequest'
examples:
example:
value:
employee:
- uuid: 56c672b4-3918-45cd-a3bb-a62ae0ff1307
balance: '54.0'
- uuid: 28e7a45d-32dd-4925-a82a-9a3ccc6d302c
balance: '80.0'
- uuid: f60650da-ba18-417a-b2ab-3c9b6f0fe4f2
balance: '26.0'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Time-Off-Policy'
examples:
example:
value:
uuid: 3f746cd0-dd08-408f-b712-8180c7c621e9
company_uuid: de83cff2-8e7a-448e-a28c-14258a9971c3
name: test policy
policy_type: vacation
accrual_method: per_hour_paid
accrual_rate: '4.0'
accrual_rate_unit: '80.0'
paid_out_on_termination: true
accrual_waiting_period_days: 30
carryover_limit_hours: '200.0'
max_accrual_hours_per_year: '120.0'
max_hours: '240.0'
is_active: true
complete: true
employees:
- uuid: 56c672b4-3918-45cd-a3bb-a62ae0ff1307
balance: '54.0'
- uuid: 28e7a45d-32dd-4925-a82a-9a3ccc6d302c
balance: '80.0'
- uuid: f60650da-ba18-417a-b2ab-3c9b6f0fe4f2
balance: '26.0'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/time_off_policies/{time_off_policy_uuid}/deactivate:
put:
tags:
- Time Off Policies
summary: Deactivate a time off policy
operationId: TimeOffPolicies_deactivatePolicy
description: |-
Deactivate a time off policy
scope: `time_off_policies:write`
parameters:
- $ref: '#/components/parameters/time_off_policy_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Time-Off-Policy'
examples:
example:
value:
uuid: 3f746cd0-dd08-408f-b712-8180c7c621e9
company_uuid: de83cff2-8e7a-448e-a28c-14258a9971c3
name: test policy
policy_type: vacation
accrual_method: unlimited
accrual_rate: null
accrual_rate_unit: null
paid_out_on_termination: false
accrual_waiting_period_days: null
carryover_limit_hours: null
max_accrual_hours_per_year: null
max_hours: null
is_active: false
complete: true
employees:
- uuid: 05ed3150-591e-4f8b-bfd5-55d478edd2d8
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/notifications/{notification_uuid}:
get:
tags:
- Notifications
summary: Get a notification's details
operationId: Notifications_getDetails
description: >-
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](https://docs.gusto.com/embedded-payroll/docs/partner-notifications)
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`
parameters:
- $ref: '#/components/parameters/notification_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Notification'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/events:
get:
tags:
- Events
summary: Get all events
operationId: Events_get30DayEvents
security:
- ApiKeyAuth: []
description: >-
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`
parameters:
- $ref: '#/components/parameters/starting_after_uuid'
- $ref: '#/components/parameters/resource_uuid'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/event_type'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Event-List'
x-gusto-integration-type:
- embedded
- app-integrations
/v1/companies/{company_uuid}/recovery_cases:
get:
tags:
- Recovery Cases
summary: Get all recovery cases for a company
operationId: RecoveryCases_listForCompany
description: |-
Fetch all recovery cases for a company.
scope: `recovery_cases:read`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Recovery-Case-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
/v1/recovery_cases/{recovery_case_uuid}/redebit:
put:
tags:
- Recovery Cases
summary: Initiate a redebit for a recovery case
operationId: RecoveryCases_initiateRedebit
description: >-
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`
parameters:
- $ref: '#/components/parameters/recovery_case_uuid'
- $ref: '#/components/parameters/VersionHeader'
responses:
'202':
description: Accepted
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
'422':
$ref: '#/components/responses/Unprocessable-Entity-Error-Object'
x-gusto-integration-type:
- embedded
/v1/companies/{company_uuid}/ach_transactions:
get:
tags:
- ACH Transactions
summary: Get all ACH transactions for a company
operationId: AchTransactions_getAllForCompany
description: |-
Fetches all ACH transactions for a company.
scope: `ach_transactions:read`
parameters:
- $ref: '#/components/parameters/company_uuid'
- $ref: '#/components/parameters/contractor_payment_uuid_query'
- $ref: '#/components/parameters/payroll_uuid_query'
- $ref: '#/components/parameters/transaction_type'
- $ref: '#/components/parameters/payment_direction'
- $ref: '#/components/parameters/VersionHeader'
responses:
'200':
$ref: '#/components/responses/Ach-Transaction-List'
'404':
$ref: '#/components/responses/Not-Found-Error-Object'
x-gusto-integration-type:
- embedded
components:
parameters:
pageParam:
description: >-
The page that is requested. When unspecified, will load all objects
unless endpoint forces pagination.
schema:
type: number
in: query
name: page
page:
description: The page that is requested. When unspecified, will load the first page.
schema:
type: number
in: query
name: page
perParam:
description: Number of objects per page. For majority of endpoints will default to 25
schema:
type: number
in: query
name: per
start_date:
in: query
name: start_date
schema:
type: string
example: '2020-01-01'
end_date:
in: query
name: end_date
schema:
type: string
example: '2020-01-31'
bank_account_uuid:
description: The UUID of the bank account
name: bank_account_uuid
in: path
required: true
schema:
type: string
benefit_id:
description: The benefit type in Gusto.
schema:
type: string
name: benefit_id
in: path
required: true
compensation_id:
description: The UUID of the compensation
schema:
type: string
name: compensation_id
in: path
required: true
company_benefit_id:
description: The UUID of the company benefit
schema:
type: string
name: company_benefit_id
in: path
required: true
company_id:
description: The UUID of the company
name: company_id
in: path
required: true
schema:
type: string
company_uuid:
description: The UUID of the company
name: company_uuid
in: path
required: true
schema:
type: string
contractor_id:
description: The UUID of the contractor
name: contractor_id
in: path
required: true
schema:
type: string
contractor_uuid:
description: The UUID of the contractor
name: contractor_uuid
in: path
required: true
schema:
type: string
contractor_payment_id:
description: The UUID of the contractor payment
name: contractor_payment_id
in: path
required: true
schema:
type: string
contractor_payment_uuid:
description: The UUID of the contractor payment
name: contractor_payment_uuid
in: path
required: true
schema:
type: string
department_uuid:
description: The UUID of the department
name: department_uuid
in: path
required: true
schema:
type: string
earning_type_uuid:
description: The UUID of the earning type
schema:
type: string
name: earning_type_uuid
in: path
required: true
effective_date:
in: query
name: effective_date
required: false
schema:
type: string
example: '2020-01-31'
employee_benefit_id:
description: The UUID of the employee benefit.
name: employee_benefit_id
in: path
required: true
schema:
type: string
employee_id:
description: The UUID of the employee
name: employee_id
in: path
required: true
schema:
type: string
employee_uuid:
description: The UUID of the employee
name: employee_uuid
in: path
required: true
schema:
type: string
event_type:
description: >-
A string containing the exact event name (e.g. `employee.created`), or
use a wildcard match to filter for a group of events (e.g. `employee.*`,
`*.created`, `notification.*.created` etc.)
name: event_type
in: query
required: false
schema:
type: string
external_payroll_id:
description: The UUID of the external payroll
name: external_payroll_id
in: path
required: true
schema:
type: string
form_id:
description: The UUID of the form
name: form_id
in: path
required: true
schema:
type: string
garnishment_id:
description: The UUID of the garnishment
name: garnishment_id
in: path
required: true
schema:
type: string
home_address_uuid:
description: The UUID of the home address
name: home_address_uuid
in: path
required: true
schema:
type: string
work_address_uuid:
description: The UUID of the work address
name: work_address_uuid
in: path
required: true
schema:
type: string
job_id:
description: The UUID of the job
schema:
type: string
name: job_id
in: path
required: true
limit:
description: >-
Limits the number of objects returned in a single response, between 1
and 100. The default is 25
name: limit
in: query
required: false
schema:
type: string
location_id:
description: The UUID of the location
name: location_id
in: path
required: true
schema:
type: string
location_uuid:
description: The UUID of the location
name: location_uuid
in: path
required: true
schema:
type: string
payroll_id:
description: The UUID of the payroll
name: payroll_id
in: path
required: true
schema:
type: string
payroll_uuid:
description: The UUID of the payroll
name: payroll_uuid
in: path
required: true
schema:
type: string
pay_schedule_id:
description: The UUID of the pay schedule
name: pay_schedule_id
in: path
required: true
schema:
type: string
payroll_types:
description: >-
regular and/or transition. Multiple options are comma separated. The
default is regular pay periods if nothing is passed in.
name: payroll_types
in: query
required: false
schema:
type: string
document_type:
description: the type of document being generated
name: document_type
in: path
required: true
schema:
type: string
request_uuid:
description: The UUID of the Generated Document Request
name: request_uuid
in: path
required: true
schema:
type: string
signatory_uuid:
description: The UUID of the signatory
name: signatory_uuid
in: path
required: true
schema:
type: string
starting_after_uuid:
description: >-
A cursor for pagination. Returns all events occuring after the specified
UUID (exclusive)
name: starting_after_uuid
in: query
required: false
schema:
type: string
resource_uuid:
description: >-
The UUID of the company. If not specified, will return all events for
all companies.
name: resource_uuid
in: query
required: false
schema:
type: string
time_off_type:
description: >-
The time off type name you want to query data for. ex: 'sick' or
'vacation'
schema:
type: string
required: true
in: query
name: time_off_type
time_off_policy_uuid:
description: The UUID of the company time off policy
name: time_off_policy_uuid
in: path
required: true
schema:
type: string
webhook_subscription_uuid:
description: The webhook subscription UUID.
name: webhook_subscription_uuid
in: path
required: true
schema:
type: string
VersionHeader:
description: >-
Determines the date-based API version associated with your API call. If
none is provided, your application's [minimum API
version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version)
is used.
name: X-Gusto-API-Version
in: header
required: false
schema:
type: string
enum:
- '2024-03-01'
notification_uuid:
description: The UUID of the notification
name: notification_uuid
in: path
required: true
schema:
type: string
invoice_period:
description: The month we are calculating the invoice for. Must be in YYYY-MM format
name: invoice_period
in: path
required: true
schema:
type: string
example: 2020-01
recovery_case_uuid:
description: The UUID of the recovery case
name: recovery_case_uuid
in: path
required: true
schema:
type: string
contractor_payment_uuid_query:
description: The UUID of the contractor payment
name: contractor_payment_uuid
in: query
required: false
schema:
type: string
payroll_uuid_query:
description: The UUID of the payroll
name: payroll_uuid
in: query
required: false
schema:
type: string
transaction_type:
description: >-
Used to filter the ACH transactions to only include those with a
specific transaction type, such as "Credit employee pay".
name: transaction_type
in: query
required: false
schema:
type: string
payment_direction:
description: >-
Used to filter the ACH transactions to only include those with a
specific payment direction, either "credit" or "debit".
name: payment_direction
in: query
required: false
schema:
type: string
responses:
Unprocessable-Entity-Error-Object:
description: >
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](https://docs.gusto.com/embedded-payroll/docs/error-categories)
guide for more details.
content:
application/json:
schema:
$ref: '#/components/schemas/Unprocessable-Entity-Error-Object'
examples:
Example:
value:
errors:
- error_key: base
category: payroll_blocker
message: >-
Company must complete all onboarding requirements in order
to run payroll.
metadata:
key: needs_onboarding
Not-Found-Error-Object:
description: >
Not Found
The requested resource does not exist. Make sure the provided ID/UUID is
valid.
Employment-Not-Found-Error-Object:
description: >-
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.
content:
application/json:
schema:
$ref: '#/components/schemas/Unprocessable-Entity-Error-Object'
examples:
Example:
value:
errors:
- error_key: employement
category: incorrect_state
message: The employee's employment is not in the right state.
Payroll-Blockers-Error:
description: Payroll Blockers Error
content:
application/json:
schema:
$ref: '#/components/schemas/Payroll-Blockers-Error'
examples:
Example:
value:
errors:
- error_key: base
category: payroll_blocker
message: >-
Company must complete all onboarding requirements in order
to run payroll.
metadata:
key: needs_onboarding
Authentication-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Authentication'
examples:
Example:
value:
access_token: 737HdeXfIqgx-NfaUFRuhV7JDe6ns6ptanJSMuQzjlc
token_type: bearer
expires_in: 7200
refresh_token: iEjL96L9Pndwmi-xVX3Q-xbrvvhnjHYGX87sopgGJ8E
scope: ach_transactions:read benefits:read companies:read
created_at: '2023-09-12T16:42:25.000-07:00'
Holiday-Pay-Policy-Object:
description: Holiday Pay Policy Object Example
content:
application/json:
schema:
$ref: '#/components/schemas/Holiday-Pay-Policy'
examples:
Example:
value:
version: 1b37938b017c7fd7116bada007072290
company_uuid: b7845189-f12b-4378-918a-d2b9de3dc4ea
federal_holidays:
new_years_day:
selected: false
name: New Year's Day
date: January 1
mlk_day:
selected: true
name: Martin Luther King, Jr. Day
date: Third Monday in January
presidents_day:
selected: false
name: Presidents' Day
date: Third Monday in February
memorial_day:
selected: true
name: Memorial Day
date: Last Monday in May
juneteenth:
selected: false
name: Juneteenth
date: June 19
independence_day:
selected: true
name: Independence Day
date: July 4
labor_day:
selected: false
name: Labor Day
date: First Monday in September
columbus_day:
selected: false
name: Columbus Day (Indigenous Peoples' Day)
date: Second Monday in October
veterans_day:
selected: true
name: Veterans Day
date: November 11
thanksgiving:
selected: true
name: Thanksgiving
date: Fourth Thursday in November
christmas_day:
selected: true
name: Christmas Day
date: December 25
employees:
uuid: 1ca3cd25-3eda-48c6-ac88-f0e7fb91a15a
Paid-Holidays-Object:
description: Paid Holidays Object Example
content:
application/json:
schema:
$ref: '#/components/schemas/Paid-Holidays'
examples:
Example:
value:
holiday_key: veterans_day
holiday_name: Veterans Day
start_date: '2023-11-11'
end_date: '2023-11-11'
Department-Object:
description: Department Object Example
content:
application/json:
schema:
$ref: '#/components/schemas/Department'
examples:
Example:
value:
title: Stage Hand
version: d90440dd464601d1c8f4e9e240dfb7a6
uuid: 56260b3d-c375-415c-b77a-75d99f717193
company_uuid: 7087a288-8349-4632-b92e-bc94fb79f29e
employees:
- uuid: 41199375-a999-4414-9f40-d9bf596b134d
contractors:
- uuid: 3488549f-60e4-494f-a34a-9d8aad3aabf5
Department-List:
description: List of departments
content:
application/json:
schema:
$ref: '#/components/schemas/DepartmentsGetAllWithEmployeesResponse'
examples:
Example:
value:
- title: Stage Hand
version: d90440dd464601d1c8f4e9e240dfb7a6
uuid: 56260b3d-c375-415c-b77a-75d99f717193
company_uuid: 7087a288-8349-4632-b92e-bc94fb79f29e
employees:
- uuid: 41199375-a999-4414-9f40-d9bf596b134d
contractors: []
- title: Actors
version: 34f39a30b45d077cb83aed2df4810d74
uuid: ec5c8a85-3233-4f39-a9f5-fb1ab7b5f5f3
company_uuid: 7087a288-8349-4632-b92e-bc94fb79f29e
employees:
- uuid: 7ee4aca1-814b-4034-b0f8-07f93cc679d1
contractors: []
- title: Band
version: 1fe3076d35ef7c97d0ae68c5f4df0acd
uuid: 1802465d-4f68-4865-920c-1307ab095f12
company_uuid: 7087a288-8349-4632-b92e-bc94fb79f29e
employees:
- uuid: a73955be-c009-44dc-915e-6246e2bdedbb
contractors:
- uuid: 3488549f-60e4-494f-a34a-9d8aad3aabf5
Employee-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Employee'
examples:
Example:
value:
version: 1c7ba9d62c8bafbfff998ffccad5d296
uuid: 4b3f930f-82cd-48a8-b797-798686e12e5e
first_name: Isom
middle_initial: null
last_name: Jaskolski
email: dane7757869450111550@botsford.net
company_uuid: a007e1ab-3595-43c2-ab4b-af7a5af2e365
manager_uuid: 5e53e257-c8d6-45aa-aa8a-ec99283a3acd
department: Stage Hand
department_uuid: 56260b3d-c375-415c-b77a-75d99f717193
terminated: false
two_percent_shareholder: false
onboarded: true
onboarding_status: onboarding_completed
jobs:
- title: Client Support Director
version: 6c0ed1521e8b86eb36bd4455a63a2dac
uuid: 428a653a-0745-4db4-9c80-558288d416fa
employee_uuid: f0689739-1985-49f3-b9ba-84562e71e85f
current_compensation_uuid: c9fd719b-8b07-48f3-8a4c-f447d2c59669
payment_unit: Year
primary: true
compensations:
- version: 2cd4b18662395eb53bcf80d5b5447f36
uuid: 145660ed-6fcc-4211-8915-18e2786290a2
payment_unit: Year
flsa_status: Exempt
job_uuid: 857feae3-414e-445d-b28b-2eb3ef50155e
effective_date: '2021-01-20'
rate: '70000.00'
adjust_for_minimum_wage: false
minimum_wages: []
rate: '70000.00'
hire_date: '2020-01-20'
eligible_paid_time_off:
- name: Sick Hours
policy_name: Sick Policy
policy_uuid: 9940d205-9904-4e55-9fec-652628e84af7
accrual_unit: Hour
accrual_rate: '208.0'
accrual_method: per_hour_worked
accrual_period: Year
accrual_balance: '31.8'
maximum_accrual_balance: '240.0'
paid_at_termination: false
- name: Vacation Hours
policy_name: Vacation Policy
policy_uuid: ab59de61-239f-4805-933b-0e3360ed291c
accrual_unit: Hour
accrual_rate: '208.0'
accrual_period: Year
accrual_balance: '77.8'
maximum_accrual_balance: '240.0'
paid_at_termination: true
terminations: []
custom_fields:
- description: Employee Level
id: ee515986-f3ca-49da-b576-2691b95262f9X
company_custom_field_id: ea7e5d57-6abb-47d7-b654-347c142886c0
name: employee_level
type: text
value: '2'
selection_options: null
- description: What is your t-shirt size?
id: 3796e08d-c2e3-434c-b4de-4ce1893e7b59X
company_custom_field_id: 299650e4-e970-4acf-9bf0-6f05585d20ba
name: t-shirt size
type: text
value: md
selection_options: null
- description: Which is your favorite fruit?
id: 3796e08d-c2e3-434c-b4de-4ce1893e7b59X
company_custom_field_id: 024ec137-6c92-43a3-b061-14a9720531d6
name: favorite fruit
type: radio
value: apple
selection_options:
- apple
- banana
- orange
garnishments: []
date_of_birth: '1986-06-25'
has_ssn: false
ssn: ''
phone: '1234567890'
preferred_first_name: Angel
work_email: angel.jaskolski@example.com
Employee-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeesListCompanyEmployeesResponse'
examples:
Example:
value:
- version: 414dedaca594b77135e0b8d2f398516d
uuid: 9779767c-6044-48e0-bf68-aeb370b9a2e7
first_name: Nicole
middle_initial: M
last_name: Boehm
email: kory7757869450111548@barton-hermiston.io
company_uuid: c44d66dc-c41b-4a60-9e25-5e93ff8583f2
manager_uuid: 5e53e257-c8d6-45aa-aa8a-ec99283a3acd
department: Stage Hand
department_uuid: 1802465d-4f68-4865-920c-1307ab095f12
terminated: false
two_percent_shareholder: false
onboarded: true
onboarding_status: onboarding_completed
jobs:
- title: Client Support Manager
version: 91179081a7309c9fbd31bb3cf7b9893e
uuid: 5d5e3ce5-ea8f-4885-90e5-7ebaed03f7c5
employee_uuid: a987bce1-6d06-43f8-9978-9db886f479fb
current_compensation_uuid: 798a962f-0fcf-491e-9b71-cfa6a1db114f
payment_unit: Hour
primary: true
compensations:
- version: 233f0096a8015e62d9795fadf1fd300d
uuid: 94f17a77-cfe5-436a-af94-422bbf8248ff
payment_unit: Hour
flsa_status: Nonexempt
job_uuid: 64711ac0-83ff-4aaf-bec1-db72f5a44e56
effective_date: '2021-01-20'
rate: '22.00'
adjust_for_minimum_wage: false
minimum_wages: []
rate: '22.00'
hire_date: '2020-01-20'
eligible_paid_time_off:
- name: Sick Hours
policy_name: Sick Policy
policy_uuid: 9940d205-9904-4e55-9fec-652628e84af7
accrual_unit: Hour
accrual_rate: '208.0'
accrual_method: per_hour_worked
accrual_period: Year
accrual_balance: '71.0'
maximum_accrual_balance: '240.0'
paid_at_termination: false
- name: Vacation Hours
policy_name: Vacation Policy
policy_uuid: 8b312f0e-30e7-4810-9c06-1177a6484f2d
accrual_unit: Hour
accrual_rate: '208.0'
accrual_period: Year
accrual_balance: '34.0'
maximum_accrual_balance: '240.0'
paid_at_termination: true
terminations: []
garnishments: []
date_of_birth: '1996-05-08'
has_ssn: true
ssn: ''
phone: '1234567890'
preferred_first_name: Vanessa
work_email: vanessa.boehm@example.com
- version: e867459e1360fa71e78b88142923d341
uuid: d7cb289a-af62-4120-9cd5-acda324b5c04
first_name: Maci
middle_initial: M
last_name: Cassin
email: claud_reinger7757869450111549@gutkowski.net
company_uuid: 4522d043-5731-406d-a129-de1808042a32
manager_uuid: 5e53e257-c8d6-45aa-aa8a-ec99283a3acd
department: Band
department_uuid: 1802465d-4f68-4865-920c-1307ab095f12
terminated: false
two_percent_shareholder: false
onboarded: true
onboarding_status: onboarding_completed
jobs:
- title: Account Director
version: d0e719137f89ca3dd334dd4cc248ffbb
uuid: 62a00cf7-342b-465e-a151-ecd295152be0
employee_uuid: 5e53e257-c8d6-45aa-aa8a-ec99283a3acd
current_compensation_uuid: 93e5da92-173b-4faa-a0bd-d1a8dee68be0
payment_unit: Year
primary: true
compensations:
- version: 994b75511d1debac5d7e2ddeae13679f
uuid: 1bad5177-c4ed-432e-ab43-66055d40c3a5
payment_unit: Year
flsa_status: Exempt
job_uuid: 1214875b-f43d-4267-bf2f-a6d2c298ff3d
effective_date: '2021-01-20'
rate: '78000.00'
adjust_for_minimum_wage: false
minimum_wages: []
rate: '78000.00'
hire_date: '2020-01-20'
eligible_paid_time_off:
- name: Sick Hours
policy_name: Sick Policy
policy_uuid: 8b312f0e-30e7-4810-9c06-1177a6484f2d
accrual_unit: Hour
accrual_rate: '208.0'
accrual_method: per_hour_worked
accrual_period: Year
accrual_balance: '74.0'
maximum_accrual_balance: '240.0'
paid_at_termination: false
- name: Vacation Hours
policy_name: Vacation Policy
policy_uuid: 0d4c755e-50ac-4c54-b46e-81bdfa03da5b
accrual_unit: Hour
accrual_rate: '208.0'
accrual_period: Year
accrual_balance: '16.0'
maximum_accrual_balance: '240.0'
paid_at_termination: true
terminations: []
garnishments: []
custom_fields:
- description: Employee Level
id: ee515986-f3ca-49da-b576-2691b95262f9X
company_custom_field_id: ea7e5d57-6abb-47d7-b654-347c142886c0
name: employee_level
type: text
value: '2'
selection_options: null
- description: What is your t-shirt size?
id: 3796e08d-c2e3-434c-b4de-4ce1893e7b59X
company_custom_field_id: 299650e4-e970-4acf-9bf0-6f05585d20ba
name: t-shirt size
type: text
value: md
selection_options: null
- description: Which is your favorite fruit?
id: 3796e08d-c2e3-434c-b4de-4ce1893e7b59X
company_custom_field_id: 024ec137-6c92-43a3-b061-14a9720531d6
name: favorite fruit
type: radio
value: apple
selection_options:
- apple
- banana
- orange
date_of_birth: '1995-09-21'
has_ssn: true
ssn: ''
phone: '1234567890'
preferred_first_name: Denis
work_email: denis.cassin@example.com
Employee-Address-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Employee-Address'
examples:
Example:
value:
uuid: 56260b3d-c375-415c-b77a-75d99f717193
employee_id: 12345
street_1: 644 Fay Vista
street_2: Suite 842
city: Richmond
state: VA
zip: '23218'
country: USA
active: false
effective_date: '2021-01-01'
courtesy_withholding: true
Employee-Address-List:
description: List of employee addresses
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeAddressesGetHomeAddressesResponse'
examples:
Example:
value:
- uuid: 56260b3d-c375-415c-b77a-75d99f717193
employee_uuid: 7087a288-8349-4632-b92e-bc94fb79f29e
street_1: 644 Fay Vista
street_2: Suite 842
city: Richmond
state: VA
zip: '23218'
country: USA
active: false
effective_date: '2021-01-01'
courtesy_withholding: true
- uuid: d9f74049-8769-4fba-8e0f-eceef2da4e6b
employee_uuid: 7087a288-8349-4632-b92e-bc94fb79f29e
street_1: 100 5th Ave
street_2: Suite 555
city: New York
state: NY
zip: '10001'
country: USA
active: true
effective_date: '2022-03-03'
courtesy_withholding: true
Employee-Work-Address-List:
description: List of employee work addresses
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeAddressesListWorkAddressesResponse'
examples:
Example:
value:
- version: 139f9769a2e543e6a1259173e1ee3b8d
uuid: fc5b87dc-8d88-400d-b2da-c3587a7e5b15
employee_uuid: 7597f3e3-31d4-4953-83a5-f95be78d2fe2
location_uuid: d9456c94-f561-40d2-afec-919da5f59196
effective_date: '2022-01-01'
active: false
street_1: 800 Adolfo Gardens
street_2: Suite 419
city: Bremen
state: AL
zip: '35033'
country: USA
- version: bbe8d4c741339c6b9e0e2e1c1b120816
uuid: be1c2e24-af86-4c36-b34e-3a55dbcdbdab
employee_uuid: 7597f3e3-31d4-4953-83a5-f95be78d2fe2
location_uuid: 6a119be7-b4b0-4e27-aaa0-89d5f2524635
effective_date: '2023-01-01'
active: true
street_1: 2216 Icie Villages
street_2: Apt. 798
city: Big Delta
state: AK
zip: '99737'
country: USA
Company-Onboarding-Status-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Company-Onboarding-Status'
examples:
Example:
value:
uuid: c44d66dc-c41b-4a60-9e25-5e93ff8583f2
onboarding_completed: false
onboarding_steps:
- title: Add Your Company's Addresses
id: add_addresses
required: true
completed: true
skippable: false
requirements: []
- title: Enter Your Federal Tax Information
id: federal_tax_setup
required: true
completed: true
skippable: false
requirements: []
- title: Select Industry
id: select_industry
required: true
completed: true
skippable: false
requirements: []
- title: Add Your Bank Account
id: add_bank_info
required: true
completed: true
skippable: false
requirements: []
- title: Add Your Employees
id: add_employees
required: true
completed: true
skippable: true
requirements:
- add_addresses
- title: Enter Your State Tax Information
id: state_setup
required: true
completed: false
skippable: false
requirements:
- add_addresses
- add_employees
- title: Select a Pay Schedule
id: payroll_schedule
required: true
completed: false
skippable: false
requirements: []
- title: Sign Documents
id: sign_all_forms
required: true
completed: false
skippable: false
requirements:
- add_employees
- federal_tax_setup
- state_setup
- add_bank_info
- payroll_schedule
- title: Verify Your Bank Account
id: verify_bank_info
required: true
completed: false
skippable: false
requirements:
- add_bank_info
Webhook-Subscription-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook-Subscription'
examples:
Example:
value:
uuid: c5fdae57-5483-4529-9aae-f0edceed92d4
url: https://the-partner-app.com/subscriber
status: verified
subscription_types:
- BankAccount
- Company
- CompanyBenefit
- Contractor
- ContractorPayment
- Employee
- EmployeeBenefit
- EmployeeJobCompensation
- ExternalPayroll
- Form
- Location
- Notification
- Payroll
- PaySchedule
- Signatory
Webhook-Subscriptions-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksListSubscriptionsResponse'
examples:
Example:
value:
- uuid: dcceb38a-46be-4110-9d1d-1b3384c3b906
url: >-
https://6116-2603-6000-8900-3d42-58e7-f1e3-b394-1f21.ngrok.io/subscriber
status: pending
subscription_types:
- BankAccount
- Company
- CompanyBenefit
- Contractor
- ContractorPayment
- Employee
- EmployeeBenefit
- EmployeeJobCompensation
- ExternalPayroll
- Form
- Location
- Notification
- Payroll
- PaySchedule
- Signatory
Company-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Company'
examples:
Example:
value:
ein: 00-0000001
entity_type: C-Corporation
tier: core
is_suspended: false
company_status: Approved
uuid: c7a07c73-a703-4462-9343-1b181182b6e0
name: Shoppe Studios LLC
trade_name: Record Shoppe
slug: record-shoppe
is_partner_managed: false
pay_schedule_type: by_department
join_date: '2023-03-01'
funding_type: ach
locations:
- street_1: 412 Kiera Stravenue
street_2: Suite 391
city: San Francisco
state: CA
zip: '94107'
country: USA
active: true
- street_1: 644 Fay Vista
street_2: Suite 842
city: Richmond
state: VA
zip: '23218'
country: USA
active: true
compensations:
hourly:
- name: Overtime
multiple: 1.5
- name: Double overtime
multiple: 2
- name: Regular
multiple: 1
- name: Outstanding vacation
multiple: 1
- name: Holiday
multiple: 1
- name: Emergency sick - self care
multiple: 1
- name: Emergency sick - caring for others
multiple: 1
- name: FMLA Public Health Emergency Leave
multiple: 1
- name: Regular Hours
multiple: 1
fixed:
- name: Bonus
- name: Commission
- name: Paycheck Tips
- name: Cash Tips
- name: Correction Payment
- name: Severance
- name: Minimum Wage Adjustment
- name: Reimbursement
paid_time_off:
- name: Vacation Hours
- name: Sick Hours
- name: Holiday Hours
primary_signatory:
first_name: Alda
middle_initial: ''
last_name: Carter
phone: 1-565-710-7558
email: louie.hessel7757869450111547@zemlak.biz
home_address:
street_1: 524 Roob Divide
street_2: Suite 565
city: San Francisco
state: CA
zip: '94107'
country: USA
primary_payroll_admin:
first_name: Ian
last_name: Labadie
phone: 1-565-710-7559
email: louie.hessel7757869450111547@zemlak.biz
Signatory-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Signatory'
examples:
Example:
value:
title: Owner
version: 49ea586f528411f5cfadfd54452b2423
uuid: f8c653dc-0094-41fb-8670-45d6399afade
first_name: Bob
last_name: Johnson
phone: '4239879876'
birthday: '2002-10-31'
email: olin.okuneva@denesik.us
is_admin: false
has_ssn: true
home_address:
street_1: 524 Roob Divide
street_2: Suite 565
city: San Francisco
state: CA
zip: '94107'
country: USA
identity_verification_status: Skipped
Contractor-Address-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Contractor-Address'
examples:
Example:
value:
version: 23323096a8015e32d9795fadf1fd300d
contractor_uuid: 9779767c-6044-48e0-bf68-aeb370b9a2e7
street_1: 999 Kiera Stravenue
street_2: Suite 391
city: San Francisco
state: CA
zip: 94107
country: USA
active: true
Employment-History-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeEmploymentsGetHistoryResponse'
examples:
Example:
value:
- hire_date: '2023-05-30'
termination_date: null
file_new_hire_report: true
two_percent_shareholder: false
employment_status: seasonal
- hire_date: '2021-02-02'
termination_date: '2023-03-01'
file_new_hire_report: false
two_percent_shareholder: false
employment_status: full_time
Rehire-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Rehire'
examples:
Example:
value:
version: 2e930d43acbdb241f8f14a2d531fa417
employee_uuid: da441196-43a9-4d23-ad5d-f37ce6bb99c0
active: false
effective_date: '2024-01-01'
file_new_hire_report: false
work_location_uuid: d2c80d44-857b-4d4d-bce4-23ae52cc863b,
two_percent_shareholder: false
employment_status: full_time
Unprocessed-Termination-Pay-Period-List:
description: Example response
content:
application/json:
schema:
$ref: >-
#/components/schemas/PaySchedulesGetUnprocessedTerminationPayPeriodsResponse
examples:
Example:
value:
- start_date: '2023-01-11'
end_date: '2023-01-24'
check_date: '2023-01-28'
debit_date: '2023-01-26'
employee_name: Mary Warner
employee_uuid: 094f6ded-a790-4651-87e6-4a7f15dec7c6
pay_schedule_uuid: 00ebc4a4-ec88-4435-8f45-c505bb63e501
- start_date: '2023-01-25'
end_date: '2023-02-07'
check_date: '2023-02-10'
debit_date: '2023-02-08'
employee_name: Mary Warner
employee_uuid: 094f6ded-a790-4651-87e6-4a7f15dec7c6
pay_schedule_uuid: 00ebc4a4-ec88-4435-8f45-c505bb63e501
Accruing-Time-Off-Hour-Object:
description: Example response
content:
application/json:
schema:
$ref: >-
#/components/schemas/TimeOffPoliciesCalculateAccruingTimeOffHoursResponse
examples:
Example:
value:
- time_off_policy_uuid: c3a15554-f124-415d-b2c4-90b430fd8eb1
hours: '3.2'
- time_off_policy_uuid: 386fc48d-52d2-4009-87b3-368f74f6b3df
hours: '6.0'
Pay-Schedule-Assignment-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Pay-Schedule-Assignment'
examples:
Example:
value:
type: by_employee
employees:
employee_uuid: f0238368-f2cf-43e2-9a07-b0265f2cec69
pay_schedule_uuid: c277ac52-9871-4a96-a1e6-0c449684602a
Pay-Schedule-Assignment-Preview-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Pay-Schedule-Assignment-Preview'
examples:
Example:
value:
type: hourly_salaried
employee_changes:
employee_uuid: 43b39ada-dc49-4879-9594-fe95f67ae434
first_name: Penny
last_name: Parker
pay_frequency: Twice per month — Salaried pay schedule
first_pay_period:
pay_schedule_uuid: 3f029a58-155d-4c30-8361-cc266b2c1f11
start_date: '2023-07-01'
end_date: '2023-08-01'
check_date: '2023-08-02'
transition_pay_period:
start_date: '2023-06-20'
end_date: '2023-06-30'
Benefit-Summary-Object:
description: Benefit summary response
content:
application/json:
schema:
$ref: '#/components/schemas/Benefit-Summary'
examples:
Example:
value:
description: Simple IRA
start_date: '2022-01-01'
end_date: '2022-12-31'
company_benefit_deduction: 60
company_benefit_contribution: 30
employees:
- uuid: 54b7114f-f5e2-4f4b-911b-5cd5ad9032b0
company_benefit_deduction: 60
company_benefit_contribution: 30
benefit_deduction: 660
benefit_contribution: 330
gross_pay: 18000
payroll_benefits:
- payroll_uuid: 8cc3471b-9da5-47df-88ea-f238c7cb968b
payroll_type: Regular
check_date: '2022-03-01'
gross_pay: 3000
company_benefit_deduction: 10
company_benefit_contribution: 5
pay_period:
start_date: '2022-02-01'
end_date: '2022-02-28'
- payroll_uuid: d9d92786-722b-4bf7-bb32-79140418d349
payroll_type: Bonus
check_date: '2022-12-31'
gross_pay: 3000
company_benefit_deduction: 20
company_benefit_contribution: 10
pay_period:
start_date: nil
end_date: nil
Company-Benefit-With-Employee-Benefits-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Company-Benefit-With-Employee-Benefits'
examples:
Example:
value:
description: Kaiser Permanente
version: 98jr3289h3298hr9329gf9egskt3kagri32qqgiqe3872
uuid: d2cec746-caee-464a-bcaf-00d93f7049c9
active: true
deletable: true
supports_percentage_amounts: true
responsible_for_employer_taxes: false
responsible_for_employee_w2: false
employee_benefits:
- employee_uuid: ae44a0b2-3c89-41e1-91c8-5f8224a779ca
company_benefit_uuid: d2cec746-caee-464a-bcaf-00d93f7049c9
active: true
deduct_as_percentage: false
employee_deduction: 3
company_contribution: 0
uuid: 9988f241-9aee-4383-bfca-eac79cf58135
contribution:
type: amount
value: 0
Employee-Pay-Stubs-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/PayrollsGetEmployeePayStubsResponse'
examples:
Example:
description: OK
value:
- uuid: d2cec746-caee-464a-bcaf-00d93f7049c9
check_date: '2023-11-24'
gross_pay: 880
net_pay: 541.02
payroll_uuid: a039cafb-745e-4af4-bf1e-935a86fc18e0
check_amount: 500.2
Signatory-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/SignatoriesGetCompanySignatoriesResponse'
examples:
Example:
value:
- title: Owner
version: 49ea586f528411f5cfadfd54452b2423
uuid: f8c653dc-0094-41fb-8670-45d6399afade
first_name: Bob
last_name: Johnson
phone: '4239879876'
birthday: '2002-10-31'
email: olin.okuneva@denesik.us
is_admin: false
has_ssn: true
home_address:
street_1: 524 Roob Divide
street_2: Suite 565
city: San Francisco
state: CA
zip: '94107'
country: USA
identity_verification_status: Skipped
External-Payroll-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/External-Payroll'
examples:
Example:
value:
uuid: c5fdae57-5483-4529-9aae-f0edceed92d4
company_uuid: bcb305b0-2855-4025-8d22-e484a9e6b7c9
check_date: '2022-06-03'
payment_period_start_date: '2022-05-15'
payment_period_end_date: '2022-05-30'
status: unprocessed
external_payroll_items:
- employee_uuid: 44f7cba9-7a3d-4f08-b7bd-6fcf5211f8ca
earnings:
- amount: 10000
hours: 0
earning_type: CompanyPayType
earning_id: 1
- amount: 500
hours: 0
earning_type: CompanyEarningType
earning_id: 4
benefits:
- benefit_id: 22
company_contribution_amount: 100
employee_deduction_amount: 50
- benefit_id: 25
company_contribution_amount: 0
employee_deduction_amount: 300
taxes:
- tax_id: 1
amount: 400
- tax_id: 2
amount: 60
applicable_earnings:
- earning_type: CompanyPayType
earning_id: 1
name: Regular Wages
input_type: amount
category: default
- earning_type: CompanyEarningType
earning_id: 4
name: Cash Tips
input_type: amount
category: default
applicable_benefits:
- description: Kaiser
id: 22
active: true
- description: HSA
id: 25
active: true
applicable_taxes:
- id: 1
name: Federal Income Tax
employer_tax: false
resident_tax: false
- id: 2
name: Social Security
employer_tax: false
resident_tax: false
metadata:
deletable: true
External-Payroll-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalPayrollsListForCompanyResponse'
examples:
Example:
value:
- uuid: c5fdae57-5483-4529-9aae-f0edceed92d4
company_uuid: bcb305b0-2855-4025-8d22-e484a9e6b7c9
check_date: '2022-06-03'
payment_period_start_date: '2022-05-15'
payment_period_end_date: '2022-05-30'
status: unprocessed
External-Payroll-Tax-Suggestions-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalPayrollsGetTaxSuggestionsResponse'
examples:
Example:
value:
- employee_uuid: d21848d5-446f-48a8-9430-30fbefeabda4
tax_suggestions:
- tax_id: 1
amount: 500
- tax_id: 2
amount: 100
- tax_id: 4
amount: 30
Tax-Liabilities-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalPayrollsGetTaxLiabilitiesResponse'
examples:
Example:
value:
- tax_id: 1
tax_name: Federal Income Tax
last_unpaid_external_payroll_uuid: null
possible_liabilities:
- liability_amount: 0
payroll_check_date: null
external_payroll_uuid: null
- liability_amount: 3000
payroll_check_date: '2022-06-01'
external_payroll_uuid: 1bf1efe1-72d4-4e6e-a181-611f3ea66435
- tax_id: 2
tax_name: Social Security
last_unpaid_external_payroll_uuid: null
possible_liabilities:
- liability_amount: 0
payroll_check_date: null
external_payroll_uuid: null
- liability_amount: 50
payroll_check_date: '2022-06-01'
external_payroll_uuid: 1bf1efe1-72d4-4e6e-a181-611f3ea66435
Flow-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Flow'
examples:
Example:
value:
url: >-
https://flows.gusto-demo.com/flows/lO2BHHAMCScPVV9G5WEURW0Im_nP9mGYloQgjUWbenQ
expires_at: '2021-12-28 04:25:48'
Form-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Form'
examples:
Example:
value:
title: Direct Deposit Authorization
description: >-
We need you to sign paperwork to authorize us to debit and
credit your bank account and file and pay your taxes.
uuid: 48cdd5ec-a4dd-4840-a424-ad79f38d8408
name: company_direct_deposit
draft: false
requires_signing: true
Form-Object-Pdf:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Form-Pdf'
examples:
Example:
value:
uuid: 48cdd5ec-a4dd-4840-a424-ad79f38d8408
document_url: >-
https://app.gusto-demo.com/assets/forms/7757842065202782/original/company_direct_deposit20211007-48226-gsqo8k.pdf?1633667020
Form-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyFormsGetAllFormsResponse'
examples:
Example:
value:
- title: Direct Deposit Authorization
description: >-
We need you to sign paperwork to authorize us to debit and
credit your bank account and file and pay your taxes.
uuid: 48cdd5ec-a4dd-4840-a424-ad79f38d8408
name: company_direct_deposit
draft: false
requires_signing: true
Industry-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Industry'
examples:
Example:
value:
title: Computer Training
company_uuid: 423dd616-6dbc-4724-938a-403f6217a933
naics_code: '611420'
sic_codes:
- '8243'
Job-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
examples:
Example:
value:
title: Account Director
version: d0e719137f89ca3dd334dd4cc248ffbb
uuid: d6d1035e-8a21-4e1d-89d5-fa894f9aff97
employee_uuid: 948daac8-4355-4ece-9e2a-229898accb22
current_compensation_uuid: ea8b0b90-1112-4f9d-bb93-bf029bc8537a
payment_unit: Year
primary: true
compensations:
- version: 994b75511d1debac5d7e2ddeae13679f
uuid: ea8b0b90-1112-4f9d-bb93-bf029bc8537a
payment_unit: Year
flsa_status: Exempt
job_uuid: d6d1035e-8a21-4e1d-89d5-fa894f9aff97
effective_date: '2021-01-20'
rate: '78000.00'
adjust_for_minimum_wage: false
minimum_wages: []
rate: '78000.00'
hire_date: '2020-01-20'
Job-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/JobsAndCompensationsGetEmployeeJobsResponse'
examples:
Example:
value:
- title: Client Support Director
version: 6c0ed1521e8b86eb36bd4455a63a2dac
uuid: d6d1035e-8a21-4e1d-89d5-fa894f9aff97
employee_uuid: 948daac8-4355-4ece-9e2a-229898accb22
current_compensation_uuid: ea8b0b90-1112-4f9d-bb93-bf029bc8537a
payment_unit: Year
primary: true
compensations:
- version: 2cd4b18662395eb53bcf80d5b5447f36
uuid: ea8b0b90-1112-4f9d-bb93-bf029bc8537a
payment_unit: Year
flsa_status: Exempt
job_uuid: d6d1035e-8a21-4e1d-89d5-fa894f9aff97
effective_date: '2021-01-20'
rate: '70000.00'
adjust_for_minimum_wage: false
minimum_wages: []
rate: '70000.00'
hire_date: '2020-01-20'
Employee-Federal-Tax-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Employee-Federal-Tax'
examples:
Example:
value:
version: 56a489ce86ed6c1b0f0cecc4050a0b01
filing_status: Single
extra_withholding: '0.0'
two_jobs: true
dependents_amount: '0.0'
other_income: '0.0'
deductions: '0.0'
employee_id: 29
w4_data_type: rev_2020_w4
Location-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Location'
examples:
Example:
value:
version: 7d9753112507b9dda4fb97910f39b06e
company_uuid: 6bf7807c-a5a0-4f4d-b2e7-3fbb4b2299fb
phone_number: '5825710808'
uuid: 04552eb9-7829-4b18-ae96-6983552948df
street_1: 412 Kiera Stravenue
street_2: Suite 391
city: San Francisco
state: CA
zip: '94107'
country: USA
active: true
filing_address: false
mailing_address: false
created_at: '2023-09-12T16:42:25.000-07:00'
updated_at: '2023-09-12T16:42:25.000-07:00'
Location-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/LocationsGetCompanyLocationsResponse'
examples:
Example:
value:
- version: 7d9753112507b9dda4fb97910f39b06e
company_uuid: 6bf7807c-a5a0-4f4d-b2e7-3fbb4b2299fb
phone_number: '5825710808'
uuid: 04552eb9-7829-4b18-ae96-6983552948df
street_1: 412 Kiera Stravenue
street_2: Suite 391
city: San Francisco
state: CA
zip: '94107'
country: USA
active: true
filing_address: false
mailing_address: false
created_at: '2023-09-12T16:42:25.000-07:00'
updated_at: '2023-09-12T16:42:25.000-07:00'
- version: 15e6b9680e00f3122729e64e3cef3224
company_uuid: 6bf7807c-a5a0-4f4d-b2e7-3fbb4b2299fb
phone_number: '2866070827'
uuid: fa94a2fd-11a8-4024-87ff-85c587d9d2b4
street_1: 644 Fay Vista
street_2: Suite 842
city: Richmond
state: VA
zip: '23218'
country: USA
active: true
filing_address: false
mailing_address: false
created_at: '2023-09-12T16:42:25.000-07:00'
updated_at: '2023-09-12T16:42:25.000-07:00'
Contractor-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/ContractorsGetCompanyContractorsResponse'
examples:
Example:
value:
- version: 63859768485e218ccf8a449bb60f14ed
uuid: c9fc1ad3-c107-4e7b-aa21-2dd4b00a7a07
company_uuid: b7457fec-3b76-43bb-9c6e-69cca4688942
wage_type: Fixed
is_active: false
type: Individual
first_name: Kory
last_name: Gottlieb
middle_initial: P
business_name: null
ein: null
has_ein: false
has_ssn: true
department: Backup Dancer
department_uuid: 1802465d-4f68-4865-920c-1307ab095f12
email: keira.west@mckenzie.org
start_date: '2022-01-01'
file_new_hire_report: false
work_state: null
onboarded: true
onboarding_status: contractor_onboarding_completed
address:
street_1: 621 Jast Row
street_2: Apt. 281
city: Coral Springs
state: FL
zip: '33065'
country: USA
hourly_rate: '0.00'
- version: 8aab307f1e8ed788697f8986346af559
uuid: 183a86f4-a803-4b38-9357-cd9b78e2560c
company_uuid: afdd5d98-581b-4fc0-b988-706b7d23b2a5
wage_type: Fixed
is_active: true
type: Business
first_name: null
last_name: null
middle_initial: null
business_name: Labadie-Stroman
ein: XX-XXX0001
has_ein: true
has_ssn: false
email: jonatan@kerluke.info
start_date: '2022-01-01'
onboarded: true
onboarding_status: contractor_onboarding_completed
address:
street_1: 1625 Bednar Center
street_2: Apt. 480
city: Port Charlotte
state: FL
zip: '33954'
country: USA
hourly_rate: '0.00'
file_new_hire_report: false
work_state: null
- version: b48c46abfed1487b873b442334b3c4ff
uuid: ea1c2d65-b622-4899-bcb7-5cd0fe0232aa
id: 7757515807623484
company_uuid: 281c763d-a2ba-4f51-b9e8-b1ed61576d62
company_id: 7757616923763477
wage_type: Fixed
is_active: true
type: Individual
first_name: Chanel
last_name: Boyle
middle_initial: X
business_name: null
ein: null
has_ein: false
has_ssn: true
email: loyal@hettinger.biz
file_new_hire_report: true
work_state: TX
onboarded: true
onboarding_status: contractor_onboarding_completed
address:
street_1: 35913 Darrick Run
street_2: Apt. 913
city: Cypress
state: TX
zip: '77433'
country: USA
hourly_rate: '0.00'
Contractor-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Contractor'
examples:
Individual Contractor:
value:
version: 63859768485e218ccf8a449bb60f14ed
uuid: c9fc1ad3-c107-4e7b-aa21-2dd4b00a7a07
company_uuid: b7457fec-3b76-43bb-9c6e-69cca4688942
wage_type: Hourly
start_date: '2022-01-01'
is_active: false
type: Individual
first_name: Kory
last_name: Gottlieb
middle_initial: P
business_name: null
ein: null
has_ein: false
has_ssn: true
department: Stage hand
department_uuid: 56260b3d-c375-415c-b77a-75d99f717193
email: keira.west@mckenzie.org
file_new_hire_report: true
work_state: FL
onboarded: true
onboarding_status: onboarding_completed
address:
street_1: 621 Jast Row
street_2: Apt. 281
city: Coral Springs
state: FL
zip: '33065'
country: USA
hourly_rate: '60.00'
Business Contractor:
value:
version: 8aab307f1e8ed788697f8986346af559
uuid: c7c0659c-21a6-4b4e-b74c-9252576fc68c
company_uuid: 0ec4ae6e-e436-460d-b63c-94a14503d16f
wage_type: Fixed
start_date: '2022-01-01'
is_active: true
type: Business
first_name: null
last_name: null
middle_initial: null
business_name: Labadie-Stroman
ein: XX-XXX0001
has_ein: true
has_ssn: false
email: jonatan@kerluke.info
file_new_hire_report: false
work_state: null
onboarded: false
onboarding_status: admin_onboarding_incomplete
address:
street_1: 1625 Bednar Center
street_2: Apt. 480
city: Port Charlotte
state: FL
zip: '33954'
country: USA
hourly_rate: '0.00'
Contractor-Onboarding-Status-Object:
description: Example response.
content:
application/json:
schema:
$ref: '#/components/schemas/Contractor-Onboarding-Status'
examples:
Example:
value:
uuid: bc57832c-d8bc-43a7-ae99-3a03380ff037
onboarding_status: admin_onboarding_incomplete
onboarding_steps:
- title: Basic details
id: basic_details
required: true
completed: false
requirements: []
- title: Enter compensation details
id: compensation_details
required: true
completed: false
requirements: []
- title: Add an address
id: add_address
required: true
completed: false
requirements: []
- title: Payment details
id: payment_details
required: true
completed: false
requirements: []
- title: Sign and acknowledge documents
id: sign_documents
required: false
completed: false
requirements:
- basic_details,
- add_address
- title: File new hire report
id: file_new_hire_report
required: false
completed: false
requirements:
- basic_details
application/xml:
schema:
$ref: '#/components/schemas/ContractorsGetOnboardingStatusResponse'
examples:
Example:
value:
uuid: bc57832c-d8bc-43a7-ae99-3a03380ff037
onboarding_status: admin_onboarding_incomplete
onboarding_steps:
- title: Basic details
id: basic_detailsX
required: true
completed: false
requirements: []
- title: Enter compensation details
id: compensation_detailsX
required: true
completed: false
requirements: []
- title: Add an address
id: add_addressX
required: true
completed: false
requirements: []
- title: Payment details
id: payment_detailsX
required: true
completed: false
requirements: []
- title: Sign and acknowledge documents
id: sign_documentsX
required: false
completed: false
requirements:
- basic_details,
- add_address
- title: File new hire report
id: file_new_hire_reportX
required: false
completed: false
requirements:
- basic_details
Contractor-Payment-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Contractor-Payment'
examples:
Example:
value:
uuid: 04552eb9-7829-4b18-ae96-6983552948df
contractor_uuid: bc57832c-d8bc-43a7-ae99-3a03380ff037
bonus: '20.0'
date: '2020-10-19'
hours: '40.0'
payment_method: Direct Deposit
reimbursement: '100.0'
status: Unfunded
hourly_rate: '18.0'
may_cancel: true
wage: '0.0'
wage_type: Hourly
wage_total: '740.00'
Contractor-Payment-Method-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Contractor-Payment-Method'
examples:
Example:
value:
version: 63859768485e218ccf8a449bb60f14ed
type: Direct Deposit
split_by: Percentage
splits:
- uuid: e88f9436-b74e-49a8-87e9-777b9bfe715e
name: BoA Checking Account
priority: 1
split_amount: 100
Compensation-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Compensation'
examples:
Exempt:
value:
version: 98jr3289h3298hr9329gf9egskt3kagri32qqgiqe3872
id: 1363316536327004
uuid: db57832c-d8bc-43a7-ae99-0a04480ff037
job_id: 1123581321345589
job_uuid: d8f8fbe7-496d-4b69-86f0-1e2d1b73a086
rate: '60000.00'
payment_unit: Year
flsa_status: Exempt
effective_date: '2020-12-11'
adjust_for_minimum_wage: false
minimum_wages: []
Minimum Wage Adjusted:
value:
version: cc59bd3879d655fb940a1f6b675f2ad9
id: 1363316536327003
uuid: a4d9ba9c-32cc-4cc1-a5bc-6ef4cd653e7a
job_id: 1123581321345589
job_uuid: d8f8fbe7-496d-4b69-86f0-1e2d1b73a086
rate: '5.00'
payment_unit: Hour
flsa_status: Nonexempt
effective_date: '2018-12-11'
adjust_for_minimum_wage: true
minimum_wages:
- uuid: edeea5af-ecd6-4b1c-b5de-5cff2d302738
wage: '7.25'
effective_date: '2018-12-11'
application/xml:
schema:
$ref: >-
#/components/schemas/JobsAndCompensationsCreateCompensationResponse
examples:
Exempt:
value:
version: 98jr3289h3298hr9329gf9egskt3kagri32qqgiqe3872
id: 1363316536327004
uuid: db57832c-d8bc-43a7-ae99-0a04480ff037
employee_uuid: be3c9d35-f17d-4431-8a90-a6537f17dfde
job_id: 1123581321345589
job_uuid: d8f8fbe7-496d-4b69-86f0-1e2d1b73a086
rate: '60000.00'
payment_unit: Year
flsa_status: Exempt
effective_date: '2020-12-11'
adjust_for_minimum_wage: false
minimum_wages: []
Minimum Wage Adjusted:
value:
version: cc59bd3879d655fb940a1f6b675f2ad9
id: 1363316536327003
uuid: a4d9ba9c-32cc-4cc1-a5bc-6ef4cd653e7a
employee_uuid: be3c9d35-f17d-4431-8a90-a6537f17dfd2
job_id: 1123581321345589
job_uuid: d8f8fbe7-496d-4b69-86f0-1e2d1b73a086
rate: '5.00'
payment_unit: Hour
flsa_status: Nonexempt
effective_date: '2018-12-11'
adjust_for_minimum_wage: true
minimum_wages:
- uuid: edeea5af-ecd6-4b1c-b5de-5cff2d302738
wage: '7.25'
effective_date: '2018-12-11'
Compensation-List:
description: Example response
content:
application/json:
schema:
$ref: >-
#/components/schemas/JobsAndCompensationsGetJobCompensationsResponse
examples:
Example:
value:
- version: 98jr3289h3298hr9329gf9egskt3kagri32qqgiqe3872
uuid: db57832c-d8bc-43a7-ae99-0a04480ff037
job_uuid: d8f8fbe7-496d-4b69-86f0-1e2d1b73a086
rate: '70.00'
payment_unit: Hour
flsa_status: Nonexempt
effective_date: '2020-12-11'
adjust_for_minimum_wage: false
minimum_wages: []
- version: cc59bd3879d655fb940a1f6b675f2ad9
id: 1363316536327003
job_id: 1123581321345589
uuid: a4d9ba9c-32cc-4cc1-a5bc-6ef4cd653e7a
job_uuid: d8f8fbe7-496d-4b69-86f0-1e2d1b73a086
payment_unit: Hour
flsa_status: Nonexempt
effective_date: '2018-12-11'
rate: '5.00'
adjust_for_minimum_wage: true
minimum_wages:
- uuid: edeea5af-ecd6-4b1c-b5de-5cff2d302738
wage: '7.25'
effective_date: '2018-12-11'
Garnishment-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Garnishment'
examples:
Example:
value:
description: Company loan to employee
version: 52b7c567242cb7452e89ba2bc02cb476
uuid: 96334c6c-4e01-40ac-ac1c-d2fb02a7e371
employee_uuid: 2d9c45f3-5ab9-4198-90a7-e8bea1ae3ce6
active: true
amount: '8.00'
court_ordered: false
times: 5
recurring: false
annual_maximum: null
pay_period_maximum: '100.00'
deduct_as_percentage: true
Garnishment-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/GarnishmentsGetEmployeeGarnishmentsResponse'
examples:
Example:
value:
- description: Child support
version: 63152767c822d6b0385509b973c49dda
uuid: 4c7841a2-1363-497e-bc0f-664703c7484f
employee_uuid: a6b53294-f871-4db2-bbd4-8c3d1fe56440
active: true
amount: '100.00'
court_ordered: true
times: null
recurring: true
annual_maximum: '400.00'
pay_period_maximum: null
deduct_as_percentage: false
- description: Company loan to employee
version: 52b7c567242cb7452e89ba2bc02cb476
uuid: 96334c6c-4e01-40ac-ac1c-d2fb02a7e371
employee_uuid: 2d9c45f3-5ab9-4198-90a7-e8bea1ae3ce6
active: true
amount: '8.00'
court_ordered: false
times: 5
recurring: false
annual_maximum: null
pay_period_maximum: '100.00'
deduct_as_percentage: true
Termination-Object:
description: Example Response
content:
application/json:
schema:
$ref: '#/components/schemas/Termination'
examples:
Example:
value:
version: d487dd0b55dfcacdd920ccbdaeafa351
uuid: da441196-43a9-4d23-ad5d-f37ce6bb99c0
employee_uuid: da441196-43a9-4d23-ad5d-f37ce6bb99c0
active: true
cancelable: true
effective_date: '2020-03-10'
run_termination_payroll: false
Termination-List:
description: Example response
content:
application/json:
schema:
$ref: >-
#/components/schemas/EmployeeEmploymentsListEmployeeTerminationsResponse
examples:
Example:
value:
- version: d487dd0b55dfcacdd920ccbdaeafa351
uuid: da441196-43a9-4d23-ad5d-f37ce6bb99c0
employee_uuid: da441196-43a9-4d23-ad5d-f37ce6bb99c0
active: true
cancelable: true
effective_date: '2020-03-10'
run_termination_payroll: false
Time-Off-Request-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Time-Off-Request'
examples:
Example:
value:
id: 1
status: approved
employee_note: Vacation at Disney World!
employer_note: But Universal has Harry Potter World...
days:
'2019-06-01': '4.000'
'2019-06-02': '8.000'
'2019-06-03': '2.000'
request_type: vacation
employee:
id: '234567'
full_name: Jessica Gusto
approver:
id: '345678'
full_name: Karen Gusto
initiator:
id: 234567X
full_name: Jessica Gusto
Time-Off-Request-List:
description: Example response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Time-Off-Request'
examples:
Example:
value:
- id: 1
status: approved
employee_note: Vacation at Disney World!
employer_note: But Universal has Harry Potter World...
days:
'2019-06-01': '4.000'
'2019-06-02': '8.000'
'2019-06-03': '2.000'
request_type: vacation
employee:
id: 234567X
full_name: Jessica Gusto
approver:
id: 345678X
full_name: Karen Gusto
initiator:
id: 234567X
full_name: Jessica Gusto
- id: 2
status: pending
employee_note: Coming down with the flu
employer_note: ''
days:
'2019-02-01': '8.000'
request_type: sick
employee:
id: '654321'
full_name: James Gusto
approver: null
initiator:
id: 654321X
full_name: James Gusto
Pay-Period-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/PaySchedulesGetPayPeriodsResponse'
examples:
Example:
value:
- start_date: '2020-01-11'
end_date: '2020-01-24'
pay_schedule_uuid: 00ebc4a4-ec88-4435-8f45-c505bb63e501
payroll:
payroll_uuid: bfd8aad4-9c3f-4ca3-b072-a1b2b3ea689f
check_date: '2020-01-30'
processed: true
payroll_deadline: '2020-01-28'
payroll_type: regular
- start_date: '2020-12-12'
end_date: '2020-12-25'
pay_schedule_uuid: cb53db72-612f-4eb1-9b85-389e79cfa510
payroll:
payroll_uuid: 7ed29b45-4bb1-4d38-bd94-4d607d49fd21
check_date: '2020-12-30'
processed: true
payroll_deadline: '2020-12-28'
payroll_type: regular
Pay-Schedule-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Pay-Schedule'
examples:
Example:
value:
uuid: f2a69c38-e2f9-4e31-b5c5-4754fc60a052
frequency: Twice per month
anchor_pay_date: '2020-05-15'
anchor_end_of_pay_period: '2020-05-08'
day_1: 15
day_2: 31
name: Engineering
custom_name: A new monthly pay schedule
auto_pilot: false
active: true
Pay-Schedule-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/PaySchedulesListForCompanyResponse'
examples:
Example:
value:
- uuid: 2097fe08-407a-46d7-b35c-a32402a2355e
frequency: Twice per month
anchor_pay_date: '2020-05-15'
anchor_end_of_pay_period: '2020-05-08'
day_1: 15
day_2: 31
name: Engineering
custom_name: Engineering department pay schedule
auto_pilot: false
active: true
- uuid: 8fc9f556-74fa-4271-97f6-4bfbfc5a5352
frequency: Monthly
anchor_pay_date: '2020-05-31'
day_1: 31
day_2: null
name: Sales
custom_name: Sales department monthly schedule
auto_pilot: false
active: false
- uuid: 0e07d35a-af11-4123-bfcb-4dd5f2f12ee1
frequency: Monthly
anchor_pay_date: '2020-05-31'
day_1: 31
day_2: null
name: Staff
custom_name: Staff department pay schedule
auto_pilot: true
active: false
Benefit-Type-Requirements-Object:
description: Benefit type requirements response
content:
application/json:
schema:
$ref: '#/components/schemas/Benefit-Type-Requirements'
examples:
Example:
value:
employee_deduction:
required: true
editable: true
default_value: null
choices: null
contribution:
required: true
editable: true
default_value:
type: percentage
value: 2
choices:
- percentage
deduct_as_percentage:
required: true
editable: true
default_value: null
choices: null
catch_up:
required: true
editable: true
default_value: null
choices: null
limit_option:
required: false
editable: false
default_value: null
choices: null
company_contribution_annual_maximum:
required: false
editable: false
default_value: null
choices: null
coverage_salary_multiplier:
required: false
editable: false
default_value: null
choices: null
coverage_amount:
required: false
editable: false
default_value: null
choices: null
Supported-Benefit-Object:
description: Supported benefit response
content:
application/json:
schema:
$ref: '#/components/schemas/Supported-Benefit'
examples:
Example:
value:
description: Deductions and contributions for Medical Insurance
benefit_type: 1
name: Medical Insurance
pretax: true
posttax: false
imputed: false
healthcare: true
retirement: false
yearly_limit: false
Supported-Benefit-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyBenefitsListSupportedBenefitsResponse'
examples:
Supported Benefits:
value:
- description: Deductions and contributions for Medical Insurance
benefit_type: 1
name: Medical Insurance
pretax: true
posttax: false
imputed: false
healthcare: true
retirement: false
yearly_limit: false
category: Health
- description: Deductions and contributions for Dental Insurance
benefit_type: 2
name: Dental Insurance
pretax: true
posttax: false
imputed: false
healthcare: true
retirement: false
yearly_limit: false
category: Health
- description: Deductions and contributions for Vision Insurance
benefit_type: 3
name: Vision Insurance
pretax: true
posttax: false
imputed: false
healthcare: true
retirement: false
yearly_limit: false
category: Health
- description: >-
Health Savings Accounts (HSA) allow employees to be
reimbursed for qualified medical expenses. Contributions are
pre-tax and lower the total amount of tax paid by employees
and the employer. Employers may also make tax-free
contributions to employees' HSA. Remaining balances are
carried over in next year.
benefit_type: 6
name: Health Savings Account
pretax: true
posttax: false
imputed: false
healthcare: false
retirement: false
yearly_limit: true
category: Health
- description: >-
Flexible Spending Accounts (FSA) allow employees to be
reimbursed for qualified medical expenses. Contributions are
pre-tax and lower the total amount of tax paid by employees
and the employer. Employers may also make tax-free
contributions to employees' FSA. Remaining balances are not
carried over in next year.
benefit_type: 7
name: Health FSA
pretax: true
posttax: false
imputed: false
healthcare: false
retirement: false
yearly_limit: true
category: Health
- description: >-
Dependent Care FSA reimburses employees for expenses to care
for dependents while the employee is at work (e.g.
Daycares). Contributions are pre-tax and lower the total
amount of tax paid by employees and the employer. Employers
may also make tax-free contributions to employee FSA.
Remaining balances are not carried over to the next year.
Single parents or Married couples filing a joint return can
elect up to $5000 per year. Married couples filing separate
returns are limited to $2500 elections each.
benefit_type: 11
name: Dependent Care FSA
pretax: true
posttax: false
imputed: false
healthcare: false
retirement: false
yearly_limit: true
category: Health
- description: >-
The SIMPLE IRA is a tax-deferred retirement savings plan for
employees. It is often used by small businesses as an
alternative to 401(k) due to its relatively low operating
cost. Employers are required to contribute a specific
percentage to an employee's SIMPLE IRA.
benefit_type: 8
name: SIMPLE IRA
pretax: true
posttax: false
imputed: false
healthcare: false
retirement: true
yearly_limit: true
category: Savings and Retirement
- description: >-
Roth 401(k) is an after-tax savings plan for employees. The
standard maximum is $18,000, or $24,000 for employees over
50 years old.
benefit_type: 105
name: Roth 401(k)
pretax: false
posttax: true
imputed: false
healthcare: false
retirement: true
yearly_limit: true
category: Savings and Retirement
- description: >-
Roth 403(b) is an after-tax savings plan for certain
clerics, employees of public schools, and employees of other
types of tax-exempt organizations. Contributions made by
employees are taxable for federal and state withholding.
Often, employers contribute additional pre-tax dollars to
the employee’s Roth account to encourage saving for
retirement.
benefit_type: 110
name: Roth 403(b)
pretax: false
posttax: true
imputed: false
healthcare: false
retirement: true
yearly_limit: true
category: Savings and Retirement
- description: >-
401(k) is tax-deferred retirement savings plan for
employees. The standard maximum is $18,000, or $24,000 for
employees over 50 years old.
benefit_type: 5
name: 401(k)
pretax: true
posttax: false
imputed: false
healthcare: false
retirement: true
yearly_limit: true
category: Savings and Retirement
- description: >-
403(b) is tax-deferred retirement savings plan for certain
clerics, employees of public schools, and employees of other
types of tax-exempt organizations.
benefit_type: 9
name: 403(b)
pretax: true
posttax: false
imputed: false
healthcare: false
retirement: true
yearly_limit: true
category: Savings and Retirement
- description: >-
A SEP-IRA is a pre-tax retirement savings plan where only
the employer contributes. It is often used by small
businesses as an alternative to 401(k) due to its relatively
low operating cost. Employers are required to contribute the
same percentage to all enrolled employees, with a maximum
contribution of 25% of the employee’s compensation.
benefit_type: 108
name: SEP-IRA
pretax: true
posttax: false
imputed: false
healthcare: false
retirement: true
yearly_limit: true
category: Savings and Retirement
- description: >-
A SARSEP is a pre-tax retirement savings plan used by small
businesses as an alternative to 401(k) due to its relatively
low operating cost. While new SARSEP plans are not
available, there are still some companies that are
grandfathered into the plan. Employers are required to
contribute the same percentage to all enrolled employees,
with a maximum contribution of 25% of the employee’s
compensation.
benefit_type: 109
name: SARSEP
pretax: true
posttax: false
imputed: false
healthcare: false
retirement: true
yearly_limit: true
category: Savings and Retirement
- description: >-
Group-Term Life Insurance for coverage in excess of $50,000
per employee is a taxable fringe benefit. See IRS
Publication 15-B to determine the dollar value of the excess
coverage.
benefit_type: 107
name: Group-Term Life Insurance
pretax: false
posttax: true
imputed: true
healthcare: false
retirement: false
yearly_limit: false
category: Health
- description: >-
Tax-free commuter benefits for transit, vanpooling,
bicycling, and work-related parking costs. The annual
maximum contribution for this pre-tax benefit is in the IRS
publication 15-B.
benefit_type: 10
name: Commuter Benefits (pre-tax)
pretax: true
posttax: false
imputed: false
healthcare: false
retirement: false
yearly_limit: false
category: Transportation
- description: >-
When an employee uses a company-owned car for personal
matters, it is considered taxable benefit provided in-kind.
benefit_type: 106
name: Personal Use of Company Car
pretax: false
posttax: true
imputed: true
healthcare: false
retirement: false
yearly_limit: false
category: Transportation
- description: >-
529 College Savings is an after-tax savings plan for
employees designed to encourage saving for future college
costs. This benefit should be reported as a taxable benefit
and will therefore be taxed.
benefit_type: 111
name: 529 College Savings
pretax: false
posttax: true
imputed: true
healthcare: false
retirement: false
yearly_limit: false
category: Other
- description: >-
Student Loan Repayment is an after-tax savings plan for
employees to pay towards their outstanding student loans. An
employee can choose to set aside after-tax dollars towards
this benefit. These benefits should be reported as a taxable
benefit and will therefore be taxed.
benefit_type: 112
name: Student Loan Repayment
pretax: false
posttax: true
imputed: true
healthcare: false
retirement: false
yearly_limit: false
category: Other
- description: >-
Third Party Disability or Third Party Leave are policies
offered by employers that pay an employee for a specific
life event (maternity leave, injury). All payments made to
employees come from a third-party, such as an insurer. For
more information on the taxation of these plans, please
refer to publication 15-A for more details.
benefit_type: 998
name: Short Term Disability (post-tax)
pretax: false
posttax: true
imputed: false
healthcare: false
retirement: false
yearly_limit: false
category: Health
- description: >-
Third Party Disability or Third Party Leave are policies
offered by employers that pay an employee for a specific
life event (maternity leave, injury). All payments made to
employees come from a third-party, such as an insurer. For
more information on the taxation of these plans, please
refer to publication 15-A for more details.
benefit_type: 999
name: Long Term Disability (post-tax)
pretax: false
posttax: true
imputed: false
healthcare: false
retirement: false
yearly_limit: false
category: Health
- description: >-
Third Party Disability or Third Party Leave are policies
offered by employers that pay an employee for a specific
life event (maternity leave, injury). All payments made to
employees come from a third-party, such as an insurer. For
more information on the taxation of these plans, please
refer to publication 15-A for more details.
benefit_type: 996
name: Short Term Disability (pre-tax)
pretax: true
posttax: false
imputed: false
healthcare: false
retirement: false
yearly_limit: false
category: Health
- description: >-
Third Party Disability or Third Party Leave are policies
offered by employers that pay an employee for a specific
life event (maternity leave, injury). All payments made to
employees come from a third-party, such as an insurer. For
more information on the taxation of these plans, please
refer to publication 15-A for more details.
benefit_type: 997
name: Long Term Disability (pre-tax)
pretax: true
posttax: false
imputed: false
healthcare: false
retirement: false
yearly_limit: false
category: Health
- description: >-
Third Party Disability or Third Party Leave are policies
offered by employers that pay an employee for a specific
life event (maternity leave, injury). All payments made to
employees come from a third-party, such as an insurer. For
more information on the taxation of these plans, please
refer to publication 15-A for more details.
benefit_type: 991
name: Voluntary Short Term Disability (post-tax)
pretax: false
posttax: true
imputed: false
healthcare: false
retirement: false
yearly_limit: false
category: Health
- description: >-
Third Party Disability or Third Party Leave are policies
offered by employers that pay an employee for a specific
life event (maternity leave, injury). All payments made to
employees come from a third-party, such as an insurer. For
more information on the taxation of these plans, please
refer to publication 15-A for more details.
benefit_type: 992
name: Voluntary Long Term Disability (post-tax)
pretax: false
posttax: true
imputed: false
healthcare: false
retirement: false
yearly_limit: false
category: Health
- description: >-
Third Party Disability or Third Party Leave are policies
offered by employers that pay an employee for a specific
life event (maternity leave, injury). All payments made to
employees come from a third-party, such as an insurer. For
more information on the taxation of these plans, please
refer to publication 15-A for more details.
benefit_type: 993
name: Voluntary Life (post-tax)
pretax: false
posttax: true
imputed: false
healthcare: false
retirement: false
yearly_limit: false
category: Health
- description: >-
Tax-free commuter benefits allow employees to reduce their
monthly commuting expenses for transit, carpooling,
bicycling, and work-related parking costs. Please note that
there is an annual maximum for this pre-tax benefit. The
maximum dollar amount is found in IRS Publication 15-B.
benefit_type: 113
name: Commuter Parking
pretax: true
posttax: false
imputed: false
healthcare: false
retirement: false
yearly_limit: false
category: Transportation
- description: >-
Tax-free commuter benefits allow employees to reduce their
monthly commuting expenses for transit, carpooling,
bicycling, and work-related parking costs. Please note that
there is an annual maximum for this pre-tax benefit. The
maximum dollar amount is found in IRS Publication 15-B.
benefit_type: 114
name: Commuter Transit
pretax: true
posttax: false
imputed: false
healthcare: false
retirement: false
yearly_limit: false
category: Transportation
- description: Other taxable benefit
benefit_type: 100
name: Other (taxable)
pretax: false
posttax: true
imputed: true
healthcare: false
retirement: false
yearly_limit: false
category: Other
- description: >-
Employer-sponsored benefits like this are called fringe
benefits, and they don’t get special tax treatment—they’ll
be reported as taxable wages on your employees’ paystubs.
benefit_type: 201
name: Cell Phone (taxable)
pretax: false
posttax: true
imputed: true
healthcare: false
retirement: false
yearly_limit: false
category: Transportation
- description: >-
Employer-sponsored benefits like this are called fringe
benefits, and they don’t get special tax treatment—they’ll
be reported as taxable wages on your employees’ paystubs.
benefit_type: 202
name: Gym & Fitness (taxable)
pretax: false
posttax: true
imputed: true
healthcare: false
retirement: false
yearly_limit: false
category: Transportation
- description: >-
Employer-sponsored benefits like this are called fringe
benefits, and they don’t get special tax treatment—they’ll
be reported as taxable wages on your employees’ paystubs.
benefit_type: 203
name: Housing (taxable)
pretax: false
posttax: true
imputed: true
healthcare: false
retirement: false
yearly_limit: false
category: Transportation
- description: >-
Employer-sponsored benefits like this are called fringe
benefits, and they don’t get special tax treatment—they’ll
be reported as taxable wages on your employees’ paystubs.
benefit_type: 204
name: Wellness (taxable)
pretax: false
posttax: true
imputed: true
healthcare: false
retirement: false
yearly_limit: false
category: Transportation
Admin-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Admin'
examples:
Example:
value:
first_name: John
last_name: Smith
email: jsmith99@gmail.com
uuid: 5de11791-98fd-4587-9ed0-d5d804b8e647
Admin-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/CompaniesGetAllAdminsResponse'
examples:
Example:
value:
- first_name: Katherine
last_name: Johnson
email: Katherine@acmecorp.com
uuid: 987058cc-23ee-46e9-81ef-5cee086cceca
- first_name: Anita
last_name: Borg
email: Anita@acmecorp.com
uuid: 5de11791-98fd-4587-9ed0-d5d804b8e647
Company-Benefit-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Company-Benefit'
examples:
Example:
value:
description: Kaiser Permanente
version: 98jr3289h3298hr9329gf9egskt3kagri32qqgiqe3872
uuid: d2cec746-caee-464a-bcaf-00d93f7049c9
company_uuid: 881ce3f2-e3e1-49c9-8ad4-0bcf515f5618
benefit_type: 1
active: true
deletable: true
supports_percentage_amounts: true
responsible_for_employer_taxes: false
responsible_for_employee_w2: false
Company-Benefit-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyBenefitsGetBenefitsForCompanyResponse'
examples:
Example:
description: OK
value:
- description: Kaiser Permanente
version: 98jr3289h3298hr9329gf9egskt3kagri32qqgiqe3872
uuid: d2cec746-caee-464a-bcaf-00d93f7049c9
company_uuid: 528cc543-8a41-497e-b479-23a4c5ec77ac
benefit_type: 1
active: true
deletable: true
supports_percentage_amounts: true
responsible_for_employer_taxes: false
responsible_for_employee_w2: false
Company-Custom-Field-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/CompaniesGetCustomFieldsResponse'
examples:
Example:
value:
custom_fields:
- description: Employee Level
uuid: ea7e5d57-6abb-47d7-b654-347c142886c0
name: employee_level
type: text
selection_options: null
- description: What is your t-shirt size?
uuid: 299650e4-e970-4acf-9bf0-6f05585d20ba
name: t-shirt size
type: text
selection_options: null
- description: Which is your favorite fruit?
uuid: 024ec137-6c92-43a3-b061-14a9720531d6
name: favorite fruit
type: radio
selection_options:
- apple
- banana
- orange
Earning-Type-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/EarningTypesGetAllResponse'
examples:
Example:
value:
default:
- name: Bonus
uuid: b82e35c5-d7c6-4705-9e16-9f87499ade18
- name: Cash Tips
uuid: f5618c94-ed7d-4366-b2c4-ff05e430064f
- name: Commission
uuid: 60191999-004a-49d9-b163-630574433653
- name: Correction Payment
uuid: 368226e0-8e8c-48f0-bc91-aee46caafbc9
- name: Minimum Wage Adjustment
uuid: 88a2e519-9ff5-4c19-9071-6a709f3c2939
- name: Paycheck Tips
uuid: a3eaf03d-e712-4144-8f9b-71a85528adcf
- name: Severance
uuid: a6a2eba7-6c7d-4ced-bbe8-43452fbc9f63
custom:
- name: Gym Membership Stipend
uuid: 6b4a8efb-db90-4c13-a75f-aae11b3f4ff9
Earning-Type-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Earning-Type'
examples:
Example:
value:
name: Gym Membership Stipend
uuid: f4dc8972-8830-4c07-b623-349a04b040d7
Employee-Benefit-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Employee-Benefit'
examples:
Example:
value:
version: 09j3d29jqdpj92109j9j2d90dq
employee_uuid: 908123091820398
company_benefit_uuid: 54e37c27-43e6-4ae5-a5b2-e29895a133be
active: true
uuid: e91ca856-a915-4339-9b18-29f9cd66b031
employee_deduction: '100.00'
employee_deduction_annual_maximum: '200.00'
company_contribution_annual_maximum: '200.00'
limit_option: null
deduct_as_percentage: false
catch_up: false
coverage_amount: null
deduction_reduces_taxable_income: null
coverage_salary_multiplier: '0.00'
contribution:
type: amount
value: '100.00'
Tiered example:
value:
version: string
employee_uuid: 8f9f3f68-8fd3-499d-ade7-4a052e56494e
company_benefit_uuid: 54e37c27-43e6-4ae5-a5b2-e29895a133be
active: true
uuid: e91ca856-a915-4339-9b18-29f9cd66b031
employee_deduction: '0.00'
deduct_as_percentage: false
employee_deduction_annual_maximum: string
contribution:
type: tiered
value:
tiers:
- rate: '5.0'
threshold: '2.0'
threshold_delta: '2.0'
- rate: '3.0'
threshold: '5.0'
threshold_delta: '3.0'
elective: false
company_contribution_annual_maximum: string
limit_option: string
catch_up: false
coverage_amount: string
deduction_reduces_taxable_income: unset
coverage_salary_multiplier: '0.00'
Employee-Benefit-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeBenefitsGetAllForEmployeeResponse'
examples:
Example:
value:
- version: 09j3d29jqdpj92109j9j2d90dq
employee_uuid: 8f9f3f68-8fd3-499d-ade7-4a052e56494e
company_benefit_uuid: 54e37c27-43e6-4ae5-a5b2-e29895a133be
active: true
uuid: e91ca856-a915-4339-9b18-29f9cd66b031
employee_deduction: '100.00'
company_contribution: '100.00'
employee_deduction_annual_maximum: '200.00'
company_contribution_annual_maximum: '200.00'
limit_option: null
deduct_as_percentage: false
contribute_as_percentage: false
catch_up: false
coverage_amount: null
deduction_reduces_taxable_income: null
coverage_salary_multiplier: '0.00'
Payroll-Update-Object:
description: A prepared payroll
content:
application/json:
schema:
$ref: '#/components/schemas/Payroll-Prepared'
examples:
Example:
value:
payroll_deadline: '2022-02-18T22:00:00Z'
check_date: '2021-02-22'
off_cycle: false
external: false
processed: false
processed_date: null
calculated_at: null
payroll_uuid: b50e611d-8f3d-4f24-b001-46675f7b5777
company_uuid: 6bf7807c-a5a0-4f4d-b2e7-3fbb4b2299fb
created_at: '2022-02-01T22:00:00Z'
pay_period:
start_date: '2021-02-01'
end_date: '2021-02-15'
pay_schedule_uuid: 00ebc4a4-ec88-4435-8f45-c505bb63e501
payroll_status_meta:
cancellable: false
expected_check_date: '2022-02-22'
initial_check_date: '2022-02-22'
expected_debit_time: '2022-02-18T22:00:00Z'
payroll_late: false
initial_debit_cutoff_time: '2022-02-18T22:00:00Z'
employee_compensations:
- version: 4ba36d23a78c7393b4900ef38019d8ff
employee_uuid: 187412e1-3dbe-491a-bb2f-2f40323a7067
excluded: false
payment_method: Direct Deposit
fixed_compensations:
- name: Bonus
amount: '100.00'
job_uuid: 94e0d15e-9ed2-4077-98f6-64554f242ba5
- name: Reimbursement
amount: '100.00'
job_uuid: 91bc3b43-ded0-4ee7-98fe-215499e909ba
hourly_compensations:
- name: Regular Hours
hours: '40.000'
job_uuid: bd378298-3e0c-4145-904a-baadf8a91fa3
compensation_multiplier: 1
flsa_status: Nonexempt
- name: Overtime
hours: '15.000'
job_uuid: 9d3760f0-d1f9-4700-8817-0fe2dce5cf23
compensation_multiplier: 1.5
flsa_status: Nonexempt
- name: Double overtime
hours: '0.000'
job_uuid: b5eef9a9-4a87-4649-a80d-14878c05f44e
compensation_multiplier: 2
flsa_status: Nonexempt
- name: Regular Hours
hours: '40.000'
job_uuid: 332bd171-9efc-432b-abbb-a75c9dba706a
compensation_multiplier: 1
flsa_status: Nonexempt
- name: Overtime
hours: '5.000'
job_uuid: ca9b3dc1-57ac-4736-901a-9b1c9634b9d5
compensation_multiplier: 1.5
flsa_status: Nonexempt
- name: Double overtime
hours: '0.000'
job_uuid: 1bad01e2-140c-49ed-9542-2388ce4a19b3
compensation_multiplier: 2
flsa_status: Nonexempt
paid_time_off:
- name: Vacation Hours
hours: '20.000'
- name: Sick Hours
hours: '0.000'
- name: Holiday Hours
hours: '0.000'
- version: ff083257a5583291fb86656ad0df1b42
employee_uuid: 187412e1-3dbe-491a-bb2f-2f40323a7012
excluded: false
payment_method: Direct Deposit
fixed_compensations:
- name: Bonus
amount: '100.00'
job_uuid: 94e0d15e-9ed2-4077-98f6-64554f242b34
- name: Reimbursement
amount: '100.00'
job_uuid: 91bc3b43-ded0-4ee7-98fe-215499e90955
hourly_compensations:
- name: Regular Hours
hours: '40.000'
job_uuid: bd378298-3e0c-4145-904a-baadf8a91fa3
compensation_multiplier: 1
flsa_status: Commission Only Exempt
paid_time_off:
- name: Vacation Hours
hours: '20.000'
- name: Sick Hours
hours: '0.000'
- name: Holiday Hours
hours: '0.000'
- version: 259816479e3729bf855318af9b9adddf
employee_uuid: 187412e1-3dbe-491a-bb2f-2f40323a7781
excluded: false
payment_method: Direct Deposit
fixed_compensations:
- name: Bonus
amount: '100.00'
job_uuid: 94e0d15e-9ed2-4077-98f6-64554f242bab
- name: Reimbursement
amount: '100.00'
job_uuid: 91bc3b43-ded0-4ee7-98fe-215499e909cd
hourly_compensations:
- name: Regular Hours
hours: '40.000'
job_uuid: bd378298-3e0c-4145-904a-baadf8a91fa3
compensation_multiplier: 1
flsa_status: Exempt
paid_time_off:
- name: Vacation Hours
hours: '20.000'
- name: Sick Hours
hours: '0.000'
- name: Holiday Hours
hours: '0.000'
fixed_compensation_types:
- name: Bonus
- name: Commission
- name: Paycheck Tips
- name: Cash Tips
- name: Correction Payment
- name: Anniversary Bonus
- name: Internet Stipend
- name: Reimbursement
Payroll-Show-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Payroll'
examples:
Unprocessed:
value:
payroll_deadline: '2021-02-18T22:00:00Z'
check_date: '2021-02-22'
off_cycle: false
external: false
processed: false
processed_date: null
calculated_at: null
payroll_uuid: b50e611d-8f3d-4f24-b001-46675f7b5777
company_uuid: 6bf7807c-a5a0-4f4d-b2e7-3fbb4b2299fb
created_at: '2022-02-01T22:00:00Z'
pay_period:
start_date: '2021-02-01'
end_date: '2021-02-15'
pay_schedule_uuid: 00ebc4a4-ec88-4435-8f45-c505bb63e501
payroll_status_meta:
cancellable: false
expected_check_date: '2021-02-22'
initial_check_date: '2021-02-22'
expected_debit_time: '2021-02-18T22:00:00Z'
payroll_late: false
initial_debit_cutoff_time: '2021-02-18T22:00:00Z'
Processed:
value:
payroll_deadline: '2021-02-18T22:00:00Z'
check_date: '2021-02-22'
off_cycle: false
external: false
processed: true
processed_date: '2021-02-18'
calculated_at: '2021-02-18T12:00:00Z'
payroll_uuid: b50e611d-8f3d-4f24-b001-46675f7b5777
company_uuid: 6bf7807c-a5a0-4f4d-b2e7-3fbb4b2299fb
created_at: '2022-02-01T22:00:00Z'
pay_period:
start_date: '2021-02-01'
end_date: '2021-02-15'
pay_schedule_uuid: 00ebc4a4-ec88-4435-8f45-c505bb63e501
totals:
company_debit: '121747.71'
net_pay_debit: '79283.80'
tax_debit: '42463.91'
reimbursement_debit: '0.00'
child_support_debit: '0.00'
reimbursements: '0.00'
net_pay: '81752.94'
gross_pay: '130635.89'
employee_bonuses: '0.00'
employee_commissions: '18536.37'
employee_cash_tips: '0.00'
employee_paycheck_tips: '0.00'
additional_earnings: '0.00'
owners_draw: '0.00'
check_amount: '2469.14'
employer_taxes: '6917.19'
employee_taxes: '35546.72'
benefits: '0.00'
employee_benefits_deductions: '13336.23'
deferred_payroll_taxes: '0.00'
other_deductions: '240.00'
company_taxes:
- name: MO Compensation Deduction
amount: '-0.92'
employer: true
- name: NY MCTMT
amount: '5.00'
employer: true
payroll_status_meta:
cancellable: false
expected_check_date: '2021-02-22'
initial_check_date: '2021-02-22'
expected_debit_time: '2021-02-18T22:00:00Z'
payroll_late: false
initial_debit_cutoff_time: '2021-02-18T22:00:00Z'
employee_compensations:
- employee_uuid: 187412e1-3dbe-491a-bb2f-2f40323a7067
excluded: false
gross_pay: '2791.25'
net_pay: '1953.31'
check_amount: '1953.31'
payment_method: Direct Deposit
fixed_compensations:
- name: Bonus
amount: '100.00'
job_uuid: 94e0d15e-9ed2-4077-98f6-64554f242ba5
- name: Reimbursement
amount: '100.00'
job_uuid: 91bc3b43-ded0-4ee7-98fe-215499e909ba
hourly_compensations:
- name: Regular Hours
hours: '40.000'
job_uuid: bd378298-3e0c-4145-904a-baadf8a91fa3
compensation_multiplier: 1
flsa_status: Nonexempt
- name: Overtime
hours: '15.000'
job_uuid: 9d3760f0-d1f9-4700-8817-0fe2dce5cf23
compensation_multiplier: 1.5
flsa_status: Nonexempt
- name: Double overtime
hours: '0.000'
job_uuid: b5eef9a9-4a87-4649-a80d-14878c05f44e
compensation_multiplier: 2
flsa_status: Nonexempt
- name: Regular Hours
hours: '40.000'
job_uuid: 332bd171-9efc-432b-abbb-a75c9dba706a
compensation_multiplier: 1
flsa_status: Nonexempt
- name: Overtime
hours: '5.000'
job_uuid: ca9b3dc1-57ac-4736-901a-9b1c9634b9d5
compensation_multiplier: 1.5
flsa_status: Nonexempt
- name: Double overtime
hours: '0.000'
job_uuid: 1bad01e2-140c-49ed-9542-2388ce4a19b3
compensation_multiplier: 2
flsa_status: Nonexempt
paid_time_off:
- name: Vacation Hours
hours: '20.000'
- name: Sick Hours
hours: '0.000'
- name: Holiday Hours
hours: '0.000'
benefits:
- name: Group Term Life
employee_deduction: '100.00'
company_contribution: '50.00'
imputed: true
- name: 401K
employee_deduction: '100.00'
company_contribution: '50.00'
imputed: false
deductions:
- name: Child Support
amount: '80.00'
taxes:
- name: Federal Income Tax
employer: false
amount: '646.69'
- name: Social Security
employer: true
amount: '191.25'
- employee_uuid: 187412e1-3dbe-491a-bb2f-2f40323a7012
excluded: false
gross_pay: '2791.25'
net_pay: '1953.31'
check_amount: '1953.31'
payment_method: Direct Deposit
fixed_compensations:
- name: Bonus
amount: '100.00'
job_uuid: 94e0d15e-9ed2-4077-98f6-64554f242b34
- name: Reimbursement
amount: '100.00'
job_uuid: 91bc3b43-ded0-4ee7-98fe-215499e90955
hourly_compensations:
- name: Regular Hours
hours: '40.000'
job_uuid: bd378298-3e0c-4145-904a-baadf8a91fa3
compensation_multiplier: 1
flsa_status: Commission Only Exempt
paid_time_off:
- name: Vacation Hours
hours: '20.000'
- name: Sick Hours
hours: '0.000'
- name: Holiday Hours
hours: '0.000'
benefits:
- name: Group Term Life
employee_deduction: '100.00'
company_contribution: '50.00'
imputed: true
- name: 401K
employee_deduction: '100.00'
company_contribution: '50.00'
imputed: false
deductions:
- name: Child Support
amount: '80.00'
taxes:
- name: Federal Income Tax
employer: false
amount: '646.69'
- name: Social Security
employer: true
amount: '191.25'
- employee_uuid: 187412e1-3dbe-491a-bb2f-2f40323a7781
excluded: false
gross_pay: '2791.25'
net_pay: '1953.31'
check_amount: '1953.31'
payment_method: Direct Deposit
fixed_compensations:
- name: Bonus
amount: '100.00'
job_uuid: 94e0d15e-9ed2-4077-98f6-64554f242bab
- name: Reimbursement
amount: '100.00'
job_uuid: 91bc3b43-ded0-4ee7-98fe-215499e909cd
hourly_compensations:
- name: Regular Hours
hours: '40.000'
job_uuid: bd378298-3e0c-4145-904a-baadf8a91fa3
compensation_multiplier: 1
flsa_status: Exempt
paid_time_off:
- name: Vacation Hours
hours: '20.000'
- name: Sick Hours
hours: '0.000'
- name: Holiday Hours
hours: '0.000'
benefits:
- name: Group Term Life
employee_deduction: '100.00'
company_contribution: '50.00'
imputed: true
- name: 401K
employee_deduction: '100.00'
company_contribution: '50.00'
imputed: false
deductions:
- name: Child Support
amount: '80.00'
taxes:
- name: Federal Income Tax
employer: false
amount: '646.69'
- name: Social Security
employer: true
amount: '191.25'
Payroll-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/PayrollsGetCompanyPayrollsResponse'
examples:
Example:
value:
- payroll_deadline: '2021-02-18T22:00:00Z'
check_date: '2021-02-22'
off_cycle: false
external: false
processed: true
processed_date: '2021-02-18'
calculated_at: '2021-02-18T12:00:00Z'
payroll_uuid: b50e611d-8f3d-4f24-b001-46675f7b5777
company_uuid: 6bf7807c-a5a0-4f4d-b2e7-3fbb4b2299fb
created_at: '2021-02-01T22:00:00Z'
pay_period:
start_date: '2021-02-01'
end_date: '2021-02-15'
pay_schedule_uuid: 00ebc4a4-ec88-4435-8f45-c505bb63e501
totals:
company_debit: '121747.71'
net_pay_debit: '79283.80'
tax_debit: '42463.91'
reimbursement_debit: '0.00'
child_support_debit: '0.00'
reimbursements: '0.00'
net_pay: '81752.94'
gross_pay: '130635.89'
employee_bonuses: '0.00'
employee_commissions: '18536.37'
employee_cash_tips: '0.00'
employee_paycheck_tips: '0.00'
additional_earnings: '0.00'
owners_draw: '0.00'
check_amount: '2469.14'
employer_taxes: '6917.19'
employee_taxes: '35546.72'
benefits: '0.00'
employee_benefits_deductions: '13336.23'
deferred_payroll_taxes: '0.00'
other_deductions: '240.00'
- payroll_deadline: '2021-02-28'
check_date: '2021-03-01'
off_cycle: false
external: false
processed: false
processed_date: nil
calculated_at: nil
payroll_uuid: b50e611d-8f3d-4f24-b001-46675f7b5777
company_uuid: 6bf7807c-a5a0-4f4d-b2e7-3fbb4b2299fb
created_at: '2022-02-01T22:00:00Z'
pay_period:
start_date: '2021-02-16'
end_date: '2021-03-01'
pay_schedule_uuid: 00ebc4a4-ec88-4435-8f45-c505bb63e501
Payment-Configs-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Payment-Configs'
examples:
Example:
value:
company_uuid: 423dd616-6dbc-4724-938a-403f6217a933
partner_uuid: 556f05d0-48e0-4c47-bce5-db9aea923043
fast_payment_limit: '5000'
payment_speed: 2-day
Company-Bank-Account-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Company-Bank-Account'
examples:
Example:
value:
uuid: 1263eae5-4411-48d9-bd6d-18ed93082e65
company_uuid: e2c4c0ce-2986-48b9-86cf-ec27f6ed9a36
account_type: Checking
routing_number: '851070439'
hidden_account_number: XXXX4087
verification_status: verified
verification_type: bank_deposits
name: Employer Funding Account
Company-Bank-Account-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccountsListCompanyBankAccountsResponse'
examples:
Example:
value:
- uuid: 1263eae5-4411-48d9-bd6d-18ed93082e65
company_uuid: e2c4c0ce-2986-48b9-86cf-ec27f6ed9a36
account_type: Checking
routing_number: '851070439'
hidden_account_number: XXXX4087
verification_status: verified
verification_type: bank_deposits
name: Employer Funding Account
Employee-Bank-Account-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Employee-Bank-Account'
examples:
Example:
value:
uuid: 1531e824-8d9e-4bd8-9f90-0d04608125d7
employee_uuid: 9fcf1b1d-8886-4691-9283-383d3bdd4fd9
name: BoA Checking Account
routing_number: '266905059'
hidden_account_number: XXXX1207
account_type: Checking
Employee-Bank-Account-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeePaymentMethodListBankAccountsResponse'
examples:
Example:
value:
- uuid: 1531e824-8d9e-4bd8-9f90-0d04608125d7
employee_uuid: 9fcf1b1d-8886-4691-9283-383d3bdd4fd9
name: BoA Checking Account
routing_number: '266905059'
hidden_account_number: XXXX1207
account_type: Checking
Employee-Payment-Method-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Employee-Payment-Method'
examples:
Example:
value:
version: 63859768485e218ccf8a449bb60f14ed
type: Direct Deposit
split_by: Amount
splits:
- uuid: e88f9436-b74e-49a8-87e9-777b9bfe715e
name: BoA Checking Account
priority: 1
split_amount: 500
- uuid: 0d2b7f73-05d6-4184-911d-269edeecc30a
name: Chase Checking Account
priority: 2
split_amount: 1000
- uuid: 1531e824-8d9e-4bd8-9f90-0d04608125d7
name: US Bank Checking Account
priority: 3
split_amount: null
Federal-Tax-Details-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Federal-Tax-Details'
examples:
Example:
value:
version: string
tax_payer_type: string
taxable_as_scorp: false
filing_form: string
has_ein: true
ein_verified: true
legal_name: string
Employee-State-Taxes-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeTaxSetupGetStateTaxesResponse'
examples:
Employee-State-Taxes-List-Example:
value:
employee_uuid: 92fa4d30-e284-43d0-a26e-605619c04beb
file_new_hire_report: false
is_work_state: true
state: CA
questions:
- description: >
The Head of Household status applies to unmarried
individuals who have a relative living with them in their
home. If unsure, read the CA
Filing Status explanation.
label: Filing Status
key: filing_status
input_question_format:
type: Select
options:
- value: S
label: Single
- value: M
label: Married one income
- value: MD
label: Married dual income
- value: H
label: Head of household
- value: E
label: Do Not Withhold
answers:
- value: S
valid_from: '2010-01-01'
valid_up_to: null
- description: >
This value is needed to calculate the employee's CA income
tax withholding. If unsure, use the CA DE-4
form to calculate the value manually.
label: Withholding Allowance
key: withholding_allowance
input_question_format:
type: Number
answers:
- value: 1
valid_from: '2010-01-01'
valid_up_to: null
- description: >-
You can withhold an additional amount of California income
taxes here.
label: Additional Withholding
key: additional_withholding
input_question_format:
type: Currency
answers:
- value: '0.0'
valid_from: '2010-01-01'
valid_up_to: null
- description: >-
State law requires you to file a new hire report within 20
days of hiring or re-hiring an employee.
label: File a New Hire Report?
key: file_new_hire_report
input_question_format:
type: Select
answers:
- value: true
valid_from: '2010-01-01'
valid_up_to: null
Employee-Onboarding-Status-Object:
description: Example response.
content:
application/json:
schema:
$ref: '#/components/schemas/Employee-Onboarding-Status'
examples:
Example:
value:
uuid: c44d66dc-c41b-4a60-9e25-5e93ff8583f2
onboarding_status: admin_onboarding_incomplete
onboarding_steps:
- title: Personal details
id: personal_details
required: true
completed: false
requirements: []
- title: Enter compensation details
id: compensation_detailsX
required: true
completed: false
requirements: []
- title: Add work address
id: add_work_address
required: true
completed: false
requirements: []
- title: Add home address
id: add_home_address
required: true
completed: false
requirements: []
- title: Enter federal tax withholdings
id: federal_tax_setupX
required: true
completed: false
requirements: []
- title: Enter state tax information
id: state_tax_setup
required: true
completed: false
requirements:
- add_work_address
- add_home_address
- title: Direct deposit setup
id: direct_deposit_setup
required: false
completed: false
requirements: []
- title: Employee form signing
id: employee_form_signing
required: true
completed: false
requirements:
- federal_tax_setup
- state_tax_setup
application/xml:
schema:
$ref: '#/components/schemas/EmployeesGetOnboardingStatusResponse'
examples:
Example:
value:
uuid: c44d66dc-c41b-4a60-9e25-5e93ff8583f2
onboarding_status: admin_onboarding_incomplete
onboarding_steps:
- title: Personal details
id: personal_detailsX
required: true
completed: false
requirements: []
- title: Enter compensation details
id: compensation_detailsX
required: true
completed: false
requirements: []
- title: Add work address
id: add_work_addressX
required: true
completed: false
requirements: []
- title: Add home address
id: add_home_addressX
required: true
completed: false
requirements: []
- title: Enter federal tax withholdings
id: federal_tax_setupX
required: true
completed: false
requirements: []
- title: Enter state tax information
id: state_tax_setupX
required: true
completed: false
requirements:
- add_work_address
- add_home_address
- title: Direct deposit setup
id: direct_deposit_setupX
required: false
completed: false
requirements: []
- title: Employee form signing
id: employee_form_signingX
required: true
completed: false
requirements:
- federal_tax_setup
- state_tax_setup
Payroll-Blocker-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/PayrollsGetAllPayrollBlockersResponse'
examples:
Payroll Blockers:
value:
- key: wc_pending_approval
message: Worker's compensation policy needs to be accepted.
- key: eftps_in_error
message: >-
We could not make payments to the Electronic Federal Tax
Payment System.
- key: geocode_error
message: >-
Company or employee address could not be verified. Please
ensure all addresses are valid.
- key: geocode_needed
message: >-
Company or employee address verification is missing. Please
ensure all addresses are entered correctly.
- key: pay_schedule_setup_not_complete
message: >-
Some employees don’t have a pay schedule set up yet. Please
complete this step to run payroll.
- key: invalid_signatory
message: >-
A signatory who is authorized to sign documents on behalf of
your company is required. Please ensure their identity
verification is successful.
- key: suspended
message: Company is suspended and cannot run payroll.
- key: soft_suspended
message: >-
Company is placed in a 'soft' suspension state and requires
missing/incorrect information to be corrected.
- key: pending_payroll_review
message: >-
Payroll is blocked. We are reviewing payroll information in
your account. Please contact support if you believe this is
an error.
- key: pending_recovery_case
message: >-
Payroll is blocked due to an open recovery case. Please
contact support if you believe this is an error.
- key: pending_information_request
message: >-
Payroll is blocked due to an open information request.
Please contact support if you believe this is an error.
- key: needs_approval
message: Company needs to be approved to run payroll.
- key: missing_addresses
message: Company must add addresses in order to run payroll.
- key: missing_federal_tax_setup
message: >-
Company must complete federal tax setup in order to run
payroll.
- key: missing_industry_selection
message: >-
Company must complete industry selection in order to run
payroll.
- key: missing_bank_info
message: Company must have a bank account in order to run payroll.
- key: missing_employee_setup
message: Company must add employees in order to run payroll.
- key: missing_state_tax_setup
message: >-
Company must complete state tax setup in order to run
payroll.
- key: missing_pay_schedule
message: Company must have a pay schedule in order to run payroll.
- key: missing_forms
message: Company forms must be signed in order to run payroll.
- key: missing_bank_verification
message: >-
Company bank account must be verified in order to run
payroll.
- key: missing_signatory
message: >-
Company must have a verified signatory in order to run
payroll.
Generated-Document:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Generated-Document'
examples:
Example:
value:
document_urls:
- https://document.url.com
request_uuid: p83d0ca8-7d41-42a9-834y-7d218ef6cb20
status: succeeded
Notification:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Notification'
examples:
Example:
value:
title: >-
Action required: Additional information needed to process
payroll
uuid: 7b1d0df1-6403-4a06-8768-c1dd7d24d27a
company_uuid: 88f7cca1-dcad-4d20-84db-7fb80303d69f
message: >-
If we do not receive this information as soon as possible,
your payroll may not be processed on time.
category: information_request
actionable: true
published_at: '2022-01-01T00:00:00.000Z'
Event-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/EventsGet30DayEventsResponse'
examples:
Example:
value:
- uuid: f7397a24-57ad-4fae-b011-d258e8232900
event_type: employee.bank_account.created
resource_type: Company
resource_uuid: 92a20431-9489-4bde-ad27-6feb20b969d5
entity_type: BankAccount
entity_uuid: 92a20431-9489-4bde-ad27-6feb20b969d5
timestamp: 1686784995
Payroll-Check:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Payroll-Check'
examples:
Example:
value:
payroll_uuid: a83d0bd8-7d20-43b9-834c-6d514ef6cb20
printing_format: top
starting_check_number: '10'
request_uuid: p83d0ca8-7d41-42a9-834y-7d218ef6cb20
status: pending
Payroll-Receipt:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Payroll-Receipt'
examples:
Example:
value:
totals:
company_debit: '1080.47'
net_pay_debit: '748.34'
child_support_debit: '100.0'
reimbursement_debit: '50.0'
tax_debit: '182.13'
taxes:
- name: Federal Income Tax
amount: '30.36'
- name: Social Security
amount: '104.54'
- name: Medicare
amount: '24.46'
- name: Additional Medicare
amount: '0.0'
- name: TX SUTA
amount: '22.77'
- name: FUTA
amount: '0.0'
employee_compensations:
- employee_uuid: f83d0bd8-7e20-43b9-834c-6d514ef6cb47
employee_first_name: Patricia
employee_last_name: Hamill
payment_method: Direct Deposit
net_pay: '748.34'
total_tax: '182.13'
total_garnishments: '0.0'
child_support_garnishment: '100.0'
total_reimbursement: '50.0'
licensee:
name: Gusto, Zenpayroll Inc.
address: 525 20th St
city: San Francisco
state: CA
postal_code: '94107'
phone_number: '4157778888'
payroll_uuid: afccb970-357e-4013-81f5-85dafc74f9b6
company_uuid: c827aa0d-3928-4d5a-ab1f-400641a7d2b8
name_of_sender: Torp and Sons and Sons
name_of_recipient: Payroll Recipients
recipient_notice: >-
Payroll recipients include the employees listed below plus the
tax agencies for the taxes listed below.
debit_date: '2022-06-02'
license: >-
ZenPayroll, Inc., dba Gusto is a licensed money transmitter.
For more about Gusto’s licenses and your state-specific rights
to request information, submit complaints, dispute errors, or
cancel transactions, visit our license page.
license_uri: https://gusto.com/about/licenses
right_to_refund: https://gusto.com/about/licenses
liability_of_licensee: https://gusto.com/about/licenses
Payroll-Reversal-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Payroll-Reversal'
examples:
Example:
value:
reversed_payroll_uuid: 09505984-8d8c-41a3-adbe-5740322ae8e9
reversal_payroll_uuid: 0424688e-0a2e-4cd0-ac86-42283e788fb3
reason: Customer Request
approved_at: null
category: convert_check_ee_requested
reversed_employee_uuids:
- 5f036964-185e-4c85-bbf2-3873e1203b30
Gross-Up-Pay:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Gross-Up-Pay'
examples:
Example:
value:
net_pay: '1183.25'
Contractor-Payment-Receipt:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Contractor-Payment-Receipt'
examples:
Example:
value:
receipt_id: 7757500935137343
contractor_payment_uuid: afccb970-357e-4013-81f5-85dafc74f9b6
name_of_recipient: Patricia Hamill
totals:
company_debit: '748.34'
contractor_payments:
- contractor_uuid: f83d0bd8-7e20-43b9-834c-6d514ef6cb47
contractor_first_name: Patricia
contractor_last_name: Hamill
contractor_business_name: ''
contractor_type: Individual
payment_method: Direct Deposit
wage: '448.34'
bonus: '248.00'
reimbursement: '100.00'
licensee:
name: Gusto, Zenpayroll Inc.
address: 525 20th St
city: San Francisco
state: CA
postal_code: '94107'
phone_number: '4157778888'
company_uuid: c827aa0d-3928-4d5a-ab1f-400641a7d2b8
name_of_sender: Torp and Sons and Sons
debit_date: '2022-06-02'
license: >-
ZenPayroll, Inc., dba Gusto is a licensed money transmitter.
For more about Gusto’s licenses and your state-specific rights
to request information, submit complaints, dispute errors, or
cancel transactions, visit our license page.
license_uri: https://gusto.com/about/licenses
right_to_refund: https://gusto.com/about/licenses
liability_of_licensee: https://gusto.com/about/licenses
Contractor-Bank-Account-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Contractor-Bank-Account'
examples:
Example:
value:
uuid: 1531e824-8d9e-4bd8-9f90-0d04608125d7
employee_uuid: 9fcf1b1d-8886-4691-9283-383d3bdd4fd9
name: BoA Checking Account
routing_number: '266905059'
hidden_account_number: XXXX1207
account_type: Checking
application/xml:
schema:
$ref: >-
#/components/schemas/ContractorPaymentMethodCreateBankAccountResponse
examples:
Example:
value:
uuid: 1531e824-8d9e-4bd8-9f90-0d04608125d7
employee_uuid: 9fcf1b1d-8886-4691-9283-383d3bdd4fd9
name: BoA Checking Account
routing_number: '266905059'
hidden_account_number: XXXX1207
account_type: Checking
Contractor-Bank-Account-List:
description: Example response
content:
application/json:
schema:
$ref: >-
#/components/schemas/ContractorPaymentMethodListBankAccountsResponse
examples:
Example:
value:
- uuid: 1531e824-8d9e-4bd8-9f90-0d04608125d7
employee_uuid: 9fcf1b1d-8886-4691-9283-383d3bdd4fd9
name: BoA Checking Account
routing_number: '266905059'
hidden_account_number: XXXX1207
account_type: Checking
Time-Off-Policy-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Time-Off-Policy'
examples:
Unlimited Policy:
value:
version: f5556bce3d75ec2b62bd11990aa7993a
uuid: 3f746cd0-dd08-408f-b712-8180c7c621e9
company_uuid: de83cff2-8e7a-448e-a28c-14258a9971c3
name: Test Vacation Unlimited Policy
policy_type: vacation
accrual_method: unlimited
accrual_rate: null
accrual_rate_unit: null
paid_out_on_termination: false
accrual_waiting_period_days: null
carryover_limit_hours: null
max_accrual_hours_per_year: null
max_hours: null
is_active: true
complete: true
employees:
- uuid: 05ed3150-591e-4f8b-bfd5-55d478edd2d8
- uuid: 3633ce57-abb7-422f-8c5a-455566618e6a
- uuid: 9b37429c-e540-40fb-86b3-738ca9af65c7
Fixed Policy:
value:
version: f5556bce3d75ec2b62bd11990aa7993a
uuid: 2439c13f-f6d7-4a93-af8c-175fd4cc7ce8
company_uuid: f5f7b10d-2ddb-42f6-a955-d55320ce5316
name: Test Vacation Fixed Policy
policy_type: vacation
accrual_method: per_anniversary_year
accrual_rate: '120.0'
accrual_rate_unit: null
paid_out_on_termination: true
accrual_waiting_period_days: 0
carryover_limit_hours: '240.0'
max_accrual_hours_per_year: '120.0'
max_hours: '300.0'
is_active: true
complete: true
employees:
- uuid: de7a5fb3-2e0f-460a-abbf-467fe310bf5c
balance: '80.0'
- uuid: 92af03c7-a833-43ae-bae8-f67007a59b37
balance: '60.0'
Hourly Policy:
value:
version: f5556bce3d75ec2b62bd11990aa7993a
uuid: bd5f354f-12e0-4a5e-ad1f-953bb2685ad4
company_uuid: 6767445f-5075-4ea4-a7f5-d5b5b93d4d60
name: Test Vacation Hourly Policy
policy_type: vacation
accrual_method: per_hour_paid
accrual_rate: '4.0'
accrual_rate_unit: '80.0'
paid_out_on_termination: true
accrual_waiting_period_days: 30
carryover_limit_hours: '200.0'
max_accrual_hours_per_year: '120.0'
max_hours: '240.0'
is_active: true
complete: true
employees:
- uuid: 1ea2764d-0f1a-4f09-b1d9-3006aecf63c4
balance: '56.0'
- uuid: a0db19a2-7c8f-42b4-9d4c-2e6246c3d6e8
balance: '84.0'
headers: {}
Time-Off-Policy-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/TimeOffPoliciesGetAllPoliciesResponse'
examples:
example:
value:
- version: f5556bce3d75ec2b62bd11990aa7993a
uuid: 3f746cd0-dd08-408f-b712-8180c7c621e9
company_uuid: de83cff2-8e7a-448e-a28c-14258a9971c3
name: Test Vacation Unlimited Policy
policy_type: vacation
accrual_method: unlimited
accrual_rate: null
accrual_rate_unit: null
paid_out_on_termination: false
accrual_waiting_period_days: null
carryover_limit_hours: null
max_accrual_hours_per_year: null
max_hours: null
is_active: true
complete: true
employees:
- uuid: 05ed3150-591e-4f8b-bfd5-55d478edd2d8
- uuid: 3633ce57-abb7-422f-8c5a-455566618e6a
- uuid: 9b37429c-e540-40fb-86b3-738ca9af65c7
- version: f5556bce3d75ec2b62bd11990aa7993a
uuid: 2439c13f-f6d7-4a93-af8c-175fd4cc7ce8
company_uuid: f5f7b10d-2ddb-42f6-a955-d55320ce5316
name: Test Vacation Fixed Policy
policy_type: vacation
accrual_method: per_anniversary_year
accrual_rate: '120.0'
accrual_rate_unit: null
paid_out_on_termination: true
accrual_waiting_period_days: 0
carryover_limit_hours: '240.0'
max_accrual_hours_per_year: '120.0'
max_hours: '300.0'
is_active: true
complete: true
employees:
- uuid: de7a5fb3-2e0f-460a-abbf-467fe310bf5c
balance: '80.0'
- uuid: 92af03c7-a833-43ae-bae8-f67007a59b37
balance: '60.0'
- version: f5556bce3d75ec2b62bd11990aa7993a
uuid: bd5f354f-12e0-4a5e-ad1f-953bb2685ad4
company_uuid: 6767445f-5075-4ea4-a7f5-d5b5b93d4d60
name: Test Vacation Hourly Policy
policy_type: vacation
accrual_method: per_hour_paid
accrual_rate: '4.0'
accrual_rate_unit: '80.0'
paid_out_on_termination: true
accrual_waiting_period_days: 30
carryover_limit_hours: '200.0'
max_accrual_hours_per_year: '120.0'
max_hours: '240.0'
is_active: true
complete: true
employees:
- uuid: 1ea2764d-0f1a-4f09-b1d9-3006aecf63c4
balance: '56.0'
- uuid: a0db19a2-7c8f-42b4-9d4c-2e6246c3d6e8
balance: '84.0'
Time-Off-Activity-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Time-Off-Activity'
examples:
example:
value:
- policy_uuid: a7838f74-4c29-4b70-9bfb-02a4e3e60709
time_off_type: vacation
policy_name: Paid Time Off
event_type: TimeOffEvent::AddToPolicy
event_description: 'Added to policy: Vacation Per Hour Worked'
effective_time: '2022-09-27T13:43:03.000-07:00'
balance: '0.0'
balance_change: '0.0'
- policy_uuid: a7838f74-4c29-4b70-9bfb-02a4e3e60709
time_off_type: vacation
policy_name: Paid Time Off
event_type: TimeOffEvent::Accrual
event_description: Accrual
effective_time: '2022-09-27T14:43:03.000-07:00'
balance: '2.0'
balance_change: '2.0'
headers: {}
Minimum-Wage-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Minimum-Wage'
examples:
example:
value:
uuid: 70c523ff-c71e-4474-9c83-a4ea51bd54a8
authority: State
wage: '13.0'
wage_type: Regular
effective_date: '2022-01-01'
notes: Employers with 6 or more employees
Invoice-Data-Object:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice-Data'
examples:
example:
value:
active_companies:
- company_uuid: 05ed3150-591e-4f8b-bfd5-55d478edd2d8
active_employees: 5
active_contractors: 3
initial_invoice_period: 2022-01
- company_uuid: 9b37429c-e540-40fb-86b3-738ca9af65c7
active_employees: 0
active_contractors: 1
initial_invoice_period: 2023-05
Minimum-Wage-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/LocationsGetMinimumWagesResponse'
examples:
Example:
value:
- uuid: 70c523ff-c71e-4474-9c83-a4ea51bd54a8
authority: State
wage: '13.0'
wage_type: Regular
effective_date: '2022-01-01'
notes: Employers with 6 or more employees
Recovery-Case-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/RecoveryCasesListForCompanyResponse'
examples:
Example:
value:
- uuid: e83d273e-4ae9-4b61-9c71-4030c2f73093
company_uuid: c5e3e3e9-732f-4762-849e-20b5cec9036f
status: open
latest_error_code: R01
original_debit_date: '2023-10-11'
check_date: '2023-10-13'
payroll_uuid: 210f2034-fb4a-4059-b109-6c3b5efe499d
contractor_payment_uuids: null
amount_outstanding: 10499.43
event_total_amount: 5912.07
Ach-Transaction-List:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/AchTransactionsGetAllForCompanyResponse'
examples:
Example:
value:
- description: PAY 380654
uuid: 123e4567-e89b-12d3-a456-426655440000,
company_uuid: 456e7890-e12b-34c5-d678-901234567890,
payment_event_type: Payroll,
payment_event_uuid: 789e0123-e45f-67ab-c890-123456789012,
recipient_type: Employee,
recipient_uuid: 012e3456-f78d-90ab-12cd-345678901234,
error_code: null,
transaction_type: Credit employee pay,
payment_status: submitted,
payment_direction: credit,
payment_event_check_date: 2023-10-02,
payment_date: 2023-10-17,
amount: 123.00,
schemas:
Versionable-Required:
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
required:
- version
Versionable:
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
Employee-Address:
allOf:
- $ref: '#/components/schemas/Address'
- type: object
properties:
uuid:
description: The UUID of the employee address
type: string
employee_uuid:
description: The UUID of the employee
type: string
effective_date:
description: The date the employee started living at the address.
type: string
format: date
courtesy_withholding:
description: >-
Determines if home taxes should be withheld and paid for
employee.
type: boolean
example:
uuid: 9557fe01-f8f8-4c14-a61c-ca6221a9f118
employee_uuid: da441196-43a9-4d23-ad5d-f37ce6bb99c0
street_1: 333 Kiera Stravenue
street_2: Suite 391
city: San Francisco
state: CA
zip: '94107'
country: USA
active: true
effective_date: '2021-01-01'
courtesy_withholding: true
Employee-Work-Address:
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
uuid:
description: The unique identifier of this work address.
type: string
readOnly: true
effective_date:
description: The date the employee began working at this location.
type: string
active:
description: >-
Signifies if this address is the active work address for the current
date
type: boolean
readOnly: true
location_uuid:
description: UUID reference to the company location for this work address.
type: string
employee_uuid:
description: UUID reference to the employee for this work address.
type: string
street_1:
type: string
readOnly: true
street_2:
type: string
readOnly: true
nullable: true
city:
type: string
readOnly: true
state:
type: string
readOnly: true
zip:
type: string
readOnly: true
country:
type: string
readOnly: true
default: USA
example:
version: 6a22da647ed391f184a212e6e83a541d
uuid: 34925ef7-6234-440d-83b8-788a24d0d69a
employee_uuid: 2363b9c0-6625-4425-9261-47627fd68783
location_uuid: aba6d0fd-7294-4997-b1a4-bc9268c45932
effective_date: '2023-05-15'
active: true
street_1: 977 Marks Viaduct
street_2: null
city: Pink Hill
state: NC
zip: '28572'
country: USA
Contractor-Address:
allOf:
- $ref: '#/components/schemas/Address'
- type: object
properties:
contractor_uuid:
description: The UUID of the contractor
type: integer
Address:
type: object
allOf:
- $ref: '#/components/schemas/Versionable'
- type: object
properties:
street_1:
type: string
readOnly: false
street_2:
type: string
readOnly: false
nullable: true
city:
type: string
readOnly: false
state:
type: string
readOnly: false
zip:
type: string
readOnly: false
country:
type: string
readOnly: false
default: USA
active:
description: >-
The status of the location. Inactive locations have been
deleted, but may still have historical data associated with
them.
type: boolean
readOnly: true
example:
street_1: 412 Kiera Stravenue
street_2: Suite 391
city: San Francisco
state: CA
zip: '94107'
country: USA
active: true
Department:
type: object
allOf:
- $ref: '#/components/schemas/Versionable'
- type: object
properties:
title:
description: Name of the department
type: string
uuid:
description: The UUID of the department
type: string
company_uuid:
description: The UUID of the company
type: string
employees:
description: Array of employees assigned to the department.
type: array
items:
properties:
uuid:
type: string
contractors:
description: Array of contractors assigned to the department.
type: array
items:
properties:
uuid:
type: string
Employee:
title: Employee
description: The representation of an employee in Gusto.
type: object
x-examples:
Example:
version: 414dedaca594b77135e0b8d2f398516d
uuid: 9779767c-6044-48e0-bf68-aeb370b9a2e7
first_name: Nicole
middle_initial: M
last_name: Boehm
email: kory7757869450111548@barton-hermiston.io
company_uuid: c44d66dc-c41b-4a60-9e25-5e93ff8583f2
manager_uuid: 5e53e257-c8d6-45aa-aa8a-ec99283a3acd
department: null
terminated: false
two_percent_shareholder: false
onboarded: true
onboarding_status: onboarding_completed
jobs:
- title: Client Support Manager
version: 91179081a7309c9fbd31bb3cf7b9893e
uuid: 5d5e3ce5-ea8f-4885-90e5-7ebaed03f7c5
employee_uuid: a987bce1-6d06-43f8-9978-9db886f479fb
current_compensation_uuid: 798a962f-0fcf-491e-9b71-cfa6a1db114f
payment_unit: Hour
primary: true
compensations:
- version: 233f0096a8015e62d9795fadf1fd300d
uuid: 94f17a77-cfe5-436a-af94-422bbf8248ff
payment_unit: Hour
flsa_status: Nonexempt
job_uuid: 64711ac0-83ff-4aaf-bec1-db72f5a44e56
effective_date: '2021-01-20'
rate: '22.00'
adjust_for_minimum_wage: false
rate: '22.00'
hire_date: '2020-01-20'
eligible_paid_time_off:
- name: Sick Hours
policy_name: Sick Policy
policy_uuid: 8dc8f324-3c03-4b42-8602-02476fa21c1b
accrual_unit: Hour
accrual_rate: '208.0'
accrual_method: per_hour_worked
accrual_period: Year
accrual_balance: '71.0'
maximum_accrual_balance: '240.0'
paid_at_termination: false
- name: Vacation Hours
policy_name: Vacation Policy
policy_uuid: ab59de61-239f-4805-933b-0e3360ed291c
accrual_unit: Hour
accrual_rate: '208.0'
accrual_period: Year
accrual_balance: '34.0'
maximum_accrual_balance: '240.0'
paid_at_termination: true
terminations: []
custom_fields:
- description: Employee Level
id: ee515986-f3ca-49da-b576-2691b95262f9
company_custom_field_id: ea7e5d57-6abb-47d7-b654-347c142886c0
name: employee_level
type: text
value: '2'
- description: What is your t-shirt size?
id: 3796e08d-c2e3-434c-b4de-4ce1893e7b59
company_custom_field_id: 299650e4-e970-4acf-9bf0-6f05585d20ba
name: t-shirt size
type: text
value: md
garnishments: []
date_of_birth: '1996-05-08'
has_ssn: true
ssn: ''
phone: '1234567890'
preferred_first_name: Vanessa
work_email: vanessa.boehm@example.com
x-tags:
- Employees
properties:
version:
description: >-
The current version of the employee. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
readOnly: true
uuid:
description: The UUID of the employee in Gusto.
type: string
readOnly: true
first_name:
type: string
middle_initial:
type: string
nullable: true
last_name:
type: string
email:
description: >-
The email address of the employee. This is provided to support
syncing users between our system and yours. You may not use this
email address for any other purpose (e.g. marketing).
type: string
nullable: true
company_uuid:
description: The UUID of the company the employee is employed by.
type: string
readOnly: true
manager_uuid:
description: The UUID of the employee's manager.
type: string
readOnly: true
department:
description: The employee's department in the company.
type: string
nullable: true
readOnly: true
terminated:
description: Whether the employee is terminated.
type: boolean
readOnly: true
two_percent_shareholder:
description: >-
Whether the employee is a two percent shareholder of the company.
This field only applies to companies with an S-Corp entity type.
type: boolean
onboarded:
description: Whether the employee has completed onboarding.
type: boolean
readOnly: true
onboarding_status:
description: The current onboarding status of the employee
type: string
enum:
- onboarding_completed
- admin_onboarding_incomplete
- self_onboarding_pending_invite
- self_onboarding_invited
- self_onboarding_invited_started
- self_onboarding_invited_overdue
- self_onboarding_completed_by_employee
- self_onboarding_awaiting_admin_review
readOnly: true
jobs:
type: array
items:
$ref: '#/components/schemas/Job'
eligible_paid_time_off:
type: array
items:
$ref: '#/components/schemas/Paid-Time-Off'
terminations:
type: array
items:
$ref: '#/components/schemas/Termination'
garnishments:
type: array
items:
$ref: '#/components/schemas/Garnishment'
custom_fields:
description: >-
Custom fields are only included for the employee if the include
param has the custom_fields value set
type: array
items:
$ref: '#/components/schemas/Employee-Custom-Field'
date_of_birth:
type: string
nullable: true
readOnly: true
has_ssn:
description: Indicates whether the employee has an SSN in Gusto.
type: boolean
ssn:
description: Deprecated. This field always returns an empty string.
type: string
phone:
type: string
preferred_first_name:
description: ''
type: string
payment_method:
description: The employee's payment method
type: string
enum:
- Direct Deposit
- Check
default: Check
nullable: false
work_email:
description: >-
The work email address of the employee. This is provided to support
syncing users between our system and yours. You may not use this
email address for any other purpose (e.g. marketing).
type: string
nullable: true
current_employment_status:
description: >-
The current employment status of the employee. Full-time employees
work 30+ hours per week. Part-time employees are split into two
groups: those that work 20-29 hours a week, and those that work
under 20 hours a week. Variable employees have hours that vary each
week. Seasonal employees are hired for 6 months of the year or less.
type: string
enum:
- full_time
- part_time_under_twenty_hours
- part_time_twenty_plus_hours
- variable
- seasonal
nullable: true
readOnly: true
readOnly: true
Employee-Onboarding-Status:
title: Employee-Onboarding-Status
description: The representation of an employee's onboarding status.
type: object
x-examples:
Example - Employee Onboarding by Admin:
uuid: c44d66dc-c41b-4a60-9e25-5e93ff8583f2
onboarding_status: admin_onboarding_incomplete
onboarding_steps:
- title: Personal details
id: personal_details
required: true
completed: false
requirements: []
- title: Enter compensation details
id: compensation_details
required: true
completed: false
requirements: []
- title: Add work address
id: add_work_address
required: true
completed: false
requirements: []
- title: Add home address
id: add_home_address
required: true
completed: false
requirements: []
- title: Enter federal tax withholdings
id: federal_tax_setup
required: true
completed: false
requirements: []
- title: Enter state tax information
id: state_tax_setup
required: true
completed: false
requirements:
- add_work_address
- add_home_address
- title: Direct deposit setup
id: direct_deposit_setup
required: false
completed: false
requirements: []
- title: Employee form signing
id: employee_form_signing
required: true
completed: false
requirements:
- federal_tax_setup
- state_tax_setup
- title: File new hire report
id: file_new_hire_report
required: true
completed: false
requirements:
- add_work_address
Example - Employee Self-Onboarding:
uuid: c44d66dc-c41b-4a60-9e25-5e93ff8583f2
onboarding_status: self_onboarding_invited
onboarding_steps:
- title: Personal details
id: personal_details
required: true
completed: false
requirements: []
- title: Enter compensation details
id: compensation_details
required: true
completed: false
requirements: []
- title: Add work address
id: add_work_address
required: true
completed: false
requirements: []
- title: Add home address
id: add_home_address
required: true
completed: false
requirements: []
- title: Enter federal tax withholdings
id: federal_tax_setup
required: true
completed: false
requirements: []
- title: Enter state tax information
id: state_tax_setup
required: true
completed: false
requirements:
- add_work_address
- add_home_address
- title: Direct deposit setup
id: direct_deposit_setup
required: true
completed: false
requirements: []
- title: Employee form signing
id: employee_form_signing
required: true
completed: false
requirements:
- federal_tax_setup
- state_tax_setup
- title: Admin review
id: admin_review
required: true
completed: false
requirements:
- personal_details
- compensation_details
- add_home_address
- add_work_address
- federal_tax_setup
- state_tax_setup
x-tags:
- Employees
properties:
uuid:
description: Unique identifier for this employee.
type: string
onboarding_status:
description: One of the "onboarding_status" enum values.
type: string
onboarding_steps:
description: List of steps required to onboard an employee.
type: array
items:
title: Onboarding step
type: object
properties:
title:
description: User-friendly description of the onboarding step.
type: string
id:
description: String identifier for the onboarding step.
type: string
required:
description: When true, this step has been completed.
type: boolean
completed:
description: When true, this step has been completed.
type: boolean
requirements:
description: A list of onboarding steps required to begin this step.
type: array
items:
type: string
Company-Address:
title: ''
description: The representation of a company's address in Gusto.
type: object
x-tags:
- Locations
x-examples:
Company Address:
street_1: 412 Kiera Stravenue
street_2: Suite 391
city: San Francisco
state: CA
zip: '94107'
country: USA
active: true
properties:
street_1:
type: string
readOnly: false
street_2:
type: string
readOnly: false
nullable: true
city:
type: string
readOnly: false
state:
type: string
readOnly: false
zip:
type: string
readOnly: false
country:
type: string
readOnly: false
default: USA
active:
description: >-
The status of the location. Inactive locations have been deleted,
but may still have historical data associated with them.
type: boolean
readOnly: true
Location:
title: ''
description: The representation of an address in Gusto.
type: object
x-examples:
Company Location:
version: 7d9753112507b9dda4fb97910f39b06e
company_uuid: 768a1043-f6bf-4f0b-a606-98465ea01ad7
phone_number: '5825710808'
uuid: 064a4107-c9f4-4fad-acbf-f12cd81c0d6c
street_1: 412 Kiera Stravenue
street_2: Suite 391
city: San Francisco
state: CA
zip: '94107'
country: USA
active: true
created_at: '2023-09-12T16:42:25.000-07:00'
updated_at: '2023-09-12T16:42:25.000-07:00'
x-tags:
- Locations
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
uuid:
description: The UUID of the location object.
type: string
readOnly: true
company_uuid:
description: >-
The UUID for the company to which the location belongs. Only
included if the location belongs to a company.
type: string
readOnly: true
phone_number:
description: >-
The phone number for the location. Required for company locations.
Optional for employee locations.
type: string
readOnly: false
street_1:
type: string
readOnly: false
street_2:
type: string
readOnly: false
nullable: true
city:
type: string
readOnly: false
state:
type: string
readOnly: false
zip:
type: string
readOnly: false
country:
type: string
readOnly: false
default: USA
active:
description: >-
The status of the location. Inactive locations have been deleted,
but may still have historical data associated with them.
type: boolean
readOnly: true
mailing_address:
description: >-
Specifies if the location is the company's mailing address. Only
included if the location belongs to a company.
type: boolean
nullable: true
filing_address:
description: >-
Specifies if the location is the company's filing address. Only
included if the location belongs to a company.
type: boolean
nullable: true
created_at:
description: Datetime for when location is created
type: string
updated_at:
description: Datetime for when location is updated
type: string
Paid-Time-Off:
description: The representation of paid time off in Gusto.
type: object
properties:
name:
description: The name of the paid time off type.
type: string
enum:
- Vacation Hours
- Sick Hours
- Holiday Hours
readOnly: true
policy_name:
description: The name of the time off policy.
type: string
readOnly: true
policy_uuid:
description: The UUID of the time off policy.
type: string
readOnly: true
accrual_unit:
description: The unit the PTO type is accrued in.
type: string
example: Hour
readOnly: true
accrual_rate:
description: The number of accrual units accrued per accrual period.
type: string
readOnly: true
accrual_method:
description: The accrual method of the time off policy
type: string
example: unlimited
readOnly: true
accrual_period:
description: The frequency at which the PTO type is accrued.
type: string
example: Year
readOnly: true
accrual_balance:
description: The number of accrual units accrued.
type: string
readOnly: true
maximum_accrual_balance:
description: >-
The maximum number of accrual units allowed. A null value signifies
no maximum.
type: string
nullable: true
readOnly: true
paid_at_termination:
description: >-
Whether the accrual balance is paid to the employee upon
termination.
type: boolean
readOnly: true
x-examples:
Example:
name: Sick Hours
policy_name: Sick Policy
policy_uuid: 8dc8f324-3c03-4b42-8602-02476fa21c1b
accrual_unit: Hour
accrual_rate: '208.0'
accrual_period: Year
accrual_balance: '64.0'
maximum_accrual_balance: '240.0'
paid_at_termination: false
x-tags:
- Payrolls
Garnishment:
description: >-
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.
type: object
x-examples:
Example:
description: Company loan to employee
version: 52b7c567242cb7452e89ba2bc02cb476
uuid: 4c7841a2-1363-497e-bc0f-664703c7484f
employee_uuid: a6b53294-f871-4db2-bbd4-8c3d1fe56440
active: true
amount: '8.00'
court_ordered: false
times: 5
recurring: false
annual_maximum: null
pay_period_maximum: '100.00'
deduct_as_percentage: true
properties:
description:
description: The description of the garnishment.
type: string
readOnly: false
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
uuid:
description: The UUID of the garnishment in Gusto.
type: string
readOnly: true
employee_uuid:
description: The UUID of the employee to which this garnishment belongs.
type: integer
readOnly: true
active:
description: Whether or not this garnishment is currently active.
type: boolean
default: true
amount:
description: >-
The amount of the garnishment. Either a percentage or a fixed dollar
amount. Represented as a float, e.g. "8.00".
type: string
format: float
readOnly: false
court_ordered:
description: Whether the garnishment is court ordered.
type: boolean
readOnly: false
times:
description: >-
The number of times to apply the garnishment. Ignored if recurring
is true.
type: integer
nullable: true
readOnly: false
default: null
recurring:
description: Whether the garnishment should recur indefinitely.
type: boolean
readOnly: false
default: false
annual_maximum:
description: >-
The maximum deduction per annum. A null value indicates no maximum.
Represented as a float, e.g. "200.00".
format: float
readOnly: false
default: null
type: string
nullable: true
pay_period_maximum:
description: >-
The maximum deduction per pay period. A null value indicates no
maximum. Represented as a float, e.g. "16.00".
type: string
nullable: true
format: float
default: null
deduct_as_percentage:
description: >-
Whether the amount should be treated as a percentage to be deducted
per pay period.
type: boolean
readOnly: false
default: false
Termination:
description: The representation of a termination in Gusto.
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
uuid:
description: The UUID of the termination object.
type: string
readOnly: true
employee_uuid:
description: The UUID of the employee to which this termination is attached.
type: integer
readOnly: true
active:
description: Whether the employee's termination has gone into effect.
type: boolean
readOnly: true
cancelable:
description: >-
Whether the employee's termination is cancelable. Cancelable is true
if `run_termination_payroll` is false and `effective_date` is in the
future.
type: boolean
readOnly: true
effective_date:
description: The employee's last day of work.
type: string
readOnly: false
run_termination_payroll:
description: >-
If true, the employee should receive their final wages via an
off-cycle payroll. If false, they should receive their final wages
on their current pay schedule.
type: boolean
readOnly: false
x-examples:
example-1:
version: d487dd0b55dfcacdd920ccbdaeafa351
uuid: da441196-43a9-4d23-ad5d-f37ce6bb99c0
employee_uuid: da441196-43a9-4d23-ad5d-f37ce6bb99c0
active: true
cancelable: true
effective_date: '2020-03-10'
run_termination_payroll: false
x-tags:
- Terminations
Rehire-Body:
type: object
properties:
effective_date:
description: The day when the employee returns to work.
type: string
file_new_hire_report:
description: >-
The boolean flag indicating whether Gusto will file a new hire
report for the employee.
type: boolean
work_location_uuid:
description: The uuid of the employee's work location.
type: string
employment_status:
description: >-
The employee's employment status. Supplying an invalid option will
set the employment_status to *not_set*.
type: string
enum:
- part_time
- full_time
- part_time_eligible
- variable
- seasonal
- not_set
two_percent_shareholder:
description: >-
Whether the employee is a two percent shareholder of the company.
This field only applies to companies with an S-Corp entity type.
type: boolean
required:
- effective_date
- file_new_hire_report
- work_location_uuid
Pay-Schedule-Assignment-Body:
type: object
properties:
type:
description: The pay schedule assignment type.
type: string
enum:
- single
- hourly_salaried
- by_employee
- by_department
hourly_pay_schedule_uuid:
description: Pay schedule for hourly employees.
type: string
salaried_pay_schedule_uuid:
description: Pay schedule for salaried employees.
type: string
default_pay_schedule_uuid:
description: Default pay schedule for employees.
type: string
employees:
description: List of employees and their pay schedules.
type: array
items:
type: object
properties:
employee_uuid:
description: Employee UUID
type: string
pay_schedule_uuid:
description: Pay schedule UUID
type: string
departments:
description: List of departments and their pay schedules.
type: array
items:
type: object
properties:
department_uuid:
description: Department UUID
type: string
pay_schedule_uuid:
description: Pay schedule UUID
type: string
required:
- type
Flsa-Status-Type:
description: >-
The FLSA status for this compensation. Salaried ('Exempt') employees are
paid a fixed salary every pay period. Salaried with overtime ('Salaried
Nonexempt') employees are paid a fixed salary every pay period, and
receive overtime pay when applicable. Hourly ('Nonexempt') employees are
paid for the hours they work, and receive overtime pay when applicable.
Commissioned employees ('Commission Only Exempt') earn wages based only
on commission. Commissioned with overtime ('Commission Only Nonexempt')
earn wages based on commission, and receive overtime pay when
applicable. Owners ('Owner') are employees that own at least twenty
percent of the company.
type: string
enum:
- Exempt
- Salaried Nonexempt
- Nonexempt
- Owner
- Commission Only Exempt
- Commission Only Nonexempt
Compensation:
description: The representation of compensation in Gusto.
type: object
x-examples:
Example:
version: 98jr3289h3298hr9329gf9egskt3kagri32qqgiqe3872
uuid: 910b675b-af99-404e-b8d8-562a72b76b44
job_uuid: fe9d72aa-11aa-4f6c-ba3b-4de14598cff6
rate: '70.00'
payment_unit: Hour
flsa_status: Nonexempt
effective_date: '2020-12-11'
adjust_for_minimum_wage: false
x-tags:
- Jobs and Compensations
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
uuid:
description: The UUID of the compensation in Gusto.
type: string
readOnly: true
job_uuid:
description: The UUID of the job to which the compensation belongs.
type: string
readOnly: true
rate:
description: The dollar amount paid per payment unit.
type: string
readOnly: false
payment_unit:
description: >-
The unit accompanying the compensation rate. If the employee is an
owner, rate should be 'Paycheck'.
type: string
readOnly: false
enum:
- Hour
- Week
- Month
- Year
- Paycheck
flsa_status:
$ref: '#/components/schemas/Flsa-Status-Type'
effective_date:
description: >-
The effective date for this compensation. For the first
compensation, this defaults to the job's hire date.
type: string
readOnly: false
adjust_for_minimum_wage:
description: >-
Indicates if the compensation could be adjusted to minimum wage
during payroll calculation.
type: boolean
readOnly: true
Form:
title: Form
type: object
properties:
title:
description: The title of the form
type: string
readOnly: true
description:
description: The description of the form
type: string
readOnly: true
uuid:
description: The UUID of the form
type: string
readOnly: true
name:
description: The type identifier of the form
type: string
readOnly: true
draft:
description: >-
If the form is in a draft state. E.g. End of year tax forms may be
provided in a draft state prior to being finalized.
type: boolean
readOnly: true
year:
description: >-
The year of this form. For some forms, e.g. tax forms, this is the
year which the form represents. A W2 for January - December 2022
would be delivered in January 2023 and have a year value of 2022.
This value is nullable and will not be present on all forms.
type: integer
readOnly: true
nullable: true
quarter:
description: >-
The quarter of this form. For some forms, e.g. tax forms, this is
the calendar quarter which this form represents. An Employer's
Quarterly Federal Tax Return (Form 941) for April, May, June 2022
would have a quarter value of 2 (and a year value of 2022). This
value is nullable and will not be present on all forms.
type: integer
readOnly: true
nullable: true
requires_signing:
description: >-
A boolean flag that indicates whether the form needs signing or not.
Note that this value will change after the form is signed.
type: boolean
readOnly: true
x-examples:
Example:
title: Direct Deposit Authorization
description: >-
We need you to sign paperwork to authorize us to debit and credit
your bank account and file and pay your taxes.
uuid: 48cdd5ec-a4dd-4840-a424-ad79f38d8408
name: company_direct_deposit
requires_signing: true
x-tags:
- Forms
Form_1099:
title: Form
type: object
properties:
title:
description: The title of the form
type: string
readOnly: true
description:
description: The description of the form
type: string
readOnly: true
uuid:
description: The UUID of the form
type: string
readOnly: true
name:
description: The type identifier of the form
type: string
readOnly: true
draft:
description: >-
If the form is in a draft state. E.g. End of year tax forms may be
provided in a draft state prior to being finalized.
type: boolean
readOnly: true
year:
description: >-
The year of this form. For some forms, e.g. tax forms, this is the
year which the form represents. A 1099 for January - December 2022
would be delivered in January 2023 and have a year value of 2022.
This value is nullable and will not be present on all forms.
type: integer
readOnly: true
nullable: true
quarter:
description: >-
The quarter of this form. This value is currently always null since
it is not present on any contractor forms.
type: integer
readOnly: true
nullable: true
requires_signing:
description: >-
A boolean flag that indicates whether the form needs signing or not.
Note that this value will change after the form is signed.
type: boolean
readOnly: true
contractor_uuid:
description: The contractor UUID
type: string
readOnly: true
x-examples:
Example:
title: 'Form 1099: 2020'
description: Form 1099 records your annual income as a contractor.
uuid: 48cdd5ec-a4dd-4840-a424-ad79f38d8408
name: US_1099
draft: false
requires_signing: false
year: 2020
quarter: null
contractor_uuid: 123dd616-6dbc-4724-938a-403f6217a933
x-tags:
- Forms
Form-Pdf:
title: Form Pdf
type: object
properties:
uuid:
description: the UUID of the form
type: string
readOnly: true
document_url:
description: the URL of the form
type: string
Industry:
title: Industry
type: object
properties:
title:
description: Industry title
type: string
readOnly: true
company_uuid:
description: Company uuid
type: string
readOnly: true
naics_code:
description: >-
North American Industry Classification System (NAICS) is used to
classify businesses with a six digit number based on the primary
type of work the business performs.
type: string
readOnly: true
sic_codes:
description: >-
A list of Standard Industrial Classification (SIC) codes, which are
four digit number that categorize the industries that companies
belong to based on their business activities.
type: array
readOnly: true
items:
type: string
x-examples:
Example:
title: Computer Training
company_uuid: 423dd616-6dbc-4724-938a-403f6217a933
naics_code: '611420'
sic_codes:
- '8243'
x-tags:
- Industry
Job:
title: Job
description: The representation of a job in Gusto.
type: object
properties:
title:
description: The title for the job.
type: string
readOnly: false
default: null
nullable: true
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
uuid:
description: The UUID of the job.
type: string
readOnly: true
employee_uuid:
description: The UUID of the employee to which the job belongs.
type: string
readOnly: true
hire_date:
description: The date when the employee was hired or rehired for the job.
type: string
readOnly: false
primary:
description: >-
Whether this is the employee's primary job. The value will be set to
true unless an existing job exists for the employee.
type: boolean
readOnly: true
rate:
description: The current compensation rate of the job.
type: string
readOnly: true
payment_unit:
description: The payment unit of the current compensation for the job.
type: string
readOnly: true
current_compensation_uuid:
description: The UUID of the current compensation of the job.
type: string
readOnly: true
two_percent_shareholder:
description: Whether the employee owns at least 2% of the company.
type: boolean
readOnly: false
state_wc_covered:
description: >-
Whether this job is eligible for workers' compensation coverage in
the state of Washington (WA).
type: boolean
readOnly: false
state_wc_class_code:
description: >-
The risk class code for workers' compensation in Washington state.
Please visit [Washington state's Risk Class
page](https://www.lni.wa.gov/insurance/rates-risk-classes/risk-classes-for-workers-compensation/risk-class-lookup#/)
to learn more.
type: string
readOnly: false
compensations:
type: array
items:
$ref: '#/components/schemas/Compensation'
readOnly: true
x-examples:
Example:
title: Account Director
version: d0e719137f89ca3dd334dd4cc248ffbb
uuid: d6d1035e-8a21-4e1d-89d5-fa894f9aff97
employee_uuid: 948daac8-4355-4ece-9e2a-229898accb22
current_compensation_uuid: ea8b0b90-1112-4f9d-bb93-bf029bc8537a
payment_unit: Year
primary: true
compensations:
- version: 994b75511d1debac5d7e2ddeae13679f
uuid: ea8b0b90-1112-4f9d-bb93-bf029bc8537a
payment_unit: Year
flsa_status: Exempt
job_uuid: d6d1035e-8a21-4e1d-89d5-fa894f9aff97
effective_date: '2021-01-20'
rate: '78000.00'
adjust_for_minimum_wage: false
rate: '78000.00'
hire_date: '2020-01-20'
x-tags:
- Jobs and Compensations
External-Payroll:
title: ''
description: The representation of an external payroll.
type: object
x-tags:
- External Payrolls
properties:
uuid:
description: The UUID of the external payroll.
type: string
readOnly: true
company_uuid:
description: The UUID of the company.
type: string
readOnly: true
check_date:
description: External payroll's check date.
type: string
readOnly: true
payment_period_start_date:
description: External payroll's pay period start date.
type: string
readOnly: true
payment_period_end_date:
description: External payroll's pay period end date.
type: string
readOnly: true
status:
description: >-
The status of the external payroll. The status will be `unprocessed`
when the external payroll is created and transition to `processed`
once tax liabilities are entered and finalized. Once in the
`processed` status all actions that can edit an external payroll
will be disabled.
type: string
enum:
- unprocessed
- processed
readOnly: true
external_payroll_items:
description: External payroll items for employees
type: array
readOnly: true
items:
type: object
properties:
employee_uuid:
type: string
earnings:
type: array
items:
type: object
properties:
amount:
type: string
format: float
hours:
type: string
format: float
earning_type:
type: string
earning_id:
type: integer
benefits:
type: array
items:
type: object
properties:
benefit_id:
type: integer
company_contribution_amount:
type: string
format: float
employee_deduction_amount:
type: string
format: float
taxes:
type: array
items:
type: object
properties:
tax_id:
type: integer
amount:
type: string
format: float
applicable_earnings:
description: Applicable earnings based on company provisioning.
type: array
readOnly: true
items:
type: object
properties:
earning_type:
type: string
earning_id:
type: number
name:
type: string
input_type:
type: string
category:
type: string
applicable_benefits:
description: Applicable benefits based on company provisioning.
type: array
readOnly: true
items:
type: object
properties:
description:
type: string
id:
type: integer
active:
type: boolean
applicable_taxes:
description: Applicable taxes based on company provisioning.
type: array
readOnly: true
items:
type: object
properties:
id:
type: integer
name:
type: string
employer_tax:
description: >-
Some taxes may have an amount withheld from the employee and
an amount withheld from the employer, e.g. Social Security. A
`true` value indicates this is the employer's amount.
type: boolean
resident_tax:
description: >-
Some taxes may have different rates or reporting requirements
depending on if the employee is a resident or non-resident of
the tax jurisdiction.
type: boolean
metadata:
description: Stores metadata of the external payroll.
type: object
readOnly: true
properties:
deletable:
description: Determines if the external payroll can be deleted.
type: boolean
readOnly: true
x-examples:
Example:
uuid: c5fdae57-5483-4529-9aae-f0edceed92d4
company_uuid: bcb305b0-2855-4025-8d22-e484a9e6b7c9
check_date: '2022-06-03'
payment_period_start_date: '2022-05-15'
payment_period_end_date: '2022-05-30'
status: unprocessed
external_payroll_items:
- employee_uuid: 44f7cba9-7a3d-4f08-b7bd-6fcf5211f8ca
earnings:
- amount: 10000
hours: 0
earning_type: CompanyPayType
earning_id: 1
- amount: 500
hours: 0
earning_type: CompanyEarningType
earning_id: 4
benefits:
- benefit_id: 22
company_contribution_amount: 100
employee_deduction_amount: 50
- benefit_id: 25
company_contribution_amount: 0
employee_deduction_amount: 300
taxes:
- tax_id: 1
amount: 400
- tax_id: 2
amount: 60
applicable_earnings:
- earning_type: CompanyPayType
earning_id: 1
name: Regular Wages
input_type: amount
category: default
- earning_type: CompanyEarningType
earning_id: 4
name: Cash Tips
input_type: amount
category: default
applicable_benefits:
- description: Kaiser
id: 22
active: true
- description: HSA
id: 25
active: true
applicable_taxes:
- id: 1
name: Federal Income Tax
employer_tax: false
resident_tax: false
- id: 2
name: Social Security
employer_tax: false
resident_tax: false
metadata:
deletable: true
Webhook-Subscription:
title: ''
description: The representation of webhook subscription.
type: object
x-tags:
- Webhooks
properties:
uuid:
description: The UUID of the webhook subscription.
type: string
readOnly: true
url:
description: The webhook subscriber URL. Updates will be POSTed to this URL.
type: string
readOnly: true
status:
description: The status of the webhook subscription.
type: string
enum:
- pending
- verified
- removed
readOnly: true
subscription_types:
description: Receive updates for these types.
type: array
readOnly: false
items:
type: string
enum:
- BankAccount
- Company
- CompanyBenefit
- Contractor
- ContractorPayment
- Employee
- EmployeeBenefit
- EmployeeJobCompensation
- ExternalPayroll
- Form
- Location
- Notification
- Payroll
- PaySchedule
- Signatory
x-examples:
Example:
uuid: c5fdae57-5483-4529-9aae-f0edceed92d4
url: https://partner-app.com/subscriber
status: verified
subscription_types:
- BankAccount
- Company
- CompanyBenefit
- Contractor
- ContractorPayment
- Employee
- EmployeeBenefit
- EmployeeJobCompensation
- ExternalPayroll
- Form
- Location
- Notification
- Payroll
- PaySchedule
- Signatory
External-Payroll-Basic:
title: ''
description: The representation of an external payroll with minimal information.
type: object
x-tags:
- External Payrolls
properties:
uuid:
description: The UUID of the external payroll.
type: string
readOnly: true
company_uuid:
description: The UUID of the company.
type: string
readOnly: true
check_date:
description: External payroll's check date.
type: string
readOnly: true
payment_period_start_date:
description: External payroll's pay period start date.
type: string
readOnly: true
payment_period_end_date:
description: External payroll's pay period end date.
type: string
readOnly: true
status:
description: >-
The status of the external payroll. The status will be `unprocessed`
when the external payroll is created and transition to `processed`
once tax liabilities are entered and finalized. Once in the
`processed` status all actions that can edit an external payroll
will be disabled.
type: string
enum:
- unprocessed
- processed
readOnly: true
x-examples:
Example:
uuid: c5fdae57-5483-4529-9aae-f0edceed92d4
company_uuid: bcb305b0-2855-4025-8d22-e484a9e6b7c9
check_date: '2022-06-03'
payment_period_start_date: '2022-05-15'
payment_period_end_date: '2022-05-30'
External-Payroll-Tax-Suggestions:
title: ''
description: The representation of an external payroll with minimal information.
type: object
x-tags:
- External Payrolls
properties:
employee_uuid:
description: The UUID of the employee.
type: string
readOnly: true
tax_suggestions:
description: Possible tax liabilities selections.
type: object
readOnly: true
properties:
tax_id:
description: The ID of the tax.
type: integer
readOnly: true
amount:
description: Calculated tax amount.
type: string
readOnly: true
x-examples:
Example:
employee_uuid: d21848d5-446f-48a8-9430-30fbefeabda4
tax_suggestions:
- tax_id: 1
amount: 500
- tax_id: 2
amount: 100
- tax_id: 4
amount: 30
Tax-Liabilities-Selections:
title: ''
description: The representation of tax liabilities selections.
type: object
x-tags:
- External Payrolls
properties:
tax_id:
description: The ID of the tax.
type: integer
readOnly: true
tax_name:
description: The name of the tax.
type: string
readOnly: true
last_unpaid_external_payroll_uuid:
description: The UUID of last unpaid external payroll.
type: string
nullable: true
readOnly: true
possible_liabilities:
description: Possible tax liabilities selections.
type: object
readOnly: true
properties:
liability_amount:
description: Liability amount.
type: string
readOnly: true
payroll_check_date:
description: The external payroll check date.
type: string
readOnly: true
external_payroll_uuid:
description: The UUID of the external payroll.
type: string
readOnly: true
x-examples:
Example:
tax_id: 1
tax_name: Federal Income Tax
last_unpaid_external_payroll_uuid: null
possible_liabilities:
- liability_amount: 0
payroll_check_date: null
external_payroll_uuid: null
- liability_amount: 3000
payroll_check_date: '2022-06-01'
external_payroll_uuid: 1bf1efe1-72d4-4e6e-a181-611f3ea66435
Admin:
title: Admin
description: The representation of an admin user in Gusto.
type: object
x-examples:
Example:
uuid: 987058cc-23ee-46e9-81ef-5cee086cceca
first_name: John
last_name: Smith
email: jsmith99@gmail.com
properties:
uuid:
description: The unique id of the admin.
type: string
email:
description: >-
The email of the admin for Gusto's system. If the email matches an
existing user, this will create an admin account for them.
type: string
first_name:
description: The first name of the admin.
type: string
last_name:
description: The last name of the admin.
type: string
x-tags:
- Admins
Company:
title: Company
description: The representation of a company in Gusto.
type: object
properties:
ein:
description: The Federal Employer Identification Number of the company.
type: string
readOnly: true
entity_type:
description: The tax payer type of the company.
type: string
enum:
- C-Corporation
- S-Corporation
- Sole proprietor
- LLC
- LLP
- Limited partnership
- Co-ownership
- Association
- Trusteeship
- General partnership
- Joint venture
- Non-Profit
readOnly: true
tier:
description: >-
The Gusto product tier of the company (not applicable to Embedded
partner managed companies).
type: string
nullable: true
readOnly: true
enum:
- simple
- plus
- premium
- core
- complete
- concierge
- contractor_only
- basic
is_suspended:
description: >-
Whether or not the company is suspended in Gusto. Suspended
companies may not run payroll.
type: boolean
company_status:
description: >-
The status of the company in Gusto. "Approved" companies may run
payroll with Gusto. "Not Approved" companies may not yet run payroll
with Gusto. In order to run payroll, the company may need to
complete onboarding or contact support. "Suspended" companies may
not run payroll with Gusto. In order to unsuspend their account, the
company must contact support.
type: string
enum:
- Approved
- Not Approved
- Suspended
readOnly: true
uuid:
description: A unique identifier of the company in Gusto.
type: string
readOnly: true
name:
description: The name of the company.
type: string
readOnly: true
slug:
description: The slug of the name of the company.
type: string
readOnly: true
trade_name:
description: The trade name of the company.
type: string
readOnly: true
is_partner_managed:
description: Whether the company is fully managed by a partner via the API
type: boolean
readOnly: true
pay_schedule_type:
description: The pay schedule assignment type.
type: string
enum:
- single
- hourly_salaried
- by_employee
- by_department
readOnly: true
join_date:
description: Company's first invoiceable event date
type: string
readOnly: true
funding_type:
description: Company's default funding type
type: string
enum:
- ach
- reverse_wire
- wire_in
- brex
locations:
description: The locations of the company.
type: array
uniqueItems: false
items:
$ref: '#/components/schemas/Company-Address'
readOnly: true
compensations:
description: The available company-wide compensation rates for the company.
type: object
properties:
hourly:
description: The available hourly compensation rates for the company.
type: array
uniqueItems: true
items:
type: object
properties:
name:
description: The name of the hourly compensation rate.
type: string
example: Overtime
readOnly: true
multiple:
description: >-
The amount multiplied by the base rate of a job to
calculate compensation.
type: number
example: 1.5
readOnly: true
readOnly: true
readOnly: true
fixed:
description: The available fixed compensation rates for the company.
type: array
uniqueItems: true
items:
type: object
properties:
name:
description: The name of the fixed compensation.
type: string
example: Bonus
readOnly: true
readOnly: true
paid_time_off:
description: The available types of paid time off for the company.
type: array
uniqueItems: true
items:
type: object
properties:
name:
description: The name of the paid time off type.
type: string
example: Vacation Hours
readOnly: true
readOnly: true
readOnly: true
readOnly: true
primary_signatory:
description: The primary signatory of the company.
type: object
properties:
first_name:
type: string
readOnly: true
middle_initial:
type: string
readOnly: true
last_name:
type: string
readOnly: true
phone:
type: string
readOnly: true
email:
type: string
readOnly: true
home_address:
type: object
properties:
street_1:
type: string
readOnly: true
street_2:
type: string
nullable: true
readOnly: true
city:
type: string
readOnly: true
state:
type: string
readOnly: true
zip:
type: string
readOnly: true
country:
type: string
readOnly: true
readOnly: true
readOnly: true
primary_payroll_admin:
description: The primary payroll admin of the company.
type: object
properties:
first_name:
type: string
readOnly: true
last_name:
type: string
readOnly: true
phone:
type: string
readOnly: true
email:
type: string
readOnly: true
x-examples:
Example:
ein: 00-0000001
entity_type: C-Corporation
tier: complete
is_suspended: false
company_status: Approved
name: Shoppe Studios LLC
trade_name: Record Shoppe
is_partner_managed: false
pay_schedule_type: by_department
locations:
- street_1: 412 Kiera Stravenue
street_2: Suite 391
city: San Francisco
state: CA
zip: '94107'
country: USA
active: true
- street_1: 644 Fay Vista
street_2: Suite 842
city: Richmond
state: VA
zip: '23218'
country: USA
active: true
compensations:
hourly:
- name: Overtime
multiple: 1.5
- name: Double overtime
multiple: 2
- name: Regular
multiple: 1
- name: Outstanding vacation
multiple: 1
- name: Holiday
multiple: 1
- name: Emergency sick - self care
multiple: 1
- name: Emergency sick - caring for others
multiple: 1
- name: FMLA Public Health Emergency Leave
multiple: 1
- name: Regular Hours
multiple: 1
fixed:
- name: Bonus
- name: Commission
- name: Paycheck Tips
- name: Cash Tips
- name: Correction Payment
- name: Severance
- name: Minimum Wage Adjustment
- name: Reimbursement
paid_time_off:
- name: Vacation Hours
- name: Sick Hours
- name: Holiday Hours
primary_signatory:
first_name: Alda
middle_initial: ''
last_name: Carter
phone: null
email: louie.hessel7757869450111547@zemlak.biz
home_address:
street_1: 524 Roob Divide
street_2: Suite 565
city: San Francisco
state: CA
zip: '94107'
country: USA
primary_payroll_admin:
first_name: Ian
last_name: Labadie
phone: 1-565-710-7559
email: louie.hessel7757869450111547@zemlak.biz
x-tags:
- Companies
Company-Onboarding-Status:
title: ''
description: The representation of a company's onboarding status
type: object
x-examples:
Example:
uuid: c44d66dc-c41b-4a60-9e25-5e93ff8583f2
onboarding_completed: false
onboarding_steps:
- title: Add Your Company's Addresses
id: add_addresses
required: true
completed: true
skippable: false
requirements: []
- title: Add Your Employees
id: add_employees
required: true
completed: true
skippable: true
requirements:
- add_addresses
- title: Enter Your Federal Tax Information
id: federal_tax_setup
required: true
completed: true
skippable: false
requirements:
- add_addresses
- add_employees
- title: Add Your Bank Account
id: add_bank_info
required: true
completed: true
skippable: false
requirements: []
- title: Select a Pay Schedule
id: payroll_schedule
required: true
completed: false
skippable: false
requirements: []
- title: Sign Documents
id: sign_all_forms
required: true
completed: false
skippable: false
requirements:
- add_employees
- federal_tax_setup
- state_setup
- add_bank_info
- payroll_schedule
- title: Verify Your Bank Account
id: verify_bank_info
required: true
completed: false
skippable: false
requirements:
- add_bank_info
x-tags:
- Companies
properties:
uuid:
description: the UUID of the company
type: string
onboarding_completed:
description: a boolean flag for the company's onboarding status
type: boolean
onboarding_steps:
description: a list of company onboarding steps
type: array
items:
title: Onboarding step
type: object
properties:
title:
description: The display name of the onboarding step
type: string
id:
description: The string identifier for each onboarding step
type: string
required:
description: >-
The boolean flag indicating whether the step is required or
optional
type: boolean
completed:
description: >-
The boolean flag indicating whether the step is completed or
not.
type: boolean
skippable:
description: >-
The boolean flag indicating whether the step can be skipped or
not.
type: boolean
requirements:
description: >-
A list of onboarding step that are required to be completed in
order to proceed with the current onboarding step.
type: array
items:
type: string
'':
type: string
Payment-Configs:
title: Payment-Configs
type: object
properties:
company_uuid:
description: Company uuid
type: string
readOnly: true
partner_uuid:
description: Partner uuid
type: string
readOnly: true
fast_payment_limit:
description: Payment limit for 1-day or 2-day payroll
type: string
readOnly: true
payment_speed:
description: Payment speed for 1-day, 2-day, 4-day
type: string
readOnly: true
x-examples:
Example:
company_uuid: 423dd616-6dbc-4724-938a-403f6217a933
partner_uuid: 556f05d0-48e0-4c47-bce5-db9aea923043
fast_payment_limit: '5000'
payment_speed: 2-day
x-tags:
- Payment Configs
Contractor-Body:
type: object
properties:
type:
description: The contractor type.
type: string
default: Individual
enum:
- Individual
- Business
wage_type:
description: |
The contractor’s wage type.
type: string
enum:
- Fixed
- Hourly
start_date:
description: |
The day when the contractor will start working for the company.
type: string
example: '2020-01-11'
hourly_rate:
description: >-
The contractor’s hourly rate. This attribute is required if the
wage_type is `Hourly`.
type: string
example: '40.0'
self_onboarding:
description: >-
Whether the contractor or the payroll admin will complete onboarding
in Gusto.
Self-onboarding is recommended so that contractors receive Gusto
accounts.
If self_onboarding is true, then email is required.
type: boolean
default: false
email:
description: The contractor’s email address.
type: string
first_name:
description: >-
The contractor’s first name.
This attribute is required for `Individual` contractors and will be
ignored for `Business` contractors.
type: string
last_name:
description: >-
The contractor’s last name.
This attribute is required for `Individual` contractors and will be
ignored for `Business` contractors.
type: string
middle_initial:
description: >-
The contractor’s middle initial.
This attribute is optional for `Individual` contractors and will be
ignored for `Business` contractors.
type: string
file_new_hire_report:
description: >-
The boolean flag indicating whether Gusto will file a new hire
report for the contractor.
This attribute is optional for `Individual` contractors and will be
ignored for `Business` contractors.
type: boolean
default: false
work_state:
description: >-
State where the contractor will be conducting the majority of their
work for the company.
This value is used when generating the new hire report.
This attribute is required for `Individual` contractors if
`file_new_hire_report` is true and will be ignored for `Business`
contractors.
type: string
nullable: true
ssn:
description: >-
This attribute is optional for `Individual` contractors and will be
ignored for `Business` contractors.
Social security number is needed to file the annual 1099 tax form.
type: string
pattern: '[0-9]{9}'
business_name:
description: >-
The name of the contractor business. This attribute is required for
`Business` contractors and will be ignored for `Individual`
contractors.
type: string
ein:
description: >-
The employer identification number of the contractor business.
This attribute is optional for `Business` contractors and will be
ignored for `Individual` contractors.
type: string
is_active:
description: The status of the contractor.
type: boolean
Contractor:
description: The representation of a contractor (individual or business) in Gusto.
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
uuid:
description: The UUID of the contractor in Gusto.
type: string
readOnly: true
company_uuid:
description: The UUID of the company the contractor is employed by.
type: string
readOnly: true
wage_type:
description: The contractor's wage type, either "Fixed" or "Hourly".
type: string
enum:
- Fixed
- Hourly
is_active:
description: The status of the contractor with the company.
type: boolean
default: true
readOnly: true
type:
description: 'The contractor''s type, either "Individual" or "Business". '
type: string
enum:
- Individual
- Business
first_name:
description: >-
The contractor’s first name. This attribute is required for
“Individual” contractors and will be ignored for “Business”
contractors.
type: string
nullable: true
last_name:
description: >-
The contractor’s last name. This attribute is required for
“Individual” contractors and will be ignored for “Business”
contractors.
type: string
nullable: true
middle_initial:
description: >-
The contractor’s middle initial. This attribute is optional for
“Individual” contractors and will be ignored for “Business”
contractors.
type: string
nullable: true
business_name:
description: >-
The name of the contractor business. This attribute is required for
“Business” contractors and will be ignored for “Individual”
contractors.
type: string
nullable: true
ein:
description: >-
The Federal Employer Identification Number of the contractor
business. This attribute is optional for “Business” contractors and
will be ignored for “Individual” contractors.
type: string
nullable: true
has_ein:
description: Whether company's Employer Identification Number (EIN) is present
type: boolean
nullable: true
email:
description: >-
The contractor’s email address. This attribute is optional for
“Individual” contractors and will be ignored for “Business”
contractors.
type: string
nullable: true
start_date:
description: The contractor's start date.
type: string
readOnly: true
address:
description: The contractor’s home address.
type: object
properties:
street_1:
type: string
readOnly: true
street_2:
type: string
nullable: true
readOnly: true
city:
type: string
readOnly: true
state:
type: string
readOnly: true
zip:
type: string
readOnly: true
country:
type: string
readOnly: true
readOnly: true
hourly_rate:
description: >-
The contractor’s hourly rate. This attribute is required if the
wage_type is “Hourly”.
type: string
example: '50.0'
file_new_hire_report:
description: >-
The boolean flag indicating whether Gusto will file a new hire
report for the contractor
type: boolean
default: false
work_state:
description: >-
State where the contractor will be conducting the majority of their
work for the company.
This value is used when generating the new hire report.
type: string
nullable: true
onboarded:
description: The updated onboarding status for the contractor
type: boolean
onboarding_status:
description: One of the "onboarding_status" enum values.
type: string
enum:
- onboarding_completed
- admin_onboarding_review
- admin_onboarding_incomplete
x-tags:
- Contractors
Contractor-Onboarding-Status:
title: Contractor-Onboarding-Status
description: The representation of an contractor's onboarding status.
type: object
x-tags:
- Contractor
properties:
uuid:
description: Unique identifier for this contractor.
type: string
onboarding_status:
description: One of the "onboarding_status" enum values.
type: string
enum:
- onboarding_completed
- admin_onboarding_review
- admin_onboarding_incomplete
onboarding_steps:
description: List of steps required to onboard a contractor.
type: array
items:
title: Onboarding step
type: object
properties:
title:
description: User-friendly description of the onboarding step.
type: string
id:
description: String identifier for the onboarding step.
type: string
required:
description: When true, this step is required.
type: boolean
completed:
description: When true, this step has been completed.
type: boolean
requirements:
description: A list of onboarding steps required to begin this step.
type: array
items:
type: string
Contractor-Payment:
title: Contractor Payment
description: The representation of a single contractor payment.
type: object
x-examples:
Example:
uuid: 04552eb9-7829-4b18-ae96-6983552948df
bonus: '20.0'
date: '2020-10-19'
hours: '40.0'
payment_method: Direct Deposit
reimbursement: '100.0'
hourly_rate: '18.0'
may_cancel: true
status: Funded
wage: '0.0'
wage_type: Hourly
wage_total: '740.00'
properties:
uuid:
description: The unique identifier of the contractor payment in Gusto.
type: string
readOnly: true
contractor_uuid:
description: The UUID of the contractor.
type: string
readOnly: true
bonus:
description: The bonus amount in the payment.
type: string
readOnly: true
date:
description: The payment date.
type: string
readOnly: true
hours:
description: The number of hours worked for the payment.
type: string
readOnly: true
payment_method:
description: The payment method.
type: string
enum:
- Direct Deposit
- Check
- Historical Payment
- Correction Payment
readOnly: true
reimbursement:
description: The reimbursement amount in the payment.
type: string
readOnly: true
status:
description: Contractor payment status
type: string
enum:
- Funded
- Unfunded
hourly_rate:
description: The rate per hour worked for the payment.
type: string
readOnly: true
may_cancel:
description: Determine if the contractor payment can be cancelled.
type: boolean
readOnly: true
wage:
description: The fixed wage of the payment, regardless of hours worked.
type: string
readOnly: true
wage_type:
description: The wage type for the payment.
type: string
enum:
- Hourly
- Fixed
readOnly: true
wage_total:
description: (hours * hourly_rate) + wage + bonus
type: string
readOnly: true
x-tags:
- Contractor Payments
Contractor-Payment-Summary:
description: >-
The representation of the summary of contractor payments for a given
company in a given time period.
type: object
x-examples:
Example:
total:
reimbursements: '110.0'
wages: '1840.0'
contractor_payments:
- contractor_uuid: bc57832c-d8bc-43a7-ae99-3a03380ff037
reimbursement_total: '110.0'
wage_total: '1840.0'
payments:
- uuid: 04552eb9-7829-4b18-ae96-6983552948df
contractor_uuid: bc57832c-d8bc-43a7-ae99-3a03380ff037
bonus: '20.0'
date: '2020-10-19'
hours: '40.0'
payment_method: Direct Deposit
reimbursement: '100.0'
hourly_rate: '18.0'
may_cancel: true
wage: '0.0'
wage_type: Hourly
wage_total: '740.00'
- uuid: 25cfeb96-17fc-4fdf-8941-57f3fb9eea00
contractor_uuid: bc57832c-d8bc-43a7-ae99-3a03380ff037
bonus: '100.0'
date: '2020-10-19'
hours: '0.00'
payment_method: Direct Deposit
reimbursement: '10.0'
hourly_rate: '0.0'
may_cancel: true
wage: '1000.0'
wage_type: Fixed
wage_total: '1100.0'
properties:
total:
description: >-
The wage and reimbursement totals for all contractor payments within
a given time period.
type: object
properties:
reimbursements:
description: >-
The total reimbursements for contractor payments within a given
time period.
type: string
readOnly: true
wages:
description: >-
The total wages for contractor payments within a given time
period.
type: string
readOnly: true
readOnly: true
contractor_payments:
description: >-
The individual contractor payments, within a given time period,
grouped by contractor.
type: array
uniqueItems: false
items:
description: ''
type: object
properties:
contractor_uuid:
description: The UUID of the contractor.
type: number
readOnly: true
reimbursement_total:
description: >-
The total reimbursements for the contractor within a given
time period.
type: string
readOnly: true
wage_total:
description: The total wages for the contractor within a given time period.
type: string
readOnly: true
payments:
description: |
The contractor’s payments within a given time period.
type: array
uniqueItems: false
items:
$ref: '#/components/schemas/Contractor-Payment'
readOnly: true
readOnly: true
readOnly: true
x-tags:
- Contractor Payments
Contractor-Payment-Summary-By-Dates:
description: >-
The representation of the summary of contractor payments for a given
company in a given time period.
type: object
x-examples:
Example:
total:
reimbursements: '110.0'
wages: '1840.0'
contractor_payments:
- check_date: '2020-10-19'
reimbursement_total: '110.0'
wage_total: '1840.0'
payments:
- uuid: 04552eb9-7829-4b18-ae96-6983552948df
contractor_uuid: bc57832c-d8bc-43a7-ae99-3a03380ff037
bonus: '20.0'
date: '2020-10-19'
hours: '40.0'
payment_method: Direct Deposit
reimbursement: '100.0'
hourly_rate: '18.0'
wage: '0.0'
wage_type: Hourly
wage_total: '740.00'
- uuid: 25cfeb96-17fc-4fdf-8941-57f3fb9eea00
contractor_uuid: bc57832c-d8bc-43a7-ae99-3a03380ff037
bonus: '100.0'
date: '2020-10-19'
hours: '0.00'
payment_method: Direct Deposit
reimbursement: '10.0'
hourly_rate: '0.0'
wage: '1000.0'
wage_type: Fixed
wage_total: '1100.0'
properties:
total:
description: >-
The wage and reimbursement totals for all contractor payments within
a given time period.
type: object
properties:
reimbursements:
description: >-
The total reimbursements for contractor payments within a given
time period.
type: string
readOnly: true
wages:
description: >-
The total wages for contractor payments within a given time
period.
type: string
readOnly: true
readOnly: true
contractor_payments:
description: >-
The individual contractor payments, within a given time period,
grouped by check date.
type: array
uniqueItems: false
items:
description: ''
type: object
properties:
contractor_uuid:
description: The UUID of the contractor.
type: string
readOnly: true
check_date:
description: The payment check date.
type: string
readOnly: true
reimbursement_total:
description: >-
The total reimbursements for the contractor within a given
time period.
type: string
readOnly: true
wage_total:
description: The total wages for the contractor within a given time period.
type: string
readOnly: true
payments:
description: |
The contractor’s payments within a given time period.
type: array
uniqueItems: false
items:
$ref: '#/components/schemas/Contractor-Payment'
readOnly: true
readOnly: true
readOnly: true
x-tags:
- Contractor Payments
Contractor-Payment-Method:
title: Contractor-Payment-Method
description: ''
type: object
x-examples:
Example-1:
value:
version: 63859768485e218ccf8a449bb60f14ed
type: Direct Deposit
split_by: Percentage
splits:
- uuid: e88f9436-b74e-49a8-87e9-777b9bfe715e
name: BoA Checking Account
priority: 1
split_amount: 100
Example-2:
value:
version: 63859768485e218ccf8a449bb60f14ed
type: Check
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
type:
description: >-
The payment method type. If type is Check, then split_by and splits
do not need to be populated. If type is Direct Deposit, split_by and
splits are required.
type: string
enum:
- Direct Deposit
- Check
split_by:
description: >-
Describes how the payment will be split. If split_by is Percentage,
then the split amounts must add up to exactly 100. If split_by is
Amount, then the last split amount must be nil to capture the
remainder.
type: string
enum:
- Amount
- Percentage
nullable: true
splits:
type: array
nullable: true
items:
$ref: '#/components/schemas/Payment-Method-Bank-Account'
x-tags:
- Contractor Payment Method
Payment-Method-Bank-Account:
description: Representation of a bank account item
type: object
properties:
uuid:
description: The bank account ID
type: string
name:
description: The bank account name
type: string
hidden_account_number:
description: Masked bank account number
type: string
priority:
description: >-
The order of priority for each payment split, with priority 1 being
the first bank account paid. Priority must be unique and sequential.
type: integer
split_amount:
description: The cents amount allocated for each payment split
type: integer
nullable: true
Time-Off-Request:
title: Time-Off-Request
description: 'The representation of a time off request. '
type: object
x-examples:
Example:
id: '1'
status: approved
employee_note: Vacation at Disney World!
employer_note: But Universal has Harry Potter World...
days:
'2019-06-01': '4.000'
'2019-06-02': '8.000'
'2019-06-03': '2.000'
request_type: vacation
employee:
id: '234567'
full_name: Jessica Gusto
approver:
id: '345678'
full_name: Karen Gusto
initiator:
id: '234567'
full_name: Jessica Gusto
x-tags:
- Time Off Requests
properties:
id:
description: The ID of the time off request.
type: integer
readOnly: true
status:
description: The status of the time off request.
type: string
enum:
- pending
- approved
- denied
readOnly: true
employee_note:
description: >-
A note about the time off request, from the employee to the
employer.
type: string
readOnly: true
employer_note:
description: >-
A note about the time off request, from the employer to the
employee.
type: string
readOnly: true
request_type:
description: The type of time off request.
type: string
enum:
- vacation
- sick
readOnly: true
days:
description: >-
An object that represents the days in the time off request. The keys
of the object are the dates, formatted as a YYYY-MM-DD string. The
values of the object are the number of hours requested off for each
day, formatted as a string representation of a numeric decimal to
the thousands place.
type: object
readOnly: true
employee:
description: ''
type: object
properties:
id:
description: The ID of the employee the time off request is for.
type: string
readOnly: true
full_name:
description: The full name of the employee the time off request is for.
type: string
readOnly: true
readOnly: true
initiator:
description: ''
type: object
nullable: true
properties:
id:
description: The ID of the employee who initiated the time off request.
type: string
readOnly: true
full_name:
description: >-
The full name of the employee who initiated the time off
request.
type: string
readOnly: true
readOnly: true
approver:
description: This value will be null if the request has not been approved.
type: object
nullable: true
properties:
id:
description: The ID of the employee who approved the time off request.
type: string
readOnly: true
full_name:
description: The full name of the employee who approved the time off request.
type: string
readOnly: true
readOnly: true
Unprocessable-Entity-Error-Object:
description: >
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](https://docs.gusto.com/embedded-payroll/docs/error-categories)
guide for more details.
type: object
properties:
errors:
type: array
items:
type: object
properties:
error_key:
description: >-
Specifies where the error occurs. Typically this key
identifies the attribute/parameter related to the error.
type: string
category:
description: >-
Specifies the type of error. The category provides error
groupings and can be used to build custom error handling in
your integration.
type: string
message:
description: >-
Provides details about the error - generally this message can
be surfaced to an end user.
type: string
metadata:
description: >-
Contains relevant data to identify the resource in question
when applicable. For example, to identify an entity
`entity_type` and `entity_uuid` will be provided.
type: object
Payroll-Blockers-Error:
description: >-
Payroll Blockers Error
For detailed information, see the [Payroll Blockers
guide](https://docs.gusto.com/embedded-payroll/docs/payroll-blockers)
type: object
properties:
errors:
type: array
items:
type: object
properties:
error_key:
description: The string "base"
type: string
category:
description: The string "payroll_blocker"
type: string
message:
description: Human readable description of the payroll blocker
type: string
metadata:
type: object
properties:
key:
description: >-
A categorization of the payroll blocker, e.g.
"geocode_error"
type: string
Authentication:
description: ''
type: object
properties:
access_token:
description: >-
A new access token that can be used for subsequent authenticated
requests
type: string
token_type:
description: The literal string 'bearer'
type: string
default: bearer
expires_in:
description: >-
The TTL of this token. After this amount of time, you must hit the
refresh token endpoint to continue making authenticated requests.
type: number
default: 7200
refresh_token:
description: >-
A token that must be passed to the refresh token endpoint to get a
new authenticated token.
type: string
created_at:
description: Datetime for when the new access token is created.
type: string
scope:
description: All of the scopes for which the access token provides access.
type: string
Pay-Schedule:
title: Pay Schedule
description: The representation of a pay schedule.
type: object
x-examples:
Example:
uuid: f2a69c38-e2f9-4e31-b5c5-4754fc60a052
frequency: Twice per month
anchor_pay_date: '2020-05-15'
anchor_end_of_pay_period: '2020-05-08'
day_1: 15
day_2: 31
name: Engineering
auto_pilot: false
custom_name: A new monthly pay schedule
properties:
uuid:
description: The unique identifier of the pay schedule in Gusto.
type: string
readOnly: true
frequency:
description: >-
The frequency that employees on this pay schedule are paid with
Gusto.
type: string
enum:
- Every week
- Every other week
- Twice per month
- Monthly
- Quarterly
- Annually
readOnly: true
anchor_pay_date:
description: >-
The first date that employees on this pay schedule are paid with
Gusto.
type: string
readOnly: true
anchor_end_of_pay_period:
description: >-
The last date of the first pay period. This can be the same date as
the anchor pay date.
type: string
readOnly: true
day_1:
description: >-
An integer between 1 and 31 indicating the first day of the month
that employees are paid. This field is only relevant for pay
schedules with the “Twice per month” and “Monthly” frequencies. It
will be null for pay schedules with other frequencies.
type: integer
nullable: true
readOnly: true
day_2:
description: >-
An integer between 1 and 31 indicating the second day of the month
that employees are paid. This field is the second pay date for pay
schedules with the "Twice per month" frequency. For semi-monthly pay
schedules, this field should be set to 31. For months shorter than
31 days, we will set the second pay date to the last day of the
month. It will be null for pay schedules with other frequencies.
type: integer
nullable: true
readOnly: true
name:
description: >-
This field will be hourly when the pay schedule is for hourly
employees, salaried when the pay schedule is for salaried employees,
the department name if pay schedule is by department, and null when
the pay schedule is for all employees.
type: string
nullable: true
readOnly: true
custom_name:
description: >-
A custom name for a pay schedule, defaults to the pay frequency
description.
type: string
readOnly: true
auto_pilot:
description: >-
With Autopilot® enabled, payroll will run automatically one day
before your payroll deadlines.
type: boolean
active:
description: >-
Whether this pay schedule is associated with any employees. A pay
schedule is inactive when it's unassigned.
type: boolean
readOnly: true
x-tags:
- Pay Schedules
Company-Bank-Account:
description: The company bank account
type: object
x-examples:
Example:
uuid: 1263eae5-4411-48d9-bd6d-18ed93082e65
company_uuid: e2c4c0ce-2986-48b9-86cf-ec27f6ed9a36
account_type: Checking
routing_number: '851070439'
hidden_account_number: XXXX4087
verification_status: verified
verification_type: bank_deposits
name: Employer Funding Account
x-tags:
- Company Bank Accounts
properties:
uuid:
description: UUID of the bank account
type: string
company_uuid:
description: UUID of the company
type: string
account_type:
description: Bank account type
type: string
enum:
- Checking
- Savings
routing_number:
description: The bank account's routing number
type: string
hidden_account_number:
description: Masked bank account number
type: string
verification_status:
description: >-
The verification status of the bank account.
'awaiting_deposits' means the bank account is just created and money
is being transferred.
'ready_for_verification' means the micro-deposits are completed and
the verification process can begin by using the verify endpoint.
'verified' means the bank account is verified.
type: string
enum:
- awaiting_deposits
- ready_for_verification
- verified
verification_type:
description: >-
The verification type of the bank account.
'bank_deposits' means the bank account is connected by entering
routing and accounting numbers and verifying through micro-deposits.
'plaid' means the bank account is connected through Plaid.
type: string
enum:
- bank_deposits
- plaid
- plaid_external
plaid_status:
description: >-
The Plaid connection status of the bank account. Only applies when
verification type is Plaid.
type: string
enum:
- connected
- disconnected
last_cached_balance:
description: >-
The last fetch balance for the bank account. Please be aware that
this amount does not reflect the most up-to-date balance and only
applies when the verification type is Plaid.
type: string
balance_fetched_date:
description: >-
The balance fetch date associated with the last_cached_balance. Only
applies when verification type is Plaid.
type: string
name:
description: Name of bank account
type: string
Benefit-Type-Requirements:
description: ''
type: object
x-tags:
- Company Benefits
properties:
employee_deduction:
description: ''
type: object
properties:
required:
type: boolean
editable:
type: boolean
default_value:
type: object
properties:
value:
type: string
type:
type: string
choices:
type: array
items:
type: string
contribution:
description: ''
type: object
properties:
required:
type: boolean
editable:
type: boolean
default_value:
type: object
properties:
value:
type: string
type:
type: string
choices:
type: array
items:
type: string
deduct_as_percentage:
description: ''
type: object
properties:
required:
type: boolean
editable:
type: boolean
default_value:
type: object
properties:
value:
type: string
type:
type: string
choices:
type: array
items:
type: string
catch_up:
description: ''
type: object
properties:
required:
type: boolean
editable:
type: boolean
default_value:
type: object
properties:
value:
type: string
type:
type: string
choices:
type: array
items:
type: string
limit_option:
description: ''
type: object
properties:
required:
type: boolean
editable:
type: boolean
default_value:
type: object
properties:
value:
type: string
type:
type: string
choices:
type: array
items:
type: string
company_contribution_annual_maximum:
description: ''
type: object
properties:
required:
type: boolean
editable:
type: boolean
default_value:
type: object
properties:
value:
type: string
type:
type: string
choices:
type: array
items:
type: string
coverage_salary_multiplier:
description: ''
type: object
properties:
required:
type: boolean
editable:
type: boolean
default_value:
type: object
properties:
value:
type: string
type:
type: string
choices:
type: array
items:
type: string
coverage_amount:
description: ''
type: object
properties:
required:
type: boolean
editable:
type: boolean
default_value:
type: object
properties:
value:
type: string
type:
type: string
choices:
type: array
items:
type: string
Benefit-Summary:
description: ''
type: object
x-tags:
- Company Benefits
properties:
description:
description: Description of the benefit.
type: string
start_date:
description: The start date of benefit summary.
type: string
end_date:
description: The end date of benefit summary.
type: string
company_benefit_deduction:
description: >-
The aggregate of employee deduction for all employees given the
period of time and benefit type.
type: string
company_benefit_contribution:
description: >-
The aggregate of company contribution for all employees given the
period of time and benefit type.
type: string
employees:
description: ''
type: object
properties:
uuid:
description: The UUID of the employee
type: string
company_benefit_deduction:
description: >-
The aggregate of employee deduction for all employees given the
period of time and benefit type.
type: string
company_benefit_contribution:
description: >-
The aggregate of company contribution for all employees given
the period of time and benefit type.
type: string
benefit_deduction:
description: >-
Sum of employee benefit deduction given the period of time for
this specific employee.
type: string
benefit_contribution:
description: >-
Sum of company contribution given the period of time for this
specific employee.
type: string
gross_pay:
description: Gross pay of this pay check.
type: string
payroll_benefits:
type: object
properties:
payroll_uuid:
type: string
payroll_type:
description: Whether it is regular or bonus payroll
type: string
check_date:
type: string
gross_pay:
type: string
company_benefit_deduction:
type: string
company_benefit_contribution:
type: string
pay_period:
type: object
properties:
start_date:
type: string
end_date:
type: string
Supported-Benefit:
description: ''
type: object
properties:
description:
description: The description of the benefit.
type: string
readOnly: true
benefit_type:
description: The benefit type in Gusto.
type: number
readOnly: true
name:
description: The name of the benefit.
type: string
readOnly: true
pretax:
description: >-
Whether the benefit is deducted before tax calculations, thus
reducing one’s taxable income
type: boolean
readOnly: true
posttax:
description: Whether the benefit is deducted after tax calculations.
type: boolean
readOnly: true
imputed:
description: Whether the benefit is considered imputed income.
type: boolean
readOnly: true
healthcare:
description: Whether the benefit is healthcare related.
type: boolean
readOnly: true
retirement:
description: Whether the benefit is associated with retirement planning.
type: boolean
readOnly: true
yearly_limit:
description: Whether the benefit has a government mandated yearly limit.
type: boolean
readOnly: true
category:
description: Category where the benefit belongs to.
type: string
readOnly: true
x-examples:
Example:
description: Deductions and contributions for Medical Insurance
benefit_type: 1
name: Medical Insurance
pretax: true
posttax: false
imputed: false
healthcare: true
retirement: false
yearly_limit: false
category: Health
Company-Benefit-With-Employee-Benefits:
description: The representation of a company benefit.
type: object
x-examples:
Example:
description: Kaiser Permanente
version: 98jr3289h3298hr9329gf9egskt3kagri32qqgiqe3872
uuid: 54e37c27-43e6-4ae5-a5b2-e29895a133be
benefit_type: 1
active: true
deletable: true
supports_percentage_amounts: true
responsible_for_employer_taxes: false
responsible_for_employee_w2: false
properties:
description:
description: >-
The description of the company benefit.For example, a company may
offer multiple benefits with an ID of 1 (for Medical Insurance). The
description would show something more specific like “Kaiser
Permanente” or “Blue Cross/ Blue Shield”.
type: string
minLength: 1
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
uuid:
description: The UUID of the company benefit.
type: string
readOnly: true
benefit_type:
description: >-
The type of the benefit to which the company benefit belongs (same
as benefit_id).
type: number
readOnly: true
active:
description: >-
Whether this benefit is active for employee participation. Company
benefits may only be deactivated if no employees are actively
participating.
type: boolean
default: true
deletable:
description: >-
Whether this company benefit can be deleted. Deletable will be set
to true if the benefit has not been used in payroll, has no employee
benefits associated, and the benefit is not owned by Gusto or a
Partner
type: boolean
supports_percentage_amounts:
description: >-
Whether employee deductions and company contributions can be set as
percentages of payroll for an individual employee. This is
determined by the type of benefit and is not configurable by the
company.
type: boolean
readOnly: true
responsible_for_employer_taxes:
description: >-
Whether the employer is subject to pay employer taxes when an
employee is on leave. Only applicable to third party sick pay
benefits.
type: boolean
responsible_for_employee_w2:
description: >-
Whether the employer is subject to file W-2 forms for an employee on
leave. Only applicable to third party sick pay benefits.
type: boolean
employee_benefits:
type: array
items:
type: object
properties:
employee_uuid:
description: The UUID of the employee to which the benefit belongs.
type: string
company_benefit_uuid:
description: The UUID of the company benefit.
type: string
active:
description: Whether the employee benefit is active.
type: boolean
default: true
deduct_as_percentage:
description: >-
Whether the employee deduction amount should be treated as a
percentage to be deducted from each payroll.
type: boolean
default: false
employee_deduction:
description: >-
The amount to be deducted, per pay period, from the employee's
pay.
type: string
default: '0.00'
company_contribution:
description: The value of the company contribution
type: string
uuid:
type: string
contribution:
description: >-
An object representing the type and value of the company
contribution.
type: object
properties:
type:
description: >-
The company contribution scheme.
"amount": The company contributes a fixed amount per
payroll. If elective is true, the contribution is
matching, dollar-for-dollar.
"percentage": The company contributes a percentage of the
payroll amount per payroll period. If elective is true,
the contribution is matching, dollar-for-dollar.
"tiered": The company contribution varies according to the
size of the employee deduction.
type: string
value:
description: >-
For the `amount` and `percentage` contribution types, the
value of the corresponding amount or percentage.
For the `tiered` contribution type, an array of tiers.
oneOf:
- type: string
- type: object
properties:
tiers:
description: ''
type: array
items:
description: A single tier of a tiered matching scheme.
type: object
properties:
rate:
description: >-
The percentage of employee deduction within
this tier the company contribution will
match.
type: string
threshold:
description: >-
The percentage threshold at which this tier
ends (inclusive).
For example, a value of "5" means the
company contribution will match employee
deductions from the previous tier's
threshold up to and including 5% of payroll.
If this is the first tier, a value of "5"
means the company contribution will match
employee deductions from 0% up to and
including 5% of payroll.
type: string
threshold_delta:
description: >-
The step up difference between this tier's
threshold and the previous tier's threshold.
In the first tier, this is equivalent to
threshold.
type: string
Company-Benefit:
description: The representation of a company benefit.
type: object
x-examples:
Example:
description: Kaiser Permanente
version: 98jr3289h3298hr9329gf9egskt3kagri32qqgiqe3872
uuid: 54e37c27-43e6-4ae5-a5b2-e29895a133be
benefit_type: 1
active: true
deletable: true
supports_percentage_amounts: true
responsible_for_employer_taxes: false
responsible_for_employee_w2: false
properties:
description:
description: >-
The description of the company benefit.For example, a company may
offer multiple benefits with an ID of 1 (for Medical Insurance). The
description would show something more specific like “Kaiser
Permanente” or “Blue Cross/ Blue Shield”.
type: string
minLength: 1
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
uuid:
description: The UUID of the company benefit.
type: string
readOnly: true
benefit_type:
description: The type of the benefit to which the company benefit belongs.
type: number
readOnly: true
active:
description: >-
Whether this benefit is active for employee participation. Company
benefits may only be deactivated if no employees are actively
participating.
type: boolean
default: true
deletable:
description: >-
Whether this company benefit can be deleted. Deletable will be set
to true if the benefit has not been used in payroll, has no employee
benefits associated, and the benefit is not owned by Gusto or a
Partner
type: boolean
supports_percentage_amounts:
description: >-
Whether employee deductions and company contributions can be set as
percentages of payroll for an individual employee. This is
determined by the type of benefit and is not configurable by the
company.
type: boolean
readOnly: true
responsible_for_employer_taxes:
description: >-
Whether the employer is subject to pay employer taxes when an
employee is on leave. Only applicable to third party sick pay
benefits.
type: boolean
responsible_for_employee_w2:
description: >-
Whether the employer is subject to file W-2 forms for an employee on
leave. Only applicable to third party sick pay benefits.
type: boolean
Earning-Type:
description: ''
type: object
x-examples:
Example:
name: Cash Tips
uuid: f5618c94-ed7d-4366-b2c4-ff05e430064f
properties:
name:
description: The name of the earning type.
type: string
uuid:
description: The ID of the earning type.
type: string
readOnly: true
x-tags:
- Earning Types
Employee-Benefit:
title: ''
description: The representation of an employee benefit.
type: object
x-examples:
Example:
version: 09j3d29jqdpj92109j9j2d90dq
employee_uuid: 73274962-63ce-4e5c-b689-1df8d4df09f4
company_benefit_uuid: 54e37c27-43e6-4ae5-a5b2-e29895a133be
active: true
uuid: e91ca856-a915-4339-9b18-29f9cd66b031
employee_deduction: '100.00'
company_contribution: '100.00'
employee_deduction_annual_maximum: '200.00'
company_contribution_annual_maximum: '200.00'
limit_option: null
retirement_loan_identifier: null
deduct_as_percentage: false
contribute_as_percentage: false
catch_up: false
coverage_amount: null
deduction_reduces_taxable_income: null
coverage_salary_multiplier: '0.00'
contribution:
type: amount
value: '100.00'
elective: false
Tiered Example:
version: 09j3d29jqdpj92109j9j2d90dq
employee_uuid: 73274962-63ce-4e5c-b689-1df8d4df09f4
company_benefit_uuid: 54e37c27-43e6-4ae5-a5b2-e29895a133be
active: true
uuid: e91ca856-a915-4339-9b18-29f9cd66b031
employee_deduction: '100.00'
employee_deduction_annual_maximum: '200.00'
company_contribution_annual_maximum: '200.00'
limit_option: null
deduct_as_percentage: false
catch_up: false
coverage_amount: null
deduction_reduces_taxable_income: null
coverage_salary_multiplier: '0.00'
elective: true
contribution:
type: tiered
value:
tiers:
- rate: '100.0'
threshold: '2.0'
threshold_delta: '2.0'
- rate: '50.0'
threshold: '5.0'
threshold_delta: '3.0'
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
employee_uuid:
description: The UUID of the employee to which the benefit belongs.
type: string
readOnly: true
company_benefit_uuid:
description: The UUID of the company benefit.
type: string
readOnly: true
active:
description: Whether the employee benefit is active.
type: boolean
default: true
uuid:
description: The UUID of the employee benefit.
type: string
readOnly: true
employee_deduction:
description: The amount to be deducted, per pay period, from the employee's pay.
type: string
default: '0.00'
deduct_as_percentage:
description: >-
Whether the employee deduction amount should be treated as a
percentage to be deducted from each payroll.
type: boolean
default: false
employee_deduction_annual_maximum:
description: >-
The maximum employee deduction amount per year. A null value
signifies no limit.
type: string
nullable: true
contribution:
description: >-
An object representing the type and value of the company
contribution.
type: object
properties:
type:
description: >-
The company contribution scheme.
"amount": The company contributes a fixed amount per payroll. If
elective is true, the contribution is matching,
dollar-for-dollar.
"percentage": The company contributes a percentage of the
payroll amount per payroll period. If elective is true, the
contribution is matching, dollar-for-dollar.
"tiered": The company contribution varies according to the size
of the employee deduction.
type: string
value:
description: >-
For the `amount` and `percentage` contribution types, the value
of the corresponding amount or percentage.
For the `tiered` contribution type, an array of tiers.
oneOf:
- type: string
- type: object
properties:
tiers:
description: ''
type: array
items:
description: A single tier of a tiered matching scheme.
type: object
properties:
rate:
description: >-
The percentage of employee deduction within this
tier the company contribution will match.
type: string
threshold:
description: >-
The percentage threshold at which this tier ends
(inclusive).
For example, a value of "5" means the company
contribution will match employee deductions from
the previous tier's threshold up to and including
5% of payroll.
If this is the first tier, a value of "5" means
the company contribution will match employee
deductions from 0% up to and including 5% of
payroll.
type: string
threshold_delta:
description: >-
The step up difference between this tier's
threshold and the previous tier's threshold. In
the first tier, this is equivalent to threshold.
type: string
elective:
description: >-
Whether the company contribution is elective (aka matching). For
"tiered" contribution types, this is always true.
type: boolean
default: false
company_contribution_annual_maximum:
description: >-
The maximum company contribution amount per year. A null value
signifies no limit.
type: string
nullable: true
limit_option:
description: >-
Some benefits require additional information to determine their
limit. For example, for an HSA benefit, the limit option should be
either "Family" or "Individual". For a Dependent Care FSA benefit,
the limit option should be either "Joint Filing or Single" or
"Married and Filing Separately".
type: string
nullable: true
catch_up:
description: >-
Whether the employee should use a benefit’s "catch up" rate. Only
Roth 401k and 401k benefits use this value for employees over 50.
type: boolean
default: false
retirement_loan_identifier:
description: Identifier for a 401(k) loan assigned by the 401(k) provider
type: string
coverage_amount:
description: >-
The amount that the employee is insured for. Note: company
contribution cannot be present if coverage amount is set.
type: string
nullable: true
deduction_reduces_taxable_income:
description: >-
Whether the employee deduction reduces taxable income or not. Only
valid for Group Term Life benefits. Note: when the value is not
"unset", coverage amount and coverage salary multiplier are ignored.
type: string
default: unset
enum:
- unset
- reduces_taxable_income
- does_not_reduce_taxable_income
- null
nullable: true
coverage_salary_multiplier:
description: >-
The coverage amount as a multiple of the employee’s salary. Only
applicable for Group Term Life benefits. Note: cannot be set if
coverage amount is also set.
type: string
default: '0.00'
company_contribution:
description: >-
The amount to be paid, per pay period, by the company. This field
will not appear for tiered contribution types.
type: string
default: '0.00'
deprecated: true
contribute_as_percentage:
description: >-
Whether the company_contribution value should be treated as a
percentage to be added to each payroll. This field will not appear
for tiered contribution types.
type: boolean
default: false
deprecated: true
Employee-Pay-Stub:
description: The representation of an employee pay stub information.
type: object
properties:
uuid:
description: The UUID of the employee pay stub.
type: string
readOnly: true
check_date:
description: The check date of the pay stub.
type: string
readOnly: true
gross_pay:
description: The gross pay amount for the pay stub.
type: string
readOnly: true
net_pay:
description: The net pay amount for the pay stub.
type: string
readOnly: true
payroll_uuid:
description: A unique identifier of the payroll to which the pay stub belongs.
type: string
readOnly: true
check_amount:
description: The check amount for the pay stub.
type: string
readOnly: true
x-tags:
- Payrolls
Pay-Period:
description: The representation of a pay period.
type: object
properties:
start_date:
description: The start date, inclusive, of the pay period.
type: string
readOnly: true
end_date:
description: The end date, inclusive, of the pay period.
type: string
minLength: 1
pay_schedule_uuid:
description: >-
A unique identifier of the pay schedule to which the pay period
belongs.
type: string
readOnly: true
payroll:
description: Information about the payroll for the pay period.
type: object
properties:
payroll_uuid:
description: The UUID of the payroll for this pay period.
type: string
readOnly: true
check_date:
description: >-
The date on which employees will be paid for the payroll if the
payroll is submitted on time.
type: string
readOnly: true
processed:
description: >-
Whether or not the payroll has been successfully processed. Note
that processed payrolls cannot be updated. Additionally, a
payroll is not guaranteed to be processed just because the
payroll deadline has passed. Late payrolls are not uncommon.
Conversely, users may choose to run payroll before the payroll
deadline.
type: boolean
readOnly: true
payroll_deadline:
description: >-
The date by which payroll should be run for employees to be paid
on time. Payroll data, such as time and attendance data, should
be submitted on or before this date.
type: string
format: date-time
readOnly: true
payroll_type:
description: Whether it is regular pay period or transition pay period.
type: string
enum:
- regular
- transition
readOnly: true
readOnly: true
x-tags:
- Payrolls
Created-At-Type:
description: Datetime for when the resource was created.
type: string
format: date-time
readOnly: true
Off-Cycle-Reason-Type:
description: The off-cycle reason. Only included for off-cycle payrolls.
type: string
readOnly: true
nullable: true
enum:
- Benefit reversal
- Bonus
- Correction
- Dismissed employee
- Hired employee
- Wage correction
- Tax reconciliation
- Reversal
- Disability insurance distribution
- Transition from old pay schedule
Payroll-Employee-Compensations-Type:
type: array
uniqueItems: false
items:
type: object
properties:
version:
description: >-
The current version of this employee compensation. This field is
only available for prepared payrolls. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency)
for information on how to use this field.
type: string
employee_uuid:
description: The UUID of the employee.
type: string
readOnly: true
excluded:
description: >-
This employee will be excluded from payroll calculation and will
not be paid for the payroll. Cancelling a payroll would reset all
employees' excluded back to false.
type: boolean
readOnly: true
gross_pay:
description: >-
The employee's gross pay, equal to regular wages + cash tips +
payroll tips + any other additional earnings, excluding imputed
income. This value is only available for processed payrolls.
type: string
nullable: true
readOnly: true
net_pay:
description: >-
The employee's net pay, equal to gross_pay - employee taxes -
employee deductions or garnishments - cash tips. This value is
only available for processed payrolls.
type: string
nullable: true
readOnly: true
check_amount:
description: >-
The employee's check amount, equal to net_pay + reimbursements.
This value is only available for processed payrolls.
type: string
nullable: true
readOnly: true
payment_method:
description: The employee's compensation payment method.
type: string
enum:
- Check
- Direct Deposit
nullable: true
memo:
description: >-
Custom text that will be printed as a personal note to the
employee on a paystub.
type: string
nullable: true
readOnly: true
fixed_compensations:
description: >-
An array of fixed compensations for the employee. Fixed
compensations include tips, bonuses, and one time reimbursements.
If this payroll has been processed, only fixed compensations with
a value greater than 0.00 are returned. For an unprocessed
payroll, all active fixed compensations are returned.
type: array
uniqueItems: false
items:
type: object
properties:
name:
description: >-
The name of the compensation. This also serves as the
unique, immutable identifier for this compensation.
type: string
amount:
description: The amount of the compensation for the pay period.
type: string
job_uuid:
description: The UUID of the job for the compensation.
type: string
readOnly: true
hourly_compensations:
description: >-
An array of hourly compensations for the employee. Hourly
compensations include regular, overtime, and double overtime
hours. If this payroll has been processed, only hourly
compensations with a value greater than 0.00 are returned. For an
unprocessed payroll, all active hourly compensations are returned.
type: array
uniqueItems: false
items:
type: object
properties:
name:
description: >-
The name of the compensation. This also serves as the
unique, immutable identifier for this compensation.
type: string
hours:
description: The number of hours to be compensated for this pay period.
type: string
amount:
description: >-
The amount of the compensation. This field is only available
after the payroll is calculated and cannot be used for
updating hourly compensations.
type: string
job_uuid:
description: The UUID of the job for the compensation.
type: string
readOnly: true
compensation_multiplier:
description: >-
The amount multiplied by the base rate to calculate total
compensation per hour worked.
type: number
readOnly: true
paid_time_off:
description: >-
An array of all paid time off the employee is eligible for this
pay period.
type: array
uniqueItems: false
items:
type: object
properties:
name:
description: >-
The name of the PTO. This also serves as the unique,
immutable identifier for the PTO.
type: string
hours:
description: The hours of this PTO taken during the pay period.
type: string
final_payout_unused_hours_input:
description: >-
The outstanding hours paid upon termination. This field is
only applicable for termination payrolls.
type: string
benefits:
description: >-
An array of employee benefits for the pay period. Benefits are
only included for processed payroll when the include parameter is
present.
type: array
uniqueItems: false
items:
type: object
properties:
name:
type: string
readOnly: true
employee_deduction:
type: string
readOnly: true
company_contribution:
type: string
readOnly: true
imputed:
type: boolean
readOnly: true
readOnly: true
deductions:
description: >-
An array of employee deductions for the pay period. Deductions are
only included for processed payroll when the include parameter is
present.
type: array
uniqueItems: false
items:
type: object
properties:
name:
type: string
readOnly: true
amount:
type: string
readOnly: true
readOnly: true
readOnly: true
taxes:
description: >-
An array of employer and employee taxes for the pay period. Only
included for processed or calculated payrolls when `taxes` is
present in the `include` parameter.
type: array
uniqueItems: false
items:
type: object
properties:
name:
type: string
minLength: 1
employer:
type: boolean
amount:
type: string
minLength: 1
required:
- name
- employer
- amount
readOnly: true
readOnly: true
Payroll-Totals-Type:
description: The subtotals for the payroll.
type: object
properties:
company_debit:
description: The total company debit for the payroll.
type: string
readOnly: true
net_pay_debit:
description: The total company net pay for the payroll.
type: string
minLength: 1
tax_debit:
description: The total tax debit for the payroll.
type: string
readOnly: true
reimbursement_debit:
description: The total reimbursement debit for the payroll.
type: string
readOnly: true
child_support_debit:
description: The total child support debit for the payroll.
type: string
readOnly: true
reimbursements:
description: The total reimbursements for the payroll.
type: string
readOnly: true
net_pay:
description: The net pay amount for the payroll.
type: string
readOnly: true
gross_pay:
description: The gross pay amount for the payroll.
type: string
readOnly: true
employee_bonuses:
description: The total employee bonuses amount for the payroll.
type: string
readOnly: true
employee_commissions:
description: The total employee commissions amount for the payroll.
type: string
readOnly: true
employee_cash_tips:
description: The total employee cash tips amount for the payroll.
type: string
readOnly: true
employee_paycheck_tips:
description: The total employee paycheck tips amount for the payroll.
type: string
readOnly: true
additional_earnings:
description: The total additional earnings amount for the payroll.
type: string
readOnly: true
owners_draw:
description: The total owner's draw for the payroll.
type: string
readOnly: true
check_amount:
description: The total check amount for the payroll.
type: string
readOnly: true
employer_taxes:
description: The total amount of employer paid taxes for the payroll.
type: string
readOnly: true
employee_taxes:
description: The total amount of employee paid taxes for the payroll.
type: string
readOnly: true
benefits:
description: The total amount of company contributed benefits for the payroll.
type: string
readOnly: true
employee_benefits_deductions:
description: The total amount of employee deducted benefits for the payroll.
type: string
readOnly: true
deferred_payroll_taxes:
description: >-
The total amount of payroll taxes deferred for the payroll, such as
allowed by the CARES act.
type: string
readOnly: true
other_deductions:
description: The total amount of deductions for the payroll.
type: string
readOnly: true
Payroll-Company-Taxes-Type:
description: >-
An array of taxes applicable to this payroll in addition to taxes
included in `employee_compensations`. Only included for processed or
calculated payrolls when `taxes` is present in the `include` parameter.
type: array
uniqueItems: false
items:
type: object
properties:
name:
description: The tax name
type: string
employer:
description: Whether this tax is an employer or employee tax
type: boolean
amount:
description: The amount of this tax for the payroll
type: string
Payroll-Payment-Speed-Changed-Type:
description: >-
Only applicable when a payroll is moved to four day processing instead
of fast ach.
type: object
properties:
original_check_date:
description: Original check date when fast ach applies.
type: string
readOnly: true
current_check_date:
description: Current check date.
type: string
readOnly: true
original_debit_date:
description: Original debit date when fast ach applies.
type: number
readOnly: true
current_debit_date:
description: Current debit date.
type: string
readOnly: true
reason:
description: The reason why the payroll is moved to four day.
type: string
readOnly: true
Payroll-Payroll-Status-Meta-Type:
description: Information about the payroll's status and expected dates
type: object
properties:
cancellable:
description: true if the payroll may be cancelled
type: boolean
readOnly: true
expected_check_date:
description: The date an employee will be paid if the payroll is submitted now
type: string
readOnly: true
initial_check_date:
description: The normal check date for the associated pay period
type: string
readOnly: true
expected_debit_time:
description: >-
The time the employer's account will be debited if the payroll is
submitted now
type: string
readOnly: true
payroll_late:
description: expected_check_date > initial_check_date
type: boolean
readOnly: true
initial_debit_cutoff_time:
description: >-
Payroll must be submitted at or before this time to avoid late
payroll
type: string
readOnly: true
Payroll-Pay-Period-Type:
type: object
properties:
start_date:
description: The start date, inclusive, of the pay period.
type: string
readOnly: true
end_date:
description: The start date, inclusive, of the pay period.
type: string
readOnly: true
pay_schedule_uuid:
description: The UUID of the pay schedule for the payroll.
type: string
readOnly: true
nullable: true
readOnly: true
Payroll-Withholding-Pay-Period-Type:
description: >-
The payment schedule tax rate the payroll is based on. Only included for
off-cycle payrolls.
type: string
readOnly: true
nullable: false
enum:
- Every week
- Every other week
- Twice per month
- Monthly
- Quarterly
- Semiannually
- Annually
Payroll-Deadline-Type:
description: >-
A timestamp that is the deadline for the payroll to be run in order for
employees to be paid on time.
type: string
format: date-time
readOnly: true
Payroll-Check-Date-Type:
description: The date on which employees will be paid for the payroll.
type: string
readOnly: true
Payroll-Processed-Type:
description: >-
Whether or not the payroll has been successfully processed. Note that
processed payrolls cannot be updated. Additionally, a payroll is not
guaranteed to be processed just because the payroll deadline has passed.
Late payrolls are not uncommon. Conversely, users may choose to run
payroll before the payroll deadline.
type: boolean
readOnly: true
Payroll-Processed-Date-Type:
description: >-
The date at which the payroll was processed. Null if the payroll isn't
processed yet.
type: string
readOnly: true
Payroll-Calculated-At-Type:
description: >-
A timestamp of the last valid payroll calculation. Null is there isn't a
valid calculation.
type: string
readOnly: true
Payroll-Payroll-Uuid-Type:
description: The UUID of the payroll.
type: string
readOnly: true
Payroll-Company-Uuid-Type:
description: The UUID of the company for the payroll.
type: string
readOnly: true
Payroll-Off-Cycle-Type:
description: Indicates whether the payroll is an off-cycle payroll
type: boolean
readOnly: true
Payroll-External-Type:
description: Indicates whether the payroll is an external payroll
type: boolean
readOnly: true
Payroll-Final-Termination-Payroll-Type:
description: >-
Indicates whether the payroll is the final payroll for a terminated
employee. Only included for off-cycle payrolls.
type: boolean
readOnly: true
Payroll-Skip-Regular-Deductions-Type:
description: >-
Block regular deductions and contributions for this payroll. Only
included for off-cycle payrolls.
type: boolean
readOnly: true
nullable: false
Payroll-Fixed-Withholding-Rate-Type:
description: >-
Enable taxes to be withheld at the IRS's required rate of 22% for
federal income taxes. State income taxes will be taxed at the state's
supplemental tax rate. Otherwise, we'll sum the entirety of the
employee's wages and withhold taxes on the entire amount at the rate for
regular wages. Only included for off-cycle payrolls.
type: boolean
readOnly: true
nullable: false
Payroll-Fixed-Compensation-Types-Type:
type: array
items:
type: object
readOnly: true
properties:
name:
description: The name of an available type of fixed compensation.
type: string
readOnly: true
Payroll:
description: ''
type: object
x-tags:
- Payrolls
properties:
payroll_deadline:
$ref: '#/components/schemas/Payroll-Deadline-Type'
check_date:
$ref: '#/components/schemas/Payroll-Check-Date-Type'
processed:
$ref: '#/components/schemas/Payroll-Processed-Type'
processed_date:
$ref: '#/components/schemas/Payroll-Processed-Date-Type'
calculated_at:
$ref: '#/components/schemas/Payroll-Calculated-At-Type'
payroll_uuid:
$ref: '#/components/schemas/Payroll-Payroll-Uuid-Type'
company_uuid:
$ref: '#/components/schemas/Payroll-Company-Uuid-Type'
off_cycle:
$ref: '#/components/schemas/Payroll-Off-Cycle-Type'
off_cycle_reason:
$ref: '#/components/schemas/Off-Cycle-Reason-Type'
external:
$ref: '#/components/schemas/Payroll-External-Type'
final_termination_payroll:
$ref: '#/components/schemas/Payroll-Final-Termination-Payroll-Type'
withholding_pay_period:
$ref: '#/components/schemas/Payroll-Withholding-Pay-Period-Type'
skip_regular_deductions:
$ref: '#/components/schemas/Payroll-Skip-Regular-Deductions-Type'
fixed_withholding_rate:
$ref: '#/components/schemas/Payroll-Fixed-Withholding-Rate-Type'
pay_period:
$ref: '#/components/schemas/Payroll-Pay-Period-Type'
payroll_status_meta:
$ref: '#/components/schemas/Payroll-Payroll-Status-Meta-Type'
totals:
$ref: '#/components/schemas/Payroll-Totals-Type'
employee_compensations:
$ref: '#/components/schemas/Payroll-Employee-Compensations-Type'
company_taxes:
$ref: '#/components/schemas/Payroll-Company-Taxes-Type'
payment_speed_changed:
$ref: '#/components/schemas/Payroll-Payment-Speed-Changed-Type'
created_at:
$ref: '#/components/schemas/Created-At-Type'
Payroll-Prepared:
description: ''
type: object
x-tags:
- Payrolls
properties:
payroll_deadline:
$ref: '#/components/schemas/Payroll-Deadline-Type'
check_date:
$ref: '#/components/schemas/Payroll-Check-Date-Type'
processed:
$ref: '#/components/schemas/Payroll-Processed-Type'
processed_date:
$ref: '#/components/schemas/Payroll-Processed-Date-Type'
calculated_at:
$ref: '#/components/schemas/Payroll-Calculated-At-Type'
payroll_uuid:
$ref: '#/components/schemas/Payroll-Payroll-Uuid-Type'
company_uuid:
$ref: '#/components/schemas/Payroll-Company-Uuid-Type'
off_cycle:
$ref: '#/components/schemas/Payroll-Off-Cycle-Type'
off_cycle_reason:
$ref: '#/components/schemas/Off-Cycle-Reason-Type'
external:
$ref: '#/components/schemas/Payroll-External-Type'
final_termination_payroll:
$ref: '#/components/schemas/Payroll-Final-Termination-Payroll-Type'
withholding_pay_period:
$ref: '#/components/schemas/Payroll-Withholding-Pay-Period-Type'
skip_regular_deductions:
$ref: '#/components/schemas/Payroll-Skip-Regular-Deductions-Type'
fixed_withholding_rate:
$ref: '#/components/schemas/Payroll-Fixed-Withholding-Rate-Type'
pay_period:
$ref: '#/components/schemas/Payroll-Pay-Period-Type'
payroll_status_meta:
$ref: '#/components/schemas/Payroll-Payroll-Status-Meta-Type'
employee_compensations:
$ref: '#/components/schemas/Payroll-Employee-Compensations-Type'
payment_speed_changed:
$ref: '#/components/schemas/Payroll-Payment-Speed-Changed-Type'
created_at:
$ref: '#/components/schemas/Created-At-Type'
fixed_compensation_types:
$ref: '#/components/schemas/Payroll-Fixed-Compensation-Types-Type'
Payroll-Minimal:
description: ''
type: object
x-tags:
- Payrolls
properties:
payroll_deadline:
$ref: '#/components/schemas/Payroll-Deadline-Type'
check_date:
$ref: '#/components/schemas/Payroll-Check-Date-Type'
processed:
$ref: '#/components/schemas/Payroll-Processed-Type'
processed_date:
$ref: '#/components/schemas/Payroll-Processed-Date-Type'
calculated_at:
$ref: '#/components/schemas/Payroll-Calculated-At-Type'
payroll_uuid:
$ref: '#/components/schemas/Payroll-Payroll-Uuid-Type'
company_uuid:
$ref: '#/components/schemas/Payroll-Company-Uuid-Type'
off_cycle:
$ref: '#/components/schemas/Payroll-Off-Cycle-Type'
off_cycle_reason:
$ref: '#/components/schemas/Off-Cycle-Reason-Type'
external:
$ref: '#/components/schemas/Payroll-External-Type'
final_termination_payroll:
$ref: '#/components/schemas/Payroll-Final-Termination-Payroll-Type'
withholding_pay_period:
$ref: '#/components/schemas/Payroll-Withholding-Pay-Period-Type'
skip_regular_deductions:
$ref: '#/components/schemas/Payroll-Skip-Regular-Deductions-Type'
fixed_withholding_rate:
$ref: '#/components/schemas/Payroll-Fixed-Withholding-Rate-Type'
pay_period:
$ref: '#/components/schemas/Payroll-Pay-Period-Type'
payroll_status_meta:
$ref: '#/components/schemas/Payroll-Payroll-Status-Meta-Type'
totals:
$ref: '#/components/schemas/Payroll-Totals-Type'
payment_speed_changed:
$ref: '#/components/schemas/Payroll-Payment-Speed-Changed-Type'
created_at:
$ref: '#/components/schemas/Created-At-Type'
Payroll-Blocker:
type: object
properties:
key:
description: The unique identifier of the reason
type: string
message:
description: User-friendly message describing the payroll blocker.
type: string
Payroll-Check:
type: object
properties:
payroll_uuid:
description: A unique identifier of the payroll.
type: string
printing_format:
description: The format the checks will be printed.
type: string
starting_check_number:
description: The starting check number for the checks being printed.
type: string
request_uuid:
description: A unique identifier of the Generated Document request
type: string
status:
description: Current status of the Generated Document
type: string
x-examples:
example-1:
payroll_uuid: a83d0bd8-7d20-43b9-834c-6d514ef6cb20
printing_format: top
starting_check_number: '10'
request_uuid: p83d0ca8-7d41-42a9-834y-7d218ef6cb20
status: pending
Generated-Document:
type: object
properties:
request_uuid:
description: A unique identifier of the Generated Document request
type: string
status:
description: Current status of the Generated Document
type: string
document_urls:
description: The array of urls to access the documents.
type: array
items:
type: string
x-examples:
example-1:
status: succeeded
document_urls:
- https://document.url.com
request_uuid: p83d0ca8-7d41-42a9-834y-7d218ef6cb20
Payroll-Receipt:
type: object
properties:
payroll_uuid:
description: A unique identifier of the payroll receipt.
type: string
company_uuid:
description: A unique identifier of the company for the payroll.
type: string
name_of_sender:
description: The name of the company by whom the payroll was paid
type: string
name_of_recipient:
description: Always the fixed string "Payroll Recipients"
type: string
recipient_notice:
description: >-
Always the fixed string "Payroll recipients include the employees
listed below plus the tax agencies for the taxes listed below."
type: string
debit_date:
description: The debit or funding date for the payroll
type: string
license:
description: >-
Always the fixed string "ZenPayroll, Inc., dba Gusto is a licensed
money transmitter. For more about Gusto’s licenses and your
state-specific rights to request information, submit complaints,
dispute errors, or cancel transactions, visit our license page."
type: string
license_uri:
description: >-
URL for the license information for the licensed payroll processor.
Always the fixed string "https://gusto.com/about/licenses"
type: string
right_to_refund:
description: ''
type: string
liability_of_licensee:
description: ''
type: string
totals:
description: The subtotals for the payroll.
type: object
properties:
company_debit:
description: The total company debit for the payroll.
type: string
net_pay_debit:
description: The total company net pay for the payroll.
type: string
child_support_debit:
description: The total child support debit for the payroll.
type: string
reimbursement_debit:
description: The total reimbursements for the payroll.
type: string
tax_debit:
description: The total tax debit for the payroll.
type: string
taxes:
description: An array of totaled employer and employee taxes for the pay period.
type: array
items:
type: object
properties:
name:
description: The amount paid for this tax.
type: string
amount:
description: >-
The total amount paid by both employer and employee for this
tax.
type: string
employee_compensations:
description: An array of employee compensations and withholdings for this payroll
type: array
items:
type: object
properties:
employee_uuid:
description: The UUID of the employee.
type: string
employee_first_name:
description: The first name of the employee.
type: string
employee_last_name:
description: The last name of the employee.
type: string
payment_method:
description: >-
The employee's compensation payment method.\n\n`Check` `Direct
Deposit`
type: string
net_pay:
description: >-
The employee's net pay. Net pay paid by check is available for
reference but is not included in the
`["totals"]["net_pay_debit"]` amount.
type: string
total_tax:
description: The total of employer and employee taxes for the pay period.
type: string
total_garnishments:
description: The total garnishments for the pay period.
type: string
child_support_garnishment:
description: The total child support garnishment for the pay period.
type: string
total_reimbursement:
description: The total reimbursement for the pay period.
type: string
licensee:
description: The licensed payroll processor
type: object
properties:
name:
description: Always the fixed string "Gusto, Zenpayroll Inc."
type: string
address:
description: Always the fixed string "525 20th St"
type: string
city:
description: Always the fixed string "San Francisco"
type: string
state:
description: Always the fixed string "CA"
type: string
postal_code:
description: Always the fixed string "94107"
type: string
phone_number:
description: Always the fixed string "4157778888"
type: string
x-examples:
example-1:
totals:
company_debit: '1080.47'
net_pay_debit: '748.34'
child_support_debit: '100.0'
reimbursement_debit: '50.0'
tax: '182.13'
taxes:
- name: Federal Income Tax
amount: '30.36'
- name: Social Security
amount: '104.54'
- name: Medicare
amount: '24.46'
- name: Additional Medicare
amount: '0.0'
- name: TX SUTA
amount: '22.77'
- name: FUTA
amount: '0.0'
employee_compensations:
- employee_uuid: f83d0bd8-7e20-43b9-834c-6d514ef6cb47
employee_first_name: Patricia
employee_last_name: Hamill
payment_method: Direct Deposit
net_pay: '748.34'
total_tax: '182.13'
total_garnishments: '0.0'
child_support_garnishment: '100.0'
total_reimbursement: '50.0'
licensee:
name: Gusto, Zenpayroll Inc.
address: 525 20th St
city: San Francisco
state: CA
postal_code: '94107'
phone_number: '4157778888'
payroll_uuid: afccb970-357e-4013-81f5-85dafc74f9b6
company_uuid: c827aa0d-3928-4d5a-ab1f-400641a7d2b8
name_of_sender: Torp and Sons and Sons
name_of_recipient: Payroll Recipients
recipient_notice: >-
Payroll recipients include the employees listed below plus the tax
agencies for the taxes listed below.
debit_date: '2022-06-02'
license: >-
ZenPayroll, Inc., dba Gusto is a licensed money transmitter. For
more about Gusto’s licenses and your state-specific rights to
request information, submit complaints, dispute errors, or cancel
transactions, visit our license page.
license_uri: https://gusto.com/about/licenses
right_to_refund: https://gusto.com/about/licenses
liability_of_licensee: https://gusto.com/about/licenses
Payroll-Reversal:
type: object
properties:
reversed_payroll_uuid:
description: The UUID for the payroll run being reversed.
type: string
reversal_payroll_uuid:
description: The UUID of the payroll where the reversal was applied.
type: string
reason:
description: A reason provided by the admin who created the reversal.
type: string
approved_at:
description: Timestamp of when the reversal was approved.
type: string
nullable: true
category:
description: Category chosen by the admin who requested the reversal.
type: string
items:
type: integer
reversed_employee_uuids:
description: Array of affected employee UUIDs.
type: array
items:
type: string
Gross-Up-Pay:
type: object
properties:
gross_up:
description: Gross up earnings.
type: string
Contractor-Payment-Receipt:
type: object
x-examples:
example-1:
contractor_payment_uuid: afccb970-357e-4013-81f5-85dafc74f9b6
company_uuid: c827aa0d-3928-4d5a-ab1f-400641a7d2b8
name_of_sender: Torp and Sons and Sons
name_of_recipient: Patricia Hamill
debit_date: '2022-06-02'
totals:
company_debit: '748.34'
contractor_payments:
- contractor_uuid: f83d0bd8-7e20-43b9-834c-6d514ef6cb47
contractor_first_name: Patricia
contractor_last_name: Hamill
contractor_business_name: ''
contractor_type: Individual
payment_method: Direct Deposit
wage: '448.34'
bonus: '248.00'
reimbursement: '100.00'
licensee:
name: Gusto, Zenpayroll Inc.
address: 525 20th St
city: San Francisco
state: CA
postal_code: '94107'
phone_number: '4157778888'
license: >-
ZenPayroll, Inc., dba Gusto is a licensed money transmitter. For
more about Gusto’s licenses and your state-specific rights to
request information, submit complaints, dispute errors, or cancel
transactions, visit our license page.
license_uri: https://gusto.com/about/licenses
right_to_refund: https://gusto.com/about/licenses
liability_of_licensee: https://gusto.com/about/licenses
properties:
contractor_payment_uuid:
description: A unique identifier of the contractor payment receipt.
type: string
company_uuid:
description: A unique identifier of the company making the contractor payment.
type: string
name_of_sender:
description: The name of the company making the contractor payment.
type: string
name_of_recipient:
description: The individual or company name of the contractor receiving payment.
type: string
debit_date:
description: The debit date for the contractor payment.
type: string
format: date
example: '2022-05-30'
license:
description: >-
Always the fixed string "ZenPayroll, Inc., dba Gusto is a licensed
money transmitter. For more about Gusto’s licenses and your
state-specific rights to request information, submit complaints,
dispute errors, or cancel transactions, visit our license page."
type: string
license_uri:
description: >-
URL for the license information for the licensed payroll processor.
Always the fixed string "https://gusto.com/about/licenses"
type: string
right_to_refund:
description: >-
URL for information related to right to refund. Always the fixed
string "https://gusto.com/about/licenses"
type: string
liability_of_licensee:
description: >-
URL for information related to right to liability of licensee.
Always the fixed string "https://gusto.com/about/licenses"
type: string
totals:
description: The subtotals for the contractor payment.
type: object
properties:
company_debit:
description: The total company debit for the contractor payment.
type: string
contractor_payments:
description: An array of contractor payments for this contractor payment.
type: array
items:
type: object
properties:
contractor_uuid:
description: The UUID of the contractor.
type: string
contractor_first_name:
description: >-
The first name of the contractor. Applies when
`contractor_type` is `Individual`.
type: string
contractor_last_name:
description: >-
The last name of the contractor. Applies when
`contractor_type` is `Individual`.
type: string
contractor_business_name:
description: >-
The business name of the employee. Applies when
`contractor_type` is `Business`.
type: string
contractor_type:
description: |-
The type of contractor.
`Individual` `Business`
type: string
payment_method:
description: >-
The payment method.
`Direct Deposit` `Check` `Historical Payment` `Correction
Payment`
type: string
wage:
description: The fixed wage of the payment, regardless of hours worked.
type: string
bonus:
description: The bonus amount in the payment.
type: string
reimbursement:
description: The reimbursement amount in the payment.
type: string
licensee:
description: The licensed payroll processor
type: object
properties:
name:
description: Always the fixed string "Gusto, Zenpayroll Inc."
type: string
address:
description: Always the fixed string "525 20th St"
type: string
city:
description: Always the fixed string "San Francisco"
type: string
state:
description: Always the fixed string "CA"
type: string
postal_code:
description: Always the fixed string "94107"
type: string
phone_number:
description: Always the fixed string "4157778888"
type: string
Custom-Field-Type:
description: Input type for the custom field.
type: string
enum:
- text
- currency
- number
- date
- radio
x-tags:
- Custom Fields
Employee-Custom-Field:
description: A custom field of an employee
type: object
x-examples:
Employee Level:
description: Employee Level
id: ae4e2cd5-e9b6-40f9-88a1-415a02365dd0
company_custom_field_id: da84500d-d05c-4e4f-bcf2-43152ca33278
name: employee_level
value: '2'
x-tags:
- Custom Fields
properties:
description:
type: string
id:
type: string
company_custom_field_id:
description: >-
This is the id of the response object from when you get the company
custom fields
type: string
name:
type: string
type:
$ref: '#/components/schemas/Custom-Field-Type'
value:
type: string
selection_options:
description: An array of options for fields of type radio. Otherwise, null.
type: array
nullable: true
items:
type: string
required:
- id
- company_custom_field_id
- name
- type
- value
Company-Custom-Field:
description: A custom field on a company
type: object
x-tags:
- Custom Fields
properties:
description:
description: Description of the company custom field
type: string
uuid:
description: UUID of the company custom field
type: string
name:
description: Name of the company custom field
type: string
type:
$ref: '#/components/schemas/Custom-Field-Type'
selection_options:
description: An array of options for fields of type radio. Otherwise, null.
type: array
nullable: true
items:
type: string
required:
- uuid
- name
- type
Rehire:
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer)
for information on how to use this field.
type: string
effective_date:
description: The day when the employee returns to work.
type: string
file_new_hire_report:
description: >-
The boolean flag indicating whether Gusto will file a new hire
report for the employee.
type: boolean
work_location_uuid:
description: The uuid of the employee's work location.
type: string
employment_status:
description: >-
The employee's employment status. Supplying an invalid option will
set the employment_status to *not_set*.
type: string
enum:
- part_time
- full_time
- part_time_eligible
- variable
- seasonal
- not_set
two_percent_shareholder:
description: >-
Whether the employee is a two percent shareholder of the company.
This field only applies to companies with an S-Corp entity type.
type: boolean
employee_uuid:
description: The UUID of the employee.
type: string
readOnly: true
active:
description: Whether the employee's rehire has gone into effect.
type: boolean
readOnly: true
x-examples:
example-1:
version: 2e930d43acbdb241f8f14a2d531fa417
employee_uuid: 8c290660-b6c9-4ad7-9f6e-ea146aaf79e8
active: false
effective_date: '2024-06-30'
employment_status: seasonal
file_new_hire_report: false
work_location_uuid: 8cb87e2e-5b30-4c13-a4f4-bfffcbed1188
two_percent_shareholder: false
Signatory:
title: Signatory
description: The representation of a company's signatory
type: object
x-tags:
- Signatories
properties:
title:
type: string
nullable: true
version:
description: >-
The current version of the signatory. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
uuid:
type: string
first_name:
type: string
nullable: true
last_name:
type: string
nullable: true
phone:
type: string
nullable: true
email:
type: string
birthday:
type: string
nullable: true
is_admin:
description: >-
Whether or not the signatory is also the payroll admin of the
company.
type: boolean
has_ssn:
description: Indicates whether the signatory has an SSN in Gusto.
type: boolean
identity_verification_status:
description: >-
| | |
|---|---|
|__Status__| __Description__ |
| Pass | Signatory can sign all forms |
| Fail | Signatory cannot sign forms |
| Skipped | Signatory cannot sign Form 8655 until the form is
manually uploaded as wet-signed |
| null | Identity verification process has not been completed |
type: string
enum:
- Pass
- Fail
- Skipped
nullable: true
home_address:
type: object
nullable: true
properties:
street_1:
type: string
street_2:
type: string
city:
type: string
state:
type: string
zip:
type: string
country:
type: string
default: USA
Flow:
title: Flow
description: The representation of a flow in Gusto white-label UI.
type: object
x-examples:
Example:
url: >-
https://flows.gusto-demo.com/flows/lO2BHHAMCScPVV9G5WEURW0Im_nP9mGYloQgjUWbenQ
expires_at: '2021-12-28 04:25:48'
x-tags:
- Flows
properties:
url:
type: string
expires_at:
type: string
Unprocessed-Termination-Pay-Period:
description: The representation of an unprocessed termination pay period.
type: object
properties:
start_date:
description: The start date of the pay period.
type: string
readOnly: true
end_date:
description: The end date of the pay period.
type: string
check_date:
description: The check date of the pay period.
type: string
readOnly: true
debit_date:
description: The debit date of the pay period.
type: string
employee_name:
description: The full name of the employee.
type: string
employee_uuid:
description: A unique identifier of the employee.
type: string
pay_schedule_uuid:
description: >-
A unique identifier of the pay schedule to which the pay period
belongs.
type: string
x-tags:
- Employee Employments
Pay-Schedule-Assignment:
description: The representation of a pay schedule assignment.
type: object
x-examples:
example-1:
type: by_employee
employees:
employee_uuid: f0238368-f2cf-43e2-9a07-b0265f2cec69
pay_schedule_uuid: c277ac52-9871-4a96-a1e6-0c449684602a
properties:
type:
description: The pay schedule assignment type.
type: string
enum:
- single
- hourly_salaried
- by_employee
- by_department
readOnly: true
hourly_pay_schedule_uuid:
description: Pay schedule for hourly employees.
type: string
readOnly: true
nullable: true
salaried_pay_schedule_uuid:
description: Pay schedule for salaried employees.
type: string
readOnly: true
nullable: true
default_pay_schedule_uuid:
description: Default pay schedule for employees.
type: string
readOnly: true
nullable: true
employees:
description: List of employees and their pay schedules.
type: array
readOnly: true
nullable: true
items:
$ref: '#/components/schemas/Pay-Schedule-Assignment-Employee'
departments:
description: List of departments and their pay schedules.
type: array
readOnly: true
nullable: true
items:
$ref: '#/components/schemas/Pay-Schedule-Assignment-Department'
x-tags:
- Pay Schedules
Pay-Schedule-Assignment-Employee:
type: object
x-examples:
example-1:
employee_uuid: 43b39ada-dc49-4879-9594-fe95f67ae434
pay_schedule_uuid: 3f029a58-155d-4c30-8361-cc266b2c1f11
properties:
employee_uuid:
description: The UUID of the employee.
type: string
pay_schedule_uuid:
description: The employee's pay schedule UUID.
type: string
x-tags:
- Pay Schedules
Pay-Schedule-Assignment-Department:
type: object
x-examples:
example-1:
department_uuid: 43b39ada-dc49-4879-9594-fe95f67ae434
pay_schedule_uuid: 3f029a58-155d-4c30-8361-cc266b2c1f11
properties:
department_uuid:
description: The UUID of the department.
type: string
pay_schedule_uuid:
description: The department's pay schedule UUID.
type: string
x-tags:
- Pay Schedules
Pay-Schedule-Assignment-Preview:
description: The representation of a pay schedule assignment preview.
type: object
x-examples:
example-1:
type: hourly_salaried
employee_changes:
employee_uuid: 43b39ada-dc49-4879-9594-fe95f67ae434
first_name: Penny
last_name: Parker
pay_frequency: Twice per month — Salaried pay schedule
first_pay_period:
pay_schedule_uuid: 3f029a58-155d-4c30-8361-cc266b2c1f11
start_date: '2023-07-01'
end_date: '2023-08-01'
check_date: '2023-08-02'
transition_pay_period:
start_date: '2023-06-20'
end_date: '2023-06-30'
properties:
type:
description: The pay schedule assignment type.
type: string
enum:
- single
- hourly_salaried
- by_employee
- by_department
readOnly: true
employee_changes:
description: >-
A list of pay schedule changes including pay period and transition
pay period.
type: array
items:
$ref: '#/components/schemas/Pay-Schedule-Assignment-Employee-Change'
x-tags:
- Pay Schedules
Pay-Schedule-Assignment-Employee-Change:
type: object
x-examples:
example-1:
employee_uuid: 43b39ada-dc49-4879-9594-fe95f67ae434
first_name: Penny
last_name: Parker
pay_frequency: Twice per month — Salaried pay schedule
first_pay_period:
pay_schedule_uuid: 3f029a58-155d-4c30-8361-cc266b2c1f11
start_date: '2023-07-01'
end_date: '2023-08-01'
check_date: '2023-08-02'
transition_pay_period:
start_date: '2023-06-20'
end_date: '2023-06-30'
properties:
employee_uuid:
description: The UUID of the employee.
type: string
readOnly: true
first_name:
description: The employee's first name.
type: string
readOnly: true
last_name:
description: The employee's last name.
type: string
readOnly: true
pay_frequency:
description: New pay schedule frequency and name.
type: string
readOnly: true
first_pay_period:
$ref: '#/components/schemas/Pay-Schedule-Assignment-Pay-Period'
transition_pay_period:
$ref: '#/components/schemas/Pay-Schedule-Assignment-Transition-Pay-Period'
x-tags:
- Pay Schedules
Pay-Schedule-Assignment-Pay-Period:
description: Pay schedule assignment first pay period information.
type: object
x-examples:
example-1:
pay_schedule_uuid: 3f029a58-155d-4c30-8361-cc266b2c1f11
start_date: '2023-07-01'
end_date: '2023-08-01'
check_date: '2023-08-02'
properties:
pay_schedule_uuid:
description: The pay schedule UUID.
type: string
start_date:
description: Pay period start date.
type: string
end_date:
description: Pay period end date.
type: string
check_date:
description: Pay period check date.
type: string
x-tags:
- Pay Schedules
Pay-Schedule-Assignment-Transition-Pay-Period:
description: Pay schedule assignment transition pay period information.
type: object
x-examples:
example-1:
start_date: '2023-07-01'
end_date: '2023-08-01'
properties:
start_date:
description: Pay period start date.
type: string
end_date:
description: Pay period end date.
type: string
x-tags:
- Pay Schedules
Accruing-Time-Off-Hour:
description: The representation of an unprocessed termination pay period.
type: object
properties:
time_off_policy_uuid:
description: A unique identifier of the time off policy.
type: string
hours:
description: Hours accrued during this pay period.
type: string
Employee-Federal-Tax:
title: Employee-Federal-Tax
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
filing_status:
description: >-
It determines which tax return form an individual will use and is an
important factor in computing taxable income. One of:
- Single
- Married
- Head of Household
- Exempt from withholding
- Married, but withhold as Single (does not apply to rev_2020_w4
form)
type: string
extra_withholding:
description: >-
An employee can request an additional amount to be withheld from
each paycheck.
type: string
two_jobs:
description: >-
If there are only two jobs (i.e., you and your spouse each have a
job, or you have two), you can set it to true.
type: boolean
dependents_amount:
description: >-
A dependent is a person other than the taxpayer or spouse who
entitles the taxpayer to claim a dependency exemption.
type: string
other_income:
description: Other income amount.
type: string
deductions:
type: string
w4_data_type:
description: The version of w4 form.
type: string
enum:
- pre_2020_w4
- rev_2020_w4
federal_withholding_allowance:
description: |-
*does not apply to rev_2020_w4 form*
An exemption from paying a certain amount of income tax.
type: string
additional_withholding:
description: '*does not apply to rev_2020_w4 form*'
type: boolean
x-examples:
Example:
value:
version: 56a489ce86ed6c1b0f0cecc4050a0b01
filing_status: Single
extra_withholding: '0.0'
two_jobs: true
dependents_amount: '0.0'
other_income: '0.0'
deductions: '0.0'
w4_data_type: rev_2020_w4
x-tags:
- Employee Tax Setup
Employee-State-Tax:
title: Employee-State-Tax
type: object
x-examples:
example-1:
employee_uuid: 2005e601-3c78-410a-9d40-b960ae130383
state: CA
questions:
- description: >
The Head of Household status applies to unmarried individuals
who have a relative living with them in their home. If unsure,
read the CA
Filing Status explanation.
label: Filing Status
key: filing_status
input_question_format:
type: Select
options:
- value: S
label: Single
- value: M
label: Married one income
- value: MD
label: Married dual income
- value: H
label: Head of household
- value: E
label: Do Not Withhold
answers:
- value: S
valid_from: '2010-01-01'
valid_up_to: null
- description: >
This value is needed to calculate the employee's CA income tax
withholding. If unsure, use the CA DE-4
form to calculate the value manually.
label: Withholding Allowance
key: withholding_allowance
input_question_format:
type: Number
answers:
- value: 1
valid_from: '2010-01-01'
valid_up_to: null
- description: >-
You can withhold an additional amount of California income taxes
here.
label: Additional Withholding
key: additional_withholding
input_question_format:
type: Currency
answers:
- value: '0.0'
valid_from: '2010-01-01'
valid_up_to: null
- description: >-
State law requires you to file a new hire report within 20 days
of hiring or re-hiring an employee.
label: File a New Hire Report?
key: file_new_hire_report
input_question_format:
type: Select
options:
- value: true
label: Yes, file the state new hire report for me.
- value: false
label: No, I have already filed.
answers:
- value: true
valid_from: '2010-01-01'
valid_up_to: null
x-tags:
- Employee Tax Setup
properties:
employee_uuid:
description: The employee's uuid
type: string
state:
description: Two letter US state abbreviation
type: string
file_new_hire_report:
type: boolean
is_work_state:
type: boolean
questions:
type: array
items:
$ref: '#/components/schemas/Employee-State-Tax-Question'
required:
- employee_uuid
- state
- questions
Employee-State-Tax-Question:
title: Employee-State-Tax-Question
type: object
x-examples:
example-1:
description: >
The Head of Household status applies to unmarried individuals who
have a relative living with them in their home. If unsure, read the
CA
Filing Status explanation.
label: Filing Status
key: filing_status
input_question_format:
type: Select
options:
- value: S
label: Single
- value: M
label: Married one income
- value: MD
label: Married dual income
- value: H
label: Head of household
- value: E
label: Do Not Withhold
answers:
- value: S
valid_from: '2010-01-01'
valid_up_to: null
x-tags:
- Employee Tax Setup
properties:
description:
description: >-
An explaination of the question - this may contain inline html
formatted links.
type: string
label:
description: A short title for the question
type: string
key:
description: >-
A unique identifier of the question (for the given state) - used for
updating the answer.
type: string
input_question_format:
$ref: '#/components/schemas/Employee-State-Tax-Input-Question-Format'
answers:
type: array
items:
$ref: '#/components/schemas/Employee-State-Tax-Answer'
required:
- label
- description
- key
- input_question_format
- answers
Employee-State-Tax-Answer:
title: Employee-State-Tax-Answer
type: object
x-examples:
example-1:
value: '0.0'
valid_from: '2010-01-01'
valid_up_to: null
x-tags:
- Employee Tax Setup
properties:
value:
description: >-
The answer to the corresponding question - this may be a string,
number, boolean, or null.
type: string
valid_from:
description: The effective date of the answer - currently always “2010-01-01”.
type: string
valid_up_to:
description: The effective end date of the answer - currently always null.
nullable: true
Employee-State-Tax-Input-Question-Format:
title: Employee-State-Tax-Input-Question-Format
type: object
x-examples:
select-example:
type: Select
options:
- value: S
label: Single
- value: M
label: Married one income
- value: MD
label: Married dual income
- value: H
label: Head of household
- value: E
label: Do Not Withhold
number-example:
type: Number
x-tags:
- Employee Tax Setup
properties:
type:
description: >-
Describes the type of question - Text, Number, Select, Currency,
Date
type: string
options:
description: For "Select" type questions, the allowed values and display labels.
type: array
uniqueItems: true
items:
type: object
properties:
value:
description: An allowed value to answer the question
type: string
label:
description: A display label that corresponds to the answer value
type: string
required:
- label
required:
- type
Federal-Tax-Details:
title: Federal-Tax-Details
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
tax_payer_type:
description: |-
What type of tax entity the company is. One of:
- C-Corporation
- S-Corporation
- Sole proprietor
- LLC
- LLP
- Limited partnership
- Co-ownership
- Association
- Trusteeship
- General partnership
- Joint venture
- Non-Profit
type: string
taxable_as_scorp:
description: >-
Whether the company is taxed as an S-Corporation. Tax payer types
that may be taxed as an S-Corporation include:
- S-Corporation
- C-Corporation
- LLC
type: boolean
filing_form:
description: |-
The form used by the company for federal tax filing. One of:
- 941 (Quarterly federal tax return form)
- 944 (Annual federal tax return form)
type: string
has_ein:
description: Whether company's Employer Identification Number (EIN) is present
type: boolean
ein_verified:
description: >-
Whether the EIN was able to be verified as a valid EIN with the
IRS.
type: boolean
legal_name:
description: The legal name of the company
type: string
x-examples:
Example:
value:
version: string
tax_payer_type: string
taxable_as_scorp: false
filing_form: string
has_ein: true
ein_verified: true
legal_name: string
x-tags:
- Federal Tax Details
Employee-Bank-Account:
title: Employee-Bank-Account
type: object
x-examples:
Example:
value:
uuid: 1531e824-8d9e-4bd8-9f90-0d04608125d7
employee_uuid: 9fcf1b1d-8886-4691-9283-383d3bdd4fd9
name: BoA Checking Account
routing_number: '266905059'
hidden_account_number: XXXX1207
account_type: Checking
properties:
uuid:
description: UUID of the bank account
type: string
employee_uuid:
description: UUID of the employee
type: string
account_type:
description: Bank account type
type: string
enum:
- Checking
- Savings
name:
description: Name for the bank account
type: string
routing_number:
description: The bank account's routing number
type: string
hidden_account_number:
description: Masked bank account number
type: string
x-tags:
- Employee Payment Method
Contractor-Bank-Account:
title: Contractor-Bank-Account
type: object
x-examples:
Example:
value:
uuid: 1531e824-8d9e-4bd8-9f90-0d04608125d7
employee_uuid: 9fcf1b1d-8886-4691-9283-383d3bdd4fd9
name: BoA Checking Account
routing_number: '266905059'
hidden_account_number: XXXX1207
account_type: Checking
x-tags:
- Contractor Payment Method
properties:
uuid:
description: UUID of the bank account
type: string
contractor_uuid:
description: UUID of the employee
type: string
account_type:
description: Bank account type
type: string
enum:
- Checking
- Savings
name:
description: Name for the bank account
type: string
routing_number:
description: The bank account's routing number
type: string
hidden_account_number:
description: Masked bank account number
type: string
Employee-Payment-Method:
title: Employee-Payment-Method
description: ''
type: object
x-examples:
Example-1:
value:
version: 63859768485e218ccf8a449bb60f14ed
type: Direct Deposit
split_by: Amount
splits:
- uuid: e88f9436-b74e-49a8-87e9-777b9bfe715e
name: BoA Checking Account
priority: 1
split_amount: 500
- uuid: 0d2b7f73-05d6-4184-911d-269edeecc30a
name: Chase Checking Account
priority: 2
split_amount: 1000
- uuid: 1531e824-8d9e-4bd8-9f90-0d04608125d7
name: US Bank Checking Account
priority: 3
split_amount: null
Example-2:
value:
version: 63859768485e218ccf8a449bb60f14ed
type: Direct Deposit
split_by: Percentage
splits:
- uuid: e88f9436-b74e-49a8-87e9-777b9bfe715e
name: BoA Checking Account
priority: 1
split_amount: 60
- uuid: 0d2b7f73-05d6-4184-911d-269edeecc30a
name: Chase Checking Account
priority: 2
split_amount: 40
Example-3:
value:
version: 63859768485e218ccf8a449bb60f14ed
type: Check
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
type:
description: >-
The payment method type. If type is Check, then split_by and splits
do not need to be populated. If type is Direct Deposit, split_by and
splits are required.
type: string
enum:
- Direct Deposit
- Check
split_by:
description: >-
Describes how the payment will be split. If split_by is Percentage,
then the split amounts must add up to exactly 100. If split_by is
Amount, then the last split amount must be nil to capture the
remainder.
type: string
enum:
- Amount
- Percentage
nullable: true
splits:
type: array
nullable: true
items:
$ref: '#/components/schemas/Payment-Method-Bank-Account'
x-tags:
- Employee Payment Method
Tax-Requirement:
type: object
x-examples:
ga-withholding-requirement-example:
description: >-
If you have run payroll in the past in GA, find your withholding
number on notices received from the Georgia Department of Revenue,
or call the agency at (877) 423-6711. If you don’t have a number
yet, you should register the business online.
The last two characters of your ID must be upper case letters.
key: 71653ec0-00b5-4c66-a58b-22ecf21704c5
applicable_if: []
label: Withholding Number
value: 1233214-AB
metadata:
type: account_number
mask: '#######-^^'
prefix: null
properties:
description:
description: A more detailed customer facing description of the requirement
type: string
key:
$ref: '#/components/schemas/Tax-Requirement-Key'
applicable_if:
description: >-
An array of references to other requirements within the requirement
set. This requirement is only applicable if all referenced
requirements have values matching the corresponding `value`. The
primary use-case is dynamically hiding and showing requirements as
values change. E.g. Show Requirement-B when Requirement-A has been
answered with `false`. To be explicit, an empty array means the
requirement is applicable.
type: array
items:
type: object
properties:
key:
$ref: '#/components/schemas/Tax-Requirement-Key'
value:
description: The required value of the requirement identified by `key`
oneOf:
- type: boolean
- type: string
- type: number
label:
description: A customer facing description of the requirement
type: string
value:
description: The "answer"
type: string
metadata:
$ref: '#/components/schemas/Tax-Requirement-Metadata'
Tax-Requirement-Metadata:
description: ''
type: object
x-examples:
select-example:
type: select
options:
- label: Semiweekly
value: Semi-weekly
- label: Monthly
value: Monthly
- label: Quarterly
value: Quarterly
tax_rate-example:
metadata:
type: tax_rate
validation:
type: min_max
min: '0.0004'
max: '0.081'
radio-example:
metadata:
type: radio
options:
- label: >-
No, we cannot reimburse the state—we have to pay SUI taxes
quarterly
short_label: Not Reimbursable
value: false
- label: >-
Yes, we can reimburse the state if an employee collects SUI
benefits—we don’t have to pay SUI taxes quarterly
short_label: Reimbursable
value: true
account_number-example:
metadata:
type: account_number
mask: '######-##'
prefix: null
properties:
type:
description: >
Describes the type of requirement - each type may have additional
metadata properties to describe possible values, formats, etc.
- `text`: free-text input, no additional requirements
- `currency`: a value representing a dollar amount, e.g. `374.55`
representing `$374.55`
- `radio`: choose one of options provided, see `options`
- `select`: choose one of options provided, see `options`
- `percent`: A decimal value representing a percentage, e.g. `0.034`
representing `3.4%`
- `account_number`: An account number for a tax agency, more
information provided by `mask` and `prefix`
- `tax_rate`: A decimal value representing a tax rate, e.g. `0.034`
representing a tax rate of `3.4%`, see `validation` for additional
validation guidance
- `workers_compensation_rate`: A decimal value representing a
percentage, see `risk_class_code`, `risk_class_description`, and
`rate_type`
type: string
enum:
- text
- currency
- radio
- select
- percent
- account_number
- tax_rate
- workers_compensation_rate
readOnly: true
options:
description: >-
[for `select` or `radio`] An array of objects describing the
possible values.
type: array
items:
type: object
properties:
label:
description: A customer facing label for the answer
type: string
value:
description: The actual value to be submitted
type: string
short_label:
description: A less verbose label that may sometimes be available
type: string
required:
- label
- value
risk_class_code:
description: >-
[for `workers_compensation_rate`] The industry risk class code for
the rate being requested
type: string
risk_class_description:
description: >-
[for `workers_compensation_rate`] A description of the industry risk
class for the rate being requested
type: string
rate_type:
description: >
[for `workers_compensation_rate`] The type of rate being collected.
Either:
- `percent`: A percentage formatted as a decimal, e.g. `0.01` for 1%
- `currency_per_hour`: A dollar amount per hour, e.g. `3.24` for $3.24/hr
type: string
enum:
- percent
- currency_per_hour
mask:
description: >
[for `account_number`] A pattern describing the format of the
account number
The mask is a sequence of characters representing the requirements
of the actual account number. Each character in the mask represents
a single character in the account number as follows:
- `#`: a digit (`\d`)
- `@`: a upper or lower case letter (`[a-zA-Z]`)
- `^`: an uppercase letter (`[A-Z]`)
- `%`: a digit or uppercase letter (`[0-9A-Z]`)
- any other character represents the literal character
Examples:
- mask: `WHT-######` represents `WHT-` followed by 5 digits, e.g.
`WHT-33421`
- mask: `%####-^^` supports values of `75544-AB` and `Z7654-HK`
type: string
prefix:
description: >-
[for `account_number`] A value that precedes the value to be
collected - useful for display, but should not be submitted as part
of the value. E.g. some tax agencies use an account number that is a
company's federal ein plus two digits. In that case the mask would
be `##` and the prefix `XXXXX1234`.
type: string
validation:
description: '[for `tax_rate`] Describes the validation required for the tax rate'
type: object
properties:
type:
description: Describes the type of tax_rate validation rule
type: string
enum:
- one_of
- min_max
min:
description: '[for `min_max`] The inclusive lower bound of the tax rate'
type: string
max:
description: '[for `min_max`] The inclusive upper bound of the tax rate'
type: string
rates:
description: >
[for `one_of`] The possible, unformatted tax rates for
selection.
- e.g. ["0.0", "0.001"] representing 0% and 0.1%
type: array
items:
type: string
required:
- type
required:
- type
Tax-Requirement-Set:
description: ''
type: object
x-examples:
tax-requirements-set-ga-registrations-example:
state: GA
key: registrations
label: Registrations
effective_from: null
requirements:
- description: >-
If you have run payroll in the past in GA, find your withholding
number on notices received from the Georgia Department of
Revenue, or call the agency at (877) 423-6711. If you don’t have
a number yet, you should register the business
online. The last two characters of your ID must be upper
case letters.
key: 71653ec0-00b5-4c66-a58b-22ecf21704c5
applicable_if: []
label: Withholding Number
value: 1233214-AB
metadata:
type: account_number
mask: '#######-^^'
prefix: null
- description: >-
If you have run payroll in the past in GA, find your DOL account
number on notices received from the Georgia Department of Labor,
or call the agency at (404) 232-3300. If you don’t have an
account number yet, please follow
the instructions here to register your business with the
Georgia Dept. of Labor.
key: 6c0911ab-5860-412e-bdef-6437cd881df5
applicable_if: []
label: DOL Account Number
value: 474747-88
metadata:
type: account_number
mask: '######-##'
prefix: null
properties:
state:
$ref: '#/components/schemas/State'
key:
$ref: '#/components/schemas/Tax-Requirement-Set-Key'
label:
description: Customer facing label for the requirement set, e.g. "Registrations"
type: string
effective_from:
$ref: '#/components/schemas/Tax-Requirement-Effective-From'
requirements:
type: array
items:
$ref: '#/components/schemas/Tax-Requirement'
Tax-Requirements-State:
title: Tax-Requirements-State
description: ''
type: object
x-examples:
tax-requirements-state-ga-example:
company_uuid: 6c14eac3-0da2-474d-bda1-786b3602d381
state: GA
requirement_sets:
- state: GA
key: registrations
label: Registrations
effective_from: null
requirements:
- description: >-
If you have run payroll in the past in GA, find your
withholding number on notices received from the Georgia
Department of Revenue, or call the agency at (877) 423-6711.
If you don’t have a number yet, you should register the business
online. The last two characters of your ID must be upper
case letters.
key: 71653ec0-00b5-4c66-a58b-22ecf21704c5
applicable_if: []
label: Withholding Number
value: 1233214-AB
metadata:
type: account_number
mask: '#######-^^'
prefix: null
- description: >-
If you have run payroll in the past in GA, find your DOL
account number on notices received from the Georgia
Department of Labor, or call the agency at (404) 232-3300.
If you don’t have an account number yet, please follow
the instructions here to register your business with the
Georgia Dept. of Labor.
key: 6c0911ab-5860-412e-bdef-6437cd881df5
applicable_if: []
label: DOL Account Number
value: 474747-88
metadata:
type: account_number
mask: '######-##'
prefix: null
- state: GA
key: taxrates
label: Tax Rates
effective_from: '2022-01-01'
requirements:
- description: >-
Instead of paying state unemployment insurance (SUI) taxes
quarterly, some businesses (like non-profits or government
organizations) may be allowed to reimburse the state if one
of their employees collects unemployment benefits.
key: suireimbursable
applicable_if: []
label: SUI Reimburser
value: false
metadata:
type: radio
options:
- label: >-
No, we cannot reimburse the state—we have to pay SUI
taxes quarterly
short_label: Not Reimbursable
value: false
- label: >-
Yes, we can reimburse the state if an employee
collects SUI benefits—we don’t have to pay SUI taxes
quarterly
short_label: Reimbursable
value: true
- description: >-
Haven't received your assigned rate yet? Find
the new employer rate and enter it here.
key: e0ac2284-8d30-4100-ae23-f85f9574868b
applicable_if:
- key: suireimbursable
value: false
label: Total Tax Rate
value: '0.05'
metadata:
type: tax_rate
validation:
type: min_max
min: '0.0004'
max: '0.081'
- state: GA
key: depositschedules
label: Deposit Schedules
effective_from: '2022-01-01'
requirements:
- description: >-
Georgia rejects payments made on the wrong schedule. GA
employers receive their schedule on a registration
verification letter after registering with the Georgia Dept.
of Revenue. If you are unsure, call the agency at (877)
423-6711. If you did not register your business yet, please
register the business
with the Georgia Dept. of Revenue.
key: 6ddfcbeb-94d3-4003-bfc2-8c6e1ca9f70c
applicable_if: []
label: Deposit Schedule
value: Monthly
metadata:
type: select
options:
- label: Semiweekly
value: Semi-weekly
- label: Monthly
value: Monthly
- label: Quarterly
value: Quarterly
- state: GA
key: depositschedules
label: Deposit Schedules
effective_from: '2022-07-01'
requirements:
- description: >-
Georgia rejects payments made on the wrong schedule. GA
employers receive their schedule on a registration
verification letter after registering with the Georgia Dept.
of Revenue. If you are unsure, call the agency at (877)
423-6711. If you did not register your business yet, please
register the business
with the Georgia Dept. of Revenue.
key: 6ddfcbeb-94d3-4003-bfc2-8c6e1ca9f70c
applicable_if: []
label: Deposit Schedule
value: Monthly
metadata:
type: select
options:
- label: Semiweekly
value: Semi-weekly
- label: Monthly
value: Monthly
- label: Quarterly
value: Quarterly
properties:
company_uuid:
type: string
state:
$ref: '#/components/schemas/State'
requirement_sets:
type: array
items:
$ref: '#/components/schemas/Tax-Requirement-Set'
Tax-Requirement-Set-Key:
title: Tax-Requirement-Set-Key
description: >-
An identifier for a set of requirements. A list of requirement sets can
contain multiple sets with the same `key` and different `effective_from`
values.
type: string
Tax-Requirement-Key:
title: Tax-Requirement-Key
description: >-
An identifier for an individual requirement. Uniqueness is guaranteed
within a requirement set.
type: string
Tax-Requirement-Effective-From:
title: Tax-Requirement-Effective-From
description: >-
An ISO 8601 formatted date representing the date values became
effective. Some requirement sets are effective dated, while others are
not. Multiple requirement sets for the same state/key can/will exist
with unique effective dates. If a requirement set is has an
`effective_from` value, all requirement sets with the same key will also
have an `effective_from` value.
type: string
nullable: true
State:
title: State
description: >-
One of the two-letter state abbreviations for the fifty United States
and the District of Columbia (DC)
type: string
Time-Off-Policy:
description: Representation of a Time Off Policy
type: object
x-examples:
example:
uuid: 3f746cd0-dd08-408f-b712-8180c7c621e9
company_uuid: de83cff2-8e7a-448e-a28c-14258a9971c3
name: test policy
policy_type: vacation
accrual_method: unlimited
is_active: true
employees:
- uuid: c61d1895-5cf8-4217-88c8-20d7c3132a04
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer)
for information on how to use this field.
type: string
uuid:
description: Unique identifier of a time off policy
type: string
company_uuid:
description: Unique identifier for the company owning the time off policy
type: string
name:
description: Name of the time off policy
type: string
policy_type:
description: Type of the time off policy
type: string
enum:
- vacation
- sick
accrual_method:
description: Policy time off accrual method
type: string
accrual_rate:
description: >-
The rate at which the time off hours will accrue for an employee on
the policy. Represented as a float, e.g. "40.0".
type: string
format: float
accrual_rate_unit:
description: >-
The number of hours an employee has to work or be paid for to accrue
the number of hours set in the accrual rate. Only used for hourly
policies (per_hour_paid, per_hour_paid_no_overtime, per_hour_work,
per_hour_worked_no_overtime). Represented as a float, e.g. "40.0".
type: string
format: float
paid_out_on_termination:
description: >-
Boolean representing if an employees accrued time off hours will be
paid out on termination
type: boolean
accrual_waiting_period_days:
description: >-
Number of days before an employee on the policy will begin accruing
time off hours
type: integer
carryover_limit_hours:
description: >-
The max number of hours and employee can carryover from one year to
the next
type: string
format: float
max_accrual_hours_per_year:
description: The max number of hours and employee can accrue in a year
type: string
format: float
max_hours:
description: The max number of hours an employee can accrue
type: string
format: float
complete:
description: boolean representing if a policy has completed configuration
type: boolean
is_active:
description: boolean representing if a policy is active or not
type: boolean
employees:
description: List of employee UUIDs under a time off policy
type: array
items:
type: object
properties:
uuid:
type: string
required:
- uuid
- company_uuid
- name
- policy_type
- accrual_method
- is_active
- employees
Time-Off-Activity:
description: Representation of a Time Off Activity
type: object
x-examples:
example:
policy_uuid: a7838f74-4c29-4b70-9bfb-02a4e3e60709
time_off_type: vacation
policy_name: Paid Time Off
event_type: TimeOffEvent::AddToPolicy
event_description: 'Added to policy: Vacation Per Hour Worked'
effective_time: '2022-09-27T13:43:03.000-07:00'
balance: '0.0'
balance_change: '0.0'
properties:
policy_uuid:
description: unique identifier of a time off policy
type: string
time_off_type:
description: Type of the time off activity
type: string
enum:
- vacation
- sick
policy_name:
description: The name of the time off policy for this activity
type: string
event_type:
description: The type of the time off event/activity
type: string
event_description:
description: A description for the time off event/activity
type: string
effective_time:
description: The datetime of the time off activity
type: string
balance:
description: The time off balance at the time of the activity
type: string
format: float
balance_change:
description: The amount the time off balance changed as a result of the activity
type: string
format: float
Holiday-Pay-Policy:
description: Representation of a Holiday Pay Policy
type: object
x-examples:
example:
version: 1b37938b017c7fd7116bada007072290
company_uuid: b7845189-f12b-4378-918a-d2b9de3dc4ea
federal_holidays:
new_years_day:
selected: true
name: New Year's Day
date: January 1
mlk_day:
selected: true
name: Martin Luther King, Jr. Day
date: Third Monday in January
presidents_day:
selected: false
name: Presidents' Day
date: Third Monday in February
memorial_day:
selected: true
name: Memorial Day
date: Last Monday in May
juneteenth:
selected: false
name: Juneteenth
date: June 19
independence_day:
selected: true
name: Independence Day
date: July 4
labor_day:
selected: false
name: Labor Day
date: First Monday in September
columbus_day:
selected: false
name: Columbus Day (Indigenous Peoples' Day)
date: Second Monday in October
veterans_day:
selected: true
name: Veterans Day
date: November 11
thanksgiving:
selected: true
name: Thanksgiving
date: Fourth Thursday in November
christmas_day:
selected: true
name: Christmas Day
date: December 25
employees:
uuid: 1ca3cd25-3eda-48c6-ac88-f0e7fb91a15a
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer)
for information on how to use this field.
type: string
company_uuid:
description: A unique identifier for the company owning the holiday pay policy
type: string
federal_holidays:
description: List of the eleven supported federal holidays and their details
type: array
items:
type: object
properties:
new_years_day:
type: object
properties:
selected:
type: boolean
name:
type: string
date:
type: string
mlk_day:
type: object
properties:
selected:
type: boolean
name:
type: string
date:
type: string
presidents_day:
type: object
properties:
selected:
type: boolean
name:
type: string
date:
type: string
memorial_day:
type: object
properties:
selected:
type: boolean
name:
type: string
date:
type: string
juneteenth:
type: object
properties:
selected:
type: boolean
name:
type: string
date:
type: string
independence_day:
type: object
properties:
selected:
type: boolean
name:
type: string
date:
type: string
labor_day:
type: object
properties:
selected:
type: boolean
name:
type: string
date:
type: string
columbus_day:
type: object
properties:
selected:
type: boolean
name:
type: string
date:
type: string
veterans_day:
type: object
properties:
selected:
type: boolean
name:
type: string
date:
type: string
thanksgiving:
type: object
properties:
selected:
type: boolean
name:
type: string
date:
type: string
employees:
description: List of employee uuids under a time off policy
type: array
items:
type: object
properties:
uuid:
type: string
required:
- version
- company_uuid
- federal_holidays
- employees
Paid-Holidays:
description: >-
Representation of a company's paid holidays as descibed by their Holiday
Pay Policy
type: object
properties:
schema:
type: object
properties:
holiday_key:
description: the holiday's identifier
type: string
holiday_name:
description: the holiday's official name
type: string
start_date:
description: the holiday's start date (YYYY-MM-DD)
type: string
end_date:
description: the holiday's end date (YYYY-MM-DD)
type: string
Minimum-Wage:
description: Representation of a Minimum Wage
type: object
x-examples:
example:
uuid: 70c523ff-c71e-4474-9c83-a4ea51bd54a8
authority: State
wage: '13.0'
wage_type: Regular
effective_date: '2022-01-01'
notes: Employers with 6 or more employees
properties:
uuid:
description: unique identifier of a minimum wage
type: string
wage:
description: >-
The wage rate for a minimum wage record. Represented as a float,
e.g. "15.0".
type: string
format: float
wage_type:
description: >-
The type of wage the minimum wage applies to, e.g. "Regular",
"Regular-Industry-Specific".
type: string
effective_date:
description: The date the minimum wage rule is effective on.
type: string
format: date
authority:
description: >-
The governing authority that created the minimum wage, e.g. "City",
"State", or "Federal".
type: string
notes:
description: Description of parties the minimum wage applies to.
type: string
required:
- uuid
- wage
- wage_type
- effective_date
- authority
Notification:
description: Representation of a notification
type: object
x-examples:
example:
title: 'Action required: Additional information needed to process payroll'
uuid: 7b1d0df1-6403-4a06-8768-c1dd7d24d27a
company_uuid: 88f7cca1-dcad-4d20-84db-7fb80303d69f
message: >-
If we do not receive this information as soon as possible, your
payroll may not be processed on time.
category: information_request
created_at: '2022-01-01T00:00:00.000Z'
properties:
title:
description: >-
The title of the notification. This highlights the actionable
component of the notification.
type: string
uuid:
description: Unique identifier of a notification.
type: string
company_uuid:
description: Unique identifier of the company to which the notification belongs.
type: string
message:
description: >-
The message of the notification. This provides additional context
for the user and recommends a specific action to resolve the
notification.
type: string
category:
description: The notification's category.
type: string
actionable:
description: >-
Indicates whether a notification requires action or not. If false,
the notification provides critical information only.
type: boolean
published_at:
description: Timestamp of when the notification was published.
type: string
due_at:
description: >-
Timestamp of when the notification is due. If the notification has
no due date, this field will be null.
type: string
resources:
description: An array of entities relevant to the notification
type: array
items:
type: object
properties:
entity_type:
description: >-
The type of entity being described, could be “Contractor”,
“Employee”, “BankAccount”, “Payroll”, “ContractorPayment”,
“RecoveryCase”, or “Signatory”
type: string
entity_uuid:
description: Unique identifier of the entity
type: string
reference_type:
description: >-
Optional. The type of a resource that is related to the one
described by entity_type and entity_uuid. For instance, if the
entity_type is “BankAccount”, the reference_type could be the
“Employee” or “Contractor” to whom the bank account belongs.
type: string
reference_uuid:
description: Optional. Unique identifier of the reference.
type: string
required:
- entity_type
- entity_uuid
Event:
description: Representation of an Event
type: object
x-examples:
example:
uuid: f7397a24-57ad-4fae-b011-d258e8232900
event_type: employee.bank_account.created
resource_type: Company
resource_uuid: 92a20431-9489-4bde-ad27-6feb20b969d5
entity_type: BankAccount
entity_uuid: 92a20431-9489-4bde-ad27-6feb20b969d5
timestamp: 1686784995
properties:
uuid:
description: Unique identifier for the event.
type: string
event_type:
description: >-
Description of the event (e.g., payroll.submitted, or
company.form.signed).
type: string
resource_type:
description: Name of the parent resource of the described entity.
type: string
enum:
- Company
resource_uuid:
description: Unique identifier for the parent resource.
type: string
entity_type:
description: Name of the entity that the event corresponds to.
type: string
entity_uuid:
description: Unique identifier for the entity.
type: string
timestamp:
description: >-
Time at which this event was created. Measured in seconds since the
Unix epoch.
type: integer
Invoice-Data:
description: Representation of a partners invoice data
type: object
x-examples:
example:
active_companies:
- company_uuid: 05ed3150-591e-4f8b-bfd5-55d478edd2d8
active_employees: 5
active_contractors: 3
initial_invoice_period: 2022-01
- company_uuid: 9b37429c-e540-40fb-86b3-738ca9af65c7
active_employees: 0
active_contractors: 1
initial_invoice_period: 2023-05
properties:
active_companies:
description: The list of companies that are active within the invoice period
type: array
items:
type: object
properties:
company_uuid:
description: >-
unique identifier for the company associated with the invoice
data
type: string
active_employees:
description: >-
The number of active employees the company was or will be
invoiced for that invoice period. Active employees are
calculated as the count of onboarded employees hired before
the end of the invoice period and not terminated before the
start of the invoice period.
type: integer
active_contractors:
description: >-
The number of active contractors the company was or will be
invoiced for that invoice period. Active contractors are
calculated as any contractor with an active contractor payment
during the invoice period.
type: integer
initial_invoice_period:
description: >-
The first invoice period for the company. This will either be
the invoice period of the first invoice-able event (first
payroll or contractor payment) or the date they migrated to
embedded, whichever is later.
type: string
Recovery-Case:
description: Representation of a recovery case
type: object
x-examples:
example:
uuid: e83d273e-4ae9-4b61-9c71-4030c2f73093
company_uuid: c5e3e3e9-732f-4762-849e-20b5cec9036f
status: open
latest_error_code: R01
original_debit_date: '2023-10-11'
check_date: '2023-10-13'
payroll_uuid: 210f2034-fb4a-4059-b109-6c3b5efe499d
contractor_payment_uuids: null
amount_outstanding: 10499.43
event_total_amount: 5912.07
properties:
uuid:
description: Unique identifier of an recovery case
type: string
company_uuid:
description: Unique identifier of the company to which the recovery case belongs
type: string
status:
description: Status of the recovery case
type: string
enum:
- open
- redebit_initiated
- recovered
- lost
latest_error_code:
description: >-
The latest bank error code for the recovery case. See [this
article](https://engineering.gusto.com/how-ach-works-a-developer-perspective-part-2/)
for a complete list of ACH return codes.
type: string
original_debit_date:
description: >-
Date when funds were originally debited from the company's bank
account
type: string
check_date:
description: Check date for the associated payroll or contractor payments
type: string
payroll_uuid:
description: >-
The uuid of the associated payroll for which the recovery case was
created. If the recovery case was created for a contractor payment,
this field will be null.
type: string
contractor_payment_uuids:
description: >-
The uuids of the associated contractor payments for which the
recovery case was created. If the recovery case was created for a
payroll, this field will be null.
type: array
items:
type: string
amount_outstanding:
description: Amount outstanding for the recovery case
type: string
event_total_amount:
description: Total amount to be debited from the payroll or contractor payments
type: string
Ach-Transaction:
description: Representation of an ACH transaction
type: object
x-examples:
example:
description: PAY 380654
uuid: 123e4567-e89b-12d3-a456-426655440000,
company_uuid: 456e7890-e12b-34c5-d678-901234567890,
payment_event_type: Payroll,
payment_event_uuid: 789e0123-e45f-67ab-c890-123456789012,
recipient_type: Employee,
recipient_uuid: 012e3456-f78d-90ab-12cd-345678901234,
error_code: null,
transaction_type: Credit employee pay,
payment_status: submitted,
payment_direction: credit,
payment_event_check_date: 2023-10-02,
payment_date: 2023-10-17,
amount: 123.00,
properties:
description:
description: >-
The description of the ACH transaction. Can be used to identify the
ACH transaction on the recipient's bank statement.
type: string
uuid:
description: Unique identifier of an ACH transaction
type: string
company_uuid:
description: >-
Unique identifier of the company to which the ACH transaction
belongs
type: string
payment_event_type:
description: The type of payment event associated with the ACH transaction
type: string
enum:
- Payroll
- ContractorPayment
payment_event_uuid:
description: >-
Unique identifier for the payment event associated with the ACH
transaction
type: string
recipient_type:
description: The type of recipient associated with the ACH transaction
type: string
enum:
- Employee
- Contractor
recipient_uuid:
description: >-
Unique identifier for the recipient associated with the ACH
transaction
type: string
error_code:
description: >-
The error code associated with the ACH transaction, if any. If there
is no error on the ACH transaction, this field will be nil. See
[this
article](https://engineering.gusto.com/how-ach-works-a-developer-perspective-part-2/)
for a complete list of ACH return codes.
type: string
transaction_type:
description: The type of transaction associated with the ACH transaction
type: string
payment_status:
description: The status of the ACH transaction
type: string
enum:
- unsubmitted
- submitted
- successful
- failed
payment_direction:
description: The direction of the payment
type: string
enum:
- credit
- debit
payment_event_check_date:
description: >-
The date of the payment event check associated with the ACH
transaction
type: string
payment_date:
description: The date of the payment associated with the ACH transaction
type: string
amount:
description: >-
The amount of money moved by the ACH transaction. This amount is
always non-negative.
type: string
IntrospectionExchangeRefreshTokenRequest:
description: ''
type: object
required:
- client_id
- client_secret
- grant_type
- refresh_token
properties:
client_id:
description: Your client id
type: string
client_secret:
description: Your client secret
type: string
redirect_uri:
description: The redirect URI you set up via the Developer Portal
type: string
refresh_token:
description: The `refresh_token` being exchanged for an access token code
type: string
grant_type:
description: this should be the literal string 'refresh_token'
type: string
CompaniesCreatePartnerManagedCompanyRequest:
type: object
properties:
user:
description: >-
Information for the user who will be the primary payroll
administrator for the new company.
type: object
required:
- first_name
- last_name
- email
properties:
first_name:
description: >-
The first name of the user who will be the primary payroll
admin.
type: string
last_name:
description: The last name of the user who will be the primary payroll admin.
type: string
email:
description: The email of the user who will be the primary payroll admin.
type: string
phone:
description: >-
The phone number of the user who will be the primary payroll
admin.
type: string
company:
type: object
required:
- name
properties:
name:
description: The legal name of the company.
type: string
trade_name:
description: The name of the company.
type: string
ein:
description: The employer identification number (EIN) of the company.
type: string
required:
- user
- company
CompaniesMigrateToEmbeddedPayrollRequest:
type: object
properties:
email:
description: >-
Email of the company signatory who is authorized to accept our
[Terms of Service](https://flows.gusto.com/terms) and migration
decision. You can retrieve the signatory email from the `GET
/v/1/companies/{company_id}/signatories` endpoint.
type: string
ip_address:
description: >-
The IP address of the signatory who viewed and accepted the Terms of
Service.
type: string
external_user_id:
description: The signatory's user ID on your platform.
type: string
required:
- email
- ip_address
- external_user_id
CompaniesAcceptTermsOfServiceRequest:
type: object
properties:
email:
description: >-
The user's email address on Gusto. You can retrieve the user's email
via company's `/admins`, `/employees`, `/signatories`, and
`/contractors` endpoints.
type: string
ip_address:
description: >-
The IP address of the user who viewed and accepted the Terms of
Service.
type: string
external_user_id:
description: The user ID on your platform.
type: string
required:
- email
- ip_address
- external_user_id
CompaniesGetTermsOfServiceStatusRequest:
type: object
properties:
email:
description: >-
The user's email address on Gusto. You can retrieve the user's email
via company's `/admins`, `/employees`, `/signatories`, and
`/contractors` endpoints.
type: string
required:
- email
FederalTaxDetailsUpdateAttributesRequest:
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer)
for information on how to use this field.
type: string
legal_name:
description: The legal name of the company
type: string
ein:
description: The EIN of of the company
type: string
tax_payer_type:
description: What type of tax entity the company is
type: string
enum:
- C-Corporation
- S-Corporation
- Sole proprietor
- LLC
- LLP
- Limited partnership
- Co-ownership
- Association
- Trusteeship
- General partnership
- Joint venture
- Non-Profit
filing_form:
description: |-
The form used by the company for federal tax filing. One of:
- 941 (Quarterly federal tax return)
- 944 (Annual federal tax return)
type: string
taxable_as_scorp:
description: Whether this company should be taxed as an S-Corporation
type: boolean
required:
- version
IndustrySelectionUpdateCompanyIndustrySelectionRequest:
description: ''
type: object
properties:
title:
description: Industry title
type: string
naics_code:
description: >-
North American Industry Classification System (NAICS) is used to
classify businesses with a six digit number based on the primary
type of work the business performs
type: string
sic_codes:
description: >-
A list of Standard Industrial Classification (SIC) codes, which are
four digit number that categorize the industries that companies
belong to based on their business activities. If sic_codes is not
passed in, we will perform an internal lookup with naics_code.
type: array
items:
type: string
required:
- title
- naics_code
CompaniesCreateAdminRequest:
description: ''
type: object
properties:
first_name:
description: The first name of the admin.
type: string
last_name:
description: The last name of the admin.
type: string
email:
description: >-
The email of the admin for Gusto's system. If the email matches an
existing user, this will create an admin account for them.
type: string
required:
- first_name
- last_name
- email
SignatoriesCreateSignatoryWithCompleteInformationRequest:
description: ''
type: object
properties:
title:
type: string
ssn:
type: string
first_name:
type: string
middle_initial:
type: string
last_name:
type: string
email:
type: string
phone:
type: string
birthday:
type: string
home_address:
description: The signatory's home address
type: object
properties:
street_1:
type: string
street_2:
type: string
city:
type: string
state:
type: string
zip:
type: string
required:
- street_1
- city
- state
- zip
required:
- ssn
- first_name
- last_name
- email
- title
- birthday
- home_address
- phone
SignatoriesCreateInviteRequest:
type: object
properties:
title:
type: string
first_name:
type: string
last_name:
type: string
email:
type: string
required:
- email
SignatoriesUpdateRequest:
type: object
properties:
title:
type: string
version:
description: >-
The current version of the object. See the versioning guide for
information on how to use this field.
type: string
first_name:
type: string
middle_initial:
type: string
last_name:
type: string
phone:
type: string
birthday:
type: string
ssn:
type: string
home_address:
type: object
properties:
street_1:
type: string
street_2:
type: string
city:
type: string
state:
type: string
zip:
type: string
FlowsGenerateLinkRequest:
type: object
properties:
flow_type:
description: flow type
type: string
entity_uuid:
description: >-
UUID of the target entity applicable to the flow. This field is
optional for company flows, please refer to the flow_types table
above for more details.
type: string
entity_type:
description: >-
the type of target entity applicable to the flow. This field is
optional for company flows, please refer to the flow_types table
above for more details.
type: string
enum:
- Company
- Employee
required:
- flow_type
LocationsCreateCompanyLocationRequest:
description: ''
type: object
properties:
phone_number:
type: string
pattern: '[0-9]{10}'
street_1:
type: string
street_2:
type: string
nullable: true
city:
type: string
state:
type: string
zip:
type: string
country:
type: string
default: USA
mailing_address:
description: Specify if this location is the company's mailing address.
type: boolean
filing_address:
description: Specify if this location is the company's filing address.
type: boolean
required:
- phone_number
- street_1
- city
- state
- zip
LocationsCreateCompanyLocationRequest1:
description: ''
type: object
properties:
phone_number:
type: string
minLength: 1
street_1:
type: string
minLength: 1
street_2:
type: string
nullable: true
minLength: 1
city:
type: string
minLength: 1
state:
type: string
minLength: 1
zip:
type: string
minLength: 1
country:
type: string
minLength: 1
required:
- phone_number
- street_1
- street_2
- city
- state
- zip
- country
LocationsUpdateLocationRequest:
allOf:
- $ref: '#/components/schemas/Versionable-Required'
- description: ''
type: object
properties:
phone_number:
type: string
pattern: '[0-9]{10}'
street_1:
type: string
street_2:
type: string
nullable: true
city:
type: string
state:
type: string
zip:
type: string
country:
type: string
mailing_address:
description: >-
For a company location, specify if this location is the
company's mailing address. A company has a single mailing
address, so this designation will override any previous
selection.
type: boolean
filing_address:
description: >-
For a company location, specify if this location is the
company's filing address. A company has a single filing address,
so this designation will override any previous selection.
type: boolean
BankAccountsCreateVerificationDepositsRequest:
description: ''
type: object
properties:
routing_number:
description: The bank routing number
type: string
nullable: false
account_number:
description: The bank account number
type: string
nullable: false
account_type:
description: The bank account type
type: string
nullable: false
enum:
- Checking
- Savings
BankAccountsVerifyMicroDepositsRequest:
description: ''
type: object
properties:
deposit_1:
description: The dollar amount of the first micro-deposit
type: number
nullable: false
deposit_2:
description: The dollar amount of the second micro-deposit
type: number
nullable: false
ExternalPayrollsCreateNewPayrollRequest:
description: ''
type: object
properties:
check_date:
description: External payroll's check date.
type: string
payment_period_start_date:
description: External payroll's pay period start date.
type: string
payment_period_end_date:
description: External payroll's pay period end date.
type: string
required:
- check_date
- payment_period_start_date
- payment_period_end_date
ExternalPayrollsUpdatePayrollItemsRequest:
type: object
properties:
replace_fields:
description: >-
Patch update external payroll items when set to true, otherwise it
will overwrite the previous changes.
type: boolean
external_payroll_items:
type: array
items:
description: Submit wages, benefits, taxes for each employee
type: object
properties:
employee_uuid:
description: The UUID of the employee.
type: string
earnings:
type: array
items:
description: >-
An array of earnings for the employee. Depends on your
company selections, earnings includes wages, hours, bonuses,
tips, commission and more.
type: object
properties:
hours:
description: The hour of the compensation for the pay period.
type: string
amount:
description: The amount of the earning.
type: string
earning_id:
description: The ID of the earning.
type: integer
earning_type:
description: The earning type for the compensation.
type: string
enum:
- CompanyPayType
- CompanyEarningType
benefits:
type: array
items:
description: >-
An array of benefits for the employee. Depends on your
company selections, benefits include 401k, health insurance
and more.
type: object
properties:
company_contribution_amount:
description: Company contribution amount towards the benefit
type: string
employee_deduction_amount:
description: Employee deduction amount towards the benefit
type: string
benefit_id:
description: The ID of the benefit.
type: integer
taxes:
description: >-
An array of taxes for the employee. Depends on your company
selections, taxes include federal income tax, social security,
medicare, and more.
type: array
items:
type: object
properties:
amount:
description: The amount of the tax.
type: string
tax_id:
description: The ID of the tax.
type: integer
ExternalPayrollsUpdateTaxLiabilitiesRequest:
type: object
properties:
liability_selections:
type: array
items:
description: ''
type: object
properties:
tax_id:
description: The ID of the tax.
type: integer
last_unpaid_external_payroll_uuid:
description: >-
The UUID of the last unpaid external payroll uuid. It should
be null when the full amount of tax liability has been paid.
type: string
nullable: true
unpaid_liability_amount:
description: A selection of unpaid liability amount.
type: number
PaymentConfigsUpdateCompanyPaymentConfigsRequest:
description: ''
type: object
properties:
fast_payment_limit:
description: >-
Fast payment limit. This limit is an aggregate of all fast payrolls
amount.
type: string
payment_speed:
description: >-
Gusto Embedded supports three payment speeds (1-day, 2-day, and
4-day). For next-day payments, funds are deposited in your team's
bank account by the end of the next business day. Most people will
see the funds arrive the next afternoon, but payments may arrive as
late as the end of the business day.
type: string
enum:
- 1-day
- 2-day
- 4-day
required:
- fast_payment_limit
- payment_speed
PaySchedulesCreateNewRequest:
description: ''
type: object
properties:
frequency:
description: >-
The frequency that employees on this pay schedule are paid with
Gusto.
type: string
enum:
- Every week
- Every other week
- Twice per month
- Monthly
anchor_pay_date:
description: >-
The first date that employees on this pay schedule are paid with
Gusto.
type: string
example: '2020-05-15'
anchor_end_of_pay_period:
description: >-
The last date of the first pay period. This can be the same date as
the anchor pay date.
type: string
example: '2020-05-08'
day_1:
description: >-
An integer between 1 and 31 indicating the first day of the month
that employees are paid. This field is only relevant for pay
schedules with the “Twice per month” and “Monthly” frequencies. It
will be null for pay schedules with other frequencies.
type: integer
nullable: true
day_2:
description: >-
An integer between 1 and 31 indicating the second day of the month
that employees are paid. This field is the second pay date for pay
schedules with the "Twice per month" frequency. For semi-monthly pay
schedules, set this field to 31. For months shorter than 31 days, we
will set the second pay date to the last day of the month. It will
be null for pay schedules with other frequencies.
type: integer
nullable: true
custom_name:
description: >-
A custom pay schedule name, defaults to the pay frequency
description.
type: string
required:
- frequency
- anchor_pay_date
- anchor_end_of_pay_period
PaySchedulesUpdatePayScheduleRequest:
description: ''
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer)
for information on how to use this field.
type: string
frequency:
description: >-
The frequency that employees on this pay schedule are paid with
Gusto.
type: string
enum:
- Every week
- Every other week
- Twice per month
- Monthly
anchor_pay_date:
description: >-
The first date that employees on this pay schedule are paid with
Gusto.
type: string
example: '2020-05-15'
anchor_end_of_pay_period:
description: >-
The last date of the first pay period. This can be the same date as
the anchor pay date.
type: string
example: '2020-05-08'
day_1:
description: >-
An integer between 1 and 31 indicating the first day of the month
that employees are paid. This field is only relevant for pay
schedules with the “Twice per month” and “Monthly” frequencies. It
will be null for pay schedules with other frequencies.
type: integer
nullable: true
day_2:
description: >-
An integer between 1 and 31 indicating the second day of the month
that employees are paid. This field is the second pay date for pay
schedules with the "Twice per month" frequency. For semi-monthly pay
schedules, set this field to 31. For months shorter than 31 days, we
will set the second pay date to the last day of the month. It will
be null for pay schedules with other frequencies.
type: integer
nullable: true
custom_name:
description: A custom pay schedule name.
type: string
auto_pilot:
description: >-
With Autopilot® enabled, payroll will run automatically one day
before your payroll deadlines.
type: boolean
required:
- version
EmployeesListCompanyEmployeesRequest:
type: object
properties: {}
EmployeesCreateEmployeeRequest:
description: ''
type: object
properties:
first_name:
type: string
middle_initial:
type: string
last_name:
type: string
date_of_birth:
type: string
email:
type: string
ssn:
type: string
pattern: '[0-9]{9}'
self_onboarding:
description: >-
If true, employee is expected to self-onboard. If false, payroll
admin is expected to enter in the employee's onboarding information
type: boolean
required:
- first_name
- last_name
DepartmentsCreateDepartmentRequest:
type: object
properties:
title:
type: string
DepartmentsUpdateDepartmentRequest:
type: object
properties:
title:
type: string
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer)
for information on how to use this field.
type: string
required:
- version
DepartmentsAddPeopleToDepartmentRequest:
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer)
for information on how to use this field.
type: string
employees:
description: Array of employees to add to the department
type: array
items:
properties:
uuid:
type: string
contractors:
description: Array of contractors to add to the department
type: array
items:
properties:
uuid:
type: string
DepartmentsRemovePeopleFromDepartmentRequest:
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer)
for information on how to use this field.
type: string
employees:
description: Array of employees to remove from a department
type: array
items:
properties:
uuid:
type: string
contractors:
description: Array of contractors to remove from a department
type: array
items:
properties:
uuid:
type: string
EmployeesUpdateEmployeeRequest:
description: ''
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer)
for information on how to use this field.
type: string
first_name:
type: string
middle_initial:
type: string
last_name:
type: string
date_of_birth:
type: string
email:
type: string
ssn:
type: string
pattern: '[0-9]{9}'
two_percent_shareholder:
description: >-
Whether the employee is a two percent shareholder of the company.
This field only applies to companies with an S-Corp entity type.
type: boolean
required:
- version
EmployeeEmploymentsCreateTerminationRequest:
description: ''
type: object
properties:
effective_date:
description: The employee's last day of work.
type: string
run_termination_payroll:
description: >-
If true, the employee should receive their final wages via an
off-cycle payroll. If false, they should receive their final wages
on their current pay schedule.
type: boolean
required:
- effective_date
EmployeeEmploymentsUpdateTerminationRequest:
allOf:
- $ref: '#/components/schemas/Versionable-Required'
- description: ''
type: object
properties:
effective_date:
description: The employee's last day of work.
type: string
run_termination_payroll:
description: >-
If true, the employee should receive their final wages via an
off-cycle payroll. If false, they should receive their final
wages on their current pay schedule.
type: boolean
required:
- effective_date
EmployeeEmploymentsUpdateRehireRequest:
allOf:
- $ref: '#/components/schemas/Versionable-Required'
- $ref: '#/components/schemas/Rehire-Body'
EmployeeAddressesCreateHomeAddressRequest:
description: ''
type: object
properties:
street_1:
type: string
street_2:
type: string
nullable: true
city:
type: string
state:
type: string
zip:
type: string
effective_date:
type: string
format: date
courtesy_withholding:
type: boolean
required:
- version
EmployeeAddressesUpdateHomeAddressRequest:
description: ''
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer)
for information on how to use this field.
type: string
street_1:
type: string
street_2:
type: string
nullable: true
city:
type: string
state:
type: string
zip:
type: string
effective_date:
type: string
format: date
courtesy_withholding:
type: boolean
required:
- version
EmployeeAddressesCreateWorkAddressRequest:
description: ''
type: object
properties:
location_uuid:
description: Reference to a company location
type: string
effective_date:
description: Date the employee began working at the company location
type: string
format: date
EmployeeAddressesUpdateWorkAddressRequest:
description: ''
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer)
for information on how to use this field.
type: string
location_uuid:
description: Reference to a company location
type: string
effective_date:
type: string
format: date
EmployeesUpdateOnboardingStatusRequest:
type: object
properties:
onboarding_status:
description: The updated onboarding status for the employee
type: string
required:
- onboarding_status
EmployeeTaxSetupUpdateFederalTaxesRequest:
description: ''
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer)
for information on how to use this field.
type: string
filing_status:
type: string
extra_withholding:
type: string
nullable: true
two_jobs:
type: boolean
dependents_amount:
type: string
other_income:
type: string
deductions:
type: string
w4_data_type:
type: string
required:
- version
EmployeeTaxSetupUpdateStateTaxesRequest:
description: ''
type: object
x-examples:
example-1:
states:
- state: CA
questions:
- key: filing_status
answers:
- value: M
valid_from: '2010-01-01'
valid_up_to: null
- key: withholding_allowance
answers:
- value: 2
valid_from: '2010-01-01'
valid_up_to: null
- key: additional_withholding
answers:
- value: '25.0'
valid_from: '2010-01-01'
valid_up_to: null
properties:
states:
type: array
uniqueItems: true
items:
type: object
properties:
state:
type: string
questions:
type: array
uniqueItems: true
items:
type: object
properties:
key:
type: string
answers:
type: array
uniqueItems: true
items:
type: object
properties:
value:
type: string
valid_from:
type: string
valid_up_to:
nullable: true
required:
- value
- valid_from
required:
- key
required:
- state
required:
- states
EmployeePaymentMethodListBankAccountsRequest:
type: object
properties: {}
EmployeePaymentMethodCreateBankAccountRequest:
type: object
properties:
name:
type: string
routing_number:
type: string
account_number:
type: string
account_type:
type: string
enum:
- Checking
- Savings
required:
- name
- routing_number
- account_number
- account_type
EmployeePaymentMethodUpdatePaymentMethodRequest:
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer)
for information on how to use this field.
type: string
type:
description: >-
The payment method type. If type is Check, then split_by and splits
do not need to be populated. If type is Direct Deposit, split_by and
splits are required.
type: string
enum:
- Direct Deposit
- Check
split_by:
description: >-
Describes how the payment will be split. If split_by is Percentage,
then the split amounts must add up to exactly 100. If split_by is
Amount, then the last split amount must be nil to capture the
remainder.
type: string
enum:
- Amount
- Percentage
splits:
type: array
items:
type: object
properties:
uuid:
description: |
The bank account ID
type: string
name:
description: The bank account name
type: string
priority:
description: >-
The order of priority for each payment split, with priority 1
being the first bank account paid. Priority must be unique and
sequential.
type: integer
split_amount:
description: The cents amount allocated for each payment split
type: integer
nullable: true
required:
- version
- type
JobsAndCompensationsCreateJobRequest:
description: ''
type: object
properties:
title:
description: The job title
type: string
hire_date:
description: The date when the employee was hired or rehired for the job.
type: string
two_percent_shareholder:
description: Whether the employee owns at least 2% of the company.
type: boolean
state_wc_covered:
description: >-
Whether this job is eligible for workers' compensation coverage in
the state of Washington (WA).
type: boolean
state_wc_class_code:
description: >-
The risk class code for workers' compensation in Washington state.
Please visit [Washington state's Risk Class
page](https://www.lni.wa.gov/insurance/rates-risk-classes/risk-classes-for-workers-compensation/risk-class-lookup#/)
to learn more.
type: string
required:
- title
- hire_date
JobsAndCompensationsUpdateJobRequest:
description: ''
type: object
properties:
title:
description: The job title
type: string
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer)
for information on how to use this field.
type: string
hire_date:
description: The date when the employee was hired or rehired for the job.
type: string
two_percent_shareholder:
description: Whether the employee owns at least 2% of the company.
type: boolean
state_wc_covered:
description: >-
Whether this job is eligible for workers' compensation coverage in
the state of Washington (WA).
type: boolean
state_wc_class_code:
description: >-
The risk class code for workers' compensation in Washington state.
Please visit [Washington state's Risk Class
page](https://www.lni.wa.gov/insurance/rates-risk-classes/risk-classes-for-workers-compensation/risk-class-lookup#/)
to learn more.
type: string
required:
- version
JobsAndCompensationsCreateCompensationRequest:
description: ''
type: object
properties:
rate:
description: The dollar amount paid per payment unit.
type: string
payment_unit:
description: >-
The unit accompanying the compensation rate. If the employee is an
owner, rate should be 'Paycheck'.
type: string
enum:
- Hour
- Week
- Month
- Year
- Paycheck
effective_date:
description: The date when the compensation takes effect.
type: string
flsa_status:
$ref: '#/components/schemas/Flsa-Status-Type'
adjust_for_minimum_wage:
description: >-
Determines whether the compensation should be adjusted for minimum
wage. Only applies to Nonexempt employees.
type: boolean
minimum_wages:
type: array
items:
description: The minimum wage record you want to apply to the compensation
type: object
properties:
uuid:
description: >-
The UUID of the minimum wage record. Required if
adjust_for_minimum_wage set to true
type: string
required:
- payment_unit
- flsa_status
JobsAndCompensationsUpdateCompensationRequest:
description: ''
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer)
for information on how to use this field.
type: string
rate:
description: The dollar amount paid per payment unit.
type: string
payment_unit:
description: >-
The unit accompanying the compensation rate. If the employee is an
owner, rate should be 'Paycheck'.
type: string
enum:
- Hour
- Week
- Month
- Year
- Paycheck
flsa_status:
$ref: '#/components/schemas/Flsa-Status-Type'
adjust_for_minimum_wage:
description: >-
Determines whether the compensation should be adjusted for minimum
wage. Only applies to Nonexempt employees.
type: boolean
minimum_wages:
type: array
items:
description: The minimum wage record you want to apply to the compensation
type: object
properties:
uuid:
description: >-
The UUID of the minimum wage record. Required if
adjust_for_minimum_wage set to true
type: string
required:
- version
EarningTypesCreateCustomEarningTypeRequest:
type: object
properties:
name:
description: The name of the custom earning type.
type: string
required:
- name
EarningTypesUpdateTypeRequest:
type: object
properties:
name:
description: The name of the custom earning type.
type: string
ContractorsCreateNewContractorRequest:
allOf:
- $ref: '#/components/schemas/Contractor-Body'
- required:
- type
- wage_type
- start_date
ContractorsUpdateContractorRequest:
allOf:
- $ref: '#/components/schemas/Versionable-Required'
- $ref: '#/components/schemas/Contractor-Body'
ContractorPaymentMethodCreateBankAccountRequest:
type: object
properties:
name:
type: string
routing_number:
type: string
account_number:
type: string
account_type:
type: string
enum:
- Checking
- Savings
required:
- name
- routing_number
- account_number
- account_type
WebhooksCreateSubscriptionRequest:
description: ''
type: object
properties:
url:
type: string
subscription_types:
type: array
items:
type: string
enum:
- BankAccount
- Company
- CompanyBenefit
- Contractor
- ContractorPayment
- Employee
- EmployeeBenefit
- EmployeeJobCompensation
- ExternalPayroll
- Form
- Location
- Notification
- Payroll
- PaySchedule
- Signatory
required:
- url
- subscription_types
WebhooksUpdateSubscriptionRequest:
description: ''
type: object
properties:
subscription_types:
type: array
items:
type: string
enum:
- BankAccount
- Company
- CompanyBenefit
- Contractor
- ContractorPayment
- Employee
- EmployeeBenefit
- EmployeeJobCompensation
- ExternalPayroll
- Form
- Location
- Notification
- Payroll
- PaySchedule
- Signatory
required:
- subscription_types
WebhooksVerifySubscriptionTokenRequest:
description: ''
type: object
properties:
verification_token:
description: The token POSTed to the Subscription URL.
type: string
required:
- verification_token
ContractorFormsCreate1099FormRequest:
type: object
properties:
contractor_id:
description: The contractor UUID.
type: string
year:
description: >
Must be equal to or more recent than 2015. If not specified,
defaults to the previous year.
type: integer
required:
- contractor_id
EmployeeFormsGenerateW2DocumentRequest:
type: object
properties:
employee_id:
description: The employee UUID.
type: string
year:
description: >
Must be equal to or more recent than 2015. If not specified,
defaults to the previous year.
type: integer
required:
- employee_id
ContractorPaymentMethodUpdateBankAccountRequest:
allOf:
- $ref: '#/components/schemas/Versionable-Required'
- type: object
properties:
type:
description: >-
The payment method type. If type is Direct Deposit, the
contractor is required to have a bank account.
see [Bank account
endpoint](./post-v1-contractors-contractor_uuid-bank_accounts)
type: string
enum:
- Direct Deposit
- Check
required:
- type
ContractorsChangeOnboardingStatusRequest:
type: object
properties:
onboarding_status:
description: The updated onboarding status for the employee
type: string
default: onboarding_completed
enum:
- onboarding_completed
required:
- onboarding_status
ContractorsUpdateAddressRequest:
allOf:
- $ref: '#/components/schemas/Versionable-Required'
- type: object
properties:
street_1:
type: string
street_2:
type: string
city:
type: string
state:
type: string
zip:
type: string
PayrollsCreateOffCyclePayrollRequest:
type: object
properties:
off_cycle:
description: Whether it is an off cycle payroll.
type: boolean
off_cycle_reason:
description: An off cycle payroll reason. Select one from the following list.
type: string
enum:
- Bonus
- Correction
- Dismissed employee
- Transition from old pay schedule
start_date:
description: Pay period start date.
type: string
end_date:
description: Pay period end date.
type: string
pay_schedule_uuid:
description: >-
A pay schedule is required for Transition from old pay schedule
payroll to identify the matching transition pay period.
type: string
employee_uuids:
description: A list of employee uuids to include on the payroll.
type: array
items:
type: string
check_date:
description: Payment date.
type: string
withholding_pay_period:
description: The payment schedule tax rate the payroll is based on
type: string
enum:
- Every week
- Every other week
- Twice per month
- Monthly
- Quarterly
- Semiannually
- Annually
skip_regular_deductions:
description: Block regular deductions and contributions for this payroll.
type: boolean
fixed_withholding_rate:
description: >-
Enable taxes to be withheld at the IRS's required rate of 22% for
federal income taxes. State income taxes will be taxed at the
state's supplemental tax rate. Otherwise, we'll sum the entirety of
the employee's wages and withhold taxes on the entire amount at the
rate for regular wages.
type: boolean
required:
- off_cycle
- off_cycle_reason
- start_date
- end_date
PayrollsUpdatePayrollByIdRequest:
type: object
properties:
employee_compensations:
type: array
items:
description: ''
type: object
properties:
version:
description: >-
The current version of this employee compensation from the
prepared payroll. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency)
for information on how to use this field.
type: string
employee_uuid:
description: The UUID of the employee.
type: string
excluded:
description: >-
This employee will be excluded from payroll calculation and
will not be paid for the payroll.
type: boolean
payment_method:
description: >-
The employee's compensation payment method. Invalid values
will be ignored.
type: string
enum:
- Direct Deposit
- Check
memo:
description: >-
Custom text that will be printed as a personal note to the
employee on a paystub.
type: string
fixed_compensations:
type: array
items:
description: >-
An array of fixed compensations for the employee. Fixed
compensations include tips, bonuses, and one time
reimbursements.
type: object
properties:
name:
description: >-
The name of the compensation. This also serves as the
unique, immutable identifier for this compensation.
type: string
amount:
description: The amount of the compensation for the pay period.
type: string
job_uuid:
description: The UUID of the job for the compensation.
type: integer
hourly_compensations:
type: array
items:
description: >-
An array of hourly compensations for the employee. Hourly
compensations include regular, overtime, and double overtime
hours.
type: object
properties:
name:
description: >-
The name of the compensation. This also serves as the
unique, immutable identifier for this compensation.
type: string
hours:
description: >-
The number of hours to be compensated for this pay
period.
type: string
job_uuid:
description: The UUIDs of the job for the compensation.
type: integer
paid_time_off:
description: >-
An array of all paid time off the employee is eligible for
this pay period. Each paid time off object can be the name or
the specific policy_uuid.
type: array
items:
type: object
properties:
name:
description: >-
The name of the PTO. This also serves as the unique,
immutable identifier for the PTO. Must pass in name or
policy_uuid but not both.
type: string
hours:
description: The hours of this PTO taken during the pay period.
type: string
policy_uuid:
description: >-
The uuid of the PTO policy. Must pass in name or
policy_uuid but not both.
type: string
final_payout_unused_hours_input:
description: >-
The outstanding hours paid upon termination. This field
is only applicable for termination payrolls.
type: string
required:
- employee_compensations
TimeOffPoliciesCalculateAccruingTimeOffHoursRequest:
description: ''
type: object
properties:
regular_hours_worked:
description: regular hours worked in this pay period
type: number
overtime_hours_worked:
description: overtime hours worked in this pay period
type: number
double_overtime_hours_worked:
description: double overtime hours worked in this pay period
type: number
pto_hours_used:
description: paid time off hours used in this pay period
type: number
sick_hours_used:
description: sick hours used in this pay period
type: number
PayrollsSkipPayrollRequest:
description: ''
type: object
properties:
payroll_type:
description: Payroll type
type: string
enum:
- Regular
- Hired employee
- Dismissed employee
- Transition from old pay schedule
start_date:
description: Pay period start date
type: string
end_date:
description: Pay period end date
type: string
pay_schedule_uuid:
description: The UUID of the pay schedule
type: string
employee_uuids:
description: >-
An array of employees. This field is only applicable to new hire
payroll and termination payroll
type: array
items:
type: string
required:
- payroll_type
PayrollsCalculateGrossUpRequest:
description: ''
type: object
properties:
employee_uuid:
description: Employee UUID
type: string
net_pay:
description: Employee net earnings
type: string
required:
- employee_uuid
- net_pay
ContractorPaymentsCreatePaymentRequest:
type: object
properties:
contractor_uuid:
description: The contractor receiving the payment
type: string
date:
description: The contractor receiving the payment
type: string
format: date
example: '2020-01-01'
payment_method:
type: string
enum:
- Direct Deposit
- Check
- Historical Payment
default: Direct Deposit
wage:
description: >-
If the contractor is on a fixed wage, this is the fixed wage payment
for the contractor, regardless of hours worked
type: number
example: 5000
hours:
description: >-
If the contractor is on an hourly wage, this is the number of hours
that the contractor worked for the payment
type: number
example: 40
bonus:
description: >-
If the contractor is on an hourly wage, this is the bonus the
contractor earned
type: number
example: 500
reimbursement:
description: Reimbursed wages for the contractor
type: number
example: 20
required:
- contractor_uuid
- date
CompanyFormsSignFormRequest:
description: ''
type: object
properties:
signature_text:
description: The signature
type: string
agree:
description: whether you agree to sign electronically
type: boolean
signed_by_ip_address:
description: The IP address of the signatory who signed the form.
type: string
required:
- signature_text
- agree
- signed_by_ip_address
EmployeeFormsSignFormRequest:
description: ''
type: object
properties:
signature_text:
description: The signature
type: string
agree:
description: whether you agree to sign electronically
type: boolean
signed_by_ip_address:
description: The IP address of the signatory who signed the form.
type: string
required:
- signature_text
- agree
- signed_by_ip_address
PayrollsGeneratePrintableChecksRequest:
type: object
properties:
printing_format:
description: >-
The type of check stock being printed. Check this
[link](https://support.gusto.com/article/999877761000000/Pay-your-team-by-check)
for more info on check types
type: string
starting_check_number:
description: The starting check number for the checks being generated
type: integer
required:
- printing_format
CompanyBenefitsCreateBenefitRequest:
description: ''
type: object
properties:
description:
description: >-
The description of the company benefit.For example, a company may
offer multiple benefits with an ID of 1 (for Medical Insurance). The
description would show something more specific like “Kaiser
Permanente” or “Blue Cross/ Blue Shield”.
type: string
benefit_type:
description: The ID of the benefit to which the company benefit belongs.
type: number
active:
description: Whether this benefit is active for employee participation.
type: boolean
default: true
responsible_for_employer_taxes:
description: >-
Whether the employer is subject to pay employer taxes when an
employee is on leave. Only applicable to third party sick pay
benefits.
type: boolean
responsible_for_employee_w2:
description: >-
Whether the employer is subject to file W-2 forms for an employee on
leave. Only applicable to third party sick pay benefits.
type: boolean
required:
- benefit_id
- description
CompanyBenefitsUpdateBenefitRequest:
description: ''
type: object
properties:
description:
description: >-
The description of the company benefit.For example, a company may
offer multiple benefits with an ID of 1 (for Medical Insurance). The
description would show something more specific like “Kaiser
Permanente” or “Blue Cross/ Blue Shield”.
type: string
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer)
for information on how to use this field.
type: string
active:
description: >-
Whether this benefit is active for employee participation. Company
benefits may only be deactivated if no employees are actively
participating.
type: boolean
required:
- version
EmployeeBenefitsCreateBenefitRecordRequest:
description: ''
type: object
properties:
company_benefit_uuid:
description: The UUID of the company benefit.
type: string
active:
description: Whether the employee benefit is active.
type: boolean
default: true
employee_deduction:
description: The amount to be deducted, per pay period, from the employee's pay.
type: string
default: '0.00'
deduct_as_percentage:
description: >-
Whether the employee deduction amount should be treated as a
percentage to be deducted from each payroll.
type: boolean
default: false
employee_deduction_annual_maximum:
description: >-
The maximum employee deduction amount per year. A null value
signifies no limit.
type: string
nullable: true
contribution:
description: An object representing the company contribution type and value.
type: object
properties:
type:
description: >-
The company contribution scheme.
`amount`: The company contributes a fixed amount per payroll. If
elective is true, the contribution is matching,
dollar-for-dollar.
`percentage`: The company contributes a percentage of the
payroll amount per payroll period. If elective is true, the
contribution is matching, dollar-for-dollar.
`tiered`: The size of the company contribution corresponds to
the size of the employee deduction relative to a tiered matching
scheme.
type: string
enum:
- tiered
- percentage
- amount
value:
description: >-
For the `amount` and `percentage` contribution types, the value
of the corresponding amount or percentage.
For the `tiered` contribution type, an array of tiers.
oneOf:
- description: >-
For the `amount` and `percentage` contribution types, the
value of the corresponding amount or percentage.
type: string
- description: For `tiered` contribution types, an array of tiers.
type: array
items:
description: A single tier of a tiered matching scheme.
type: object
properties:
rate:
description: >-
The percentage of employee deduction within this tier
the company contribution will match.
type: string
threshold:
description: >-
The percentage threshold at which this tier ends
(inclusive).
For example, a value of "5" means the company
contribution will match employee deductions from the
previous tier's threshold up to and including 5% of
payroll.
If this is the first tier, a value of "5" means the
company contribution will match employee deductions
from 0% up to and including 5% of payroll.
type: string
elective:
description: >-
Whether the company contribution is elective (aka "matching"). For
`tiered`, `elective_amount`, and `elective_percentage` contribution
types this is ignored and assumed to be `true`.
type: boolean
default: false
company_contribution_annual_maximum:
description: >-
The maximum company contribution amount per year. A null value
signifies no limit.
type: string
nullable: true
limit_option:
description: >-
Some benefits require additional information to determine their
limit. For example, for an HSA benefit, the limit option should be
either "Family" or "Individual". For a Dependent Care FSA benefit,
the limit option should be either "Joint Filing or Single" or
"Married and Filing Separately".
type: string
nullable: true
catch_up:
description: >-
Whether the employee should use a benefit’s "catch up" rate. Only
Roth 401k and 401k benefits use this value for employees over 50.
type: boolean
default: false
coverage_amount:
description: >-
The amount that the employee is insured for. Note: company
contribution cannot be present if coverage amount is set.
type: string
nullable: true
coverage_salary_multiplier:
description: >-
The coverage amount as a multiple of the employee’s salary. Only
applicable for Group Term Life benefits. Note: cannot be set if
coverage amount is also set.
type: string
default: '0.00'
deduction_reduces_taxable_income:
description: >-
Whether the employee deduction reduces taxable income or not. Only
valid for Group Term Life benefits. Note: when the value is not
"unset", coverage amount and coverage salary multiplier are ignored.
type: string
enum:
- unset
- reduces_taxable_income
- does_not_reduce_taxable_income
- null
nullable: true
company_contribution:
description: The amount to be paid, per pay period, by the company.
type: string
default: '0.00'
deprecated: true
contribute_as_percentage:
description: >-
Whether the company contribution amount should be treated as a
percentage to be deducted from each payroll.
type: boolean
default: false
deprecated: true
required:
- company_benefit_uuid
EmployeeBenefitsUpdateBenefitRecordRequest:
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer)
for information on how to use this field.
type: string
active:
description: Whether the employee benefit is active.
type: boolean
employee_deduction:
description: The amount to be deducted, per pay period, from the employee's pay.
type: string
default: '0.00'
deduct_as_percentage:
description: >-
Whether the employee deduction amount should be treated as a
percentage to be deducted from each payroll.
type: boolean
employee_deduction_annual_maximum:
description: >-
The maximum employee deduction amount per year. A null value
signifies no limit.
type: string
nullable: true
contribution:
description: >-
An object representing the type and value of the company
contribution.
type: object
properties:
type:
description: >-
The company contribution scheme.
`amount`: The company contributes a fixed amount per payroll. If
elective is true, the contribution is matching,
dollar-for-dollar.
`percentage`: The company contributes a percentage of the
payroll amount per payroll period. If elective is true, the
contribution is matching, dollar-for-dollar.
`tiered`: The size of the company contribution corresponds to
the size of the employee deduction relative to a tiered matching
scheme.
type: string
enum:
- amount
- percentage
- tiered
value:
description: >-
For the `amount` and `percentage` contribution types, the value
of the corresponding amount or percentage.
For the `tiered` contribution type, an array of tiers.
oneOf:
- description: >-
For the `amount` and `percentage` contribution types, the
value of the corresponding amount or percentage.
type: string
- description: For `tiered` contribution types, an array of tiers.
type: array
items:
description: A single tier of a tiered matching scheme.
type: object
properties:
rate:
description: >-
The percentage of employee deduction within this tier
the company contribution will match.
type: string
threshold:
description: >-
The percentage threshold at which this tier ends
(inclusive).
For example, a value of "5" means the company
contribution will match employee deductions from the
previous tier's threshold up to and including 5% of
payroll.
If this is the first tier, a value of "5" means the
company contribution will match employee deductions
from 0% up to and including 5% of payroll.
type: string
elective:
description: >-
Whether the company contribution is elective (aka "matching"). For
`tiered`, `elective_amount`, and `elective_percentage` contribution
types this is ignored and assumed to be `true`.
type: boolean
default: false
company_contribution_annual_maximum:
description: >-
The maximum company contribution amount per year. A null value
signifies no limit.
type: string
nullable: true
limit_option:
description: >-
Some benefits require additional information to determine their
limit. For example, for an HSA benefit, the limit option should be
either "Family" or "Individual". For a Dependent Care FSA benefit,
the limit option should be either "Joint Filing or Single" or
"Married and Filing Separately".
type: string
nullable: true
catch_up:
description: >-
Whether the employee should use a benefit’s "catch up" rate. Only
Roth 401k and 401k benefits use this value for employees over 50.
type: boolean
default: false
coverage_amount:
description: >-
The amount that the employee is insured for. Note: company
contribution cannot be present if coverage amount is set.
type: string
nullable: true
deduction_reduces_taxable_income:
description: >-
Whether the employee deduction reduces taxable income or not. Only
valid for Group Term Life benefits. Note: when the value is not
"unset", coverage amount and coverage salary multiplier are ignored.
type: string
default: unset
enum:
- unset
- reduces_taxable_income
- does_not_reduce_taxable_income
- null
nullable: true
coverage_salary_multiplier:
description: >-
The coverage amount as a multiple of the employee’s salary. Only
applicable for Group Term Life benefits. Note: cannot be set if
coverage amount is also set.
type: string
default: '0.00'
company_contribution:
description: The amount to be paid, per pay period, by the company.
type: string
default: '0.00'
deprecated: true
contribute_as_percentage:
description: >-
Whether the company contribution amount should be treated as a
percentage to be deducted from each payroll.
type: boolean
default: false
deprecated: true
required:
- version
EmployeeBenefitsCreateYtdBenefitAmountsFromDifferentCompanyRequest:
type: object
properties:
benefit_type:
description: The benefit type supported by Gusto.
type: number
tax_year:
description: The tax year for which this amount applies.
type: number
minimum: 2000
maximum: 2999
ytd_employee_deduction_amount:
description: >-
The year-to-date employee deduction made outside the current
company.
type: string
default: '0.00'
ytd_company_contribution_amount:
description: >-
The year-to-date company contribution made outside the current
company.
type: string
default: '0.00'
required:
- benefit_id
- tax_year
- ytd_employee_deduction_amount
- ytd_company_contribution_amount
GarnishmentsCreateGarnishmentRequest:
description: ''
type: object
properties:
description:
description: The description of the garnishment.
type: string
readOnly: false
active:
description: Whether or not this garnishment is currently active.
type: boolean
default: true
amount:
description: >-
The amount of the garnishment. Either a percentage or a fixed dollar
amount. Represented as a float, e.g. "8.00".
type: string
format: float
readOnly: false
court_ordered:
description: Whether the garnishment is court ordered.
type: boolean
readOnly: false
times:
description: >-
The number of times to apply the garnishment. Ignored if recurring
is true.
type: integer
readOnly: false
default: null
nullable: true
recurring:
description: Whether the garnishment should recur indefinitely.
type: boolean
readOnly: false
default: false
annual_maximum:
description: >-
The maximum deduction per annum. A null value indicates no maximum.
Represented as a float, e.g. "200.00".
format: float
readOnly: false
default: null
nullable: true
type: string
pay_period_maximum:
description: >-
The maximum deduction per pay period. A null value indicates no
maximum. Represented as a float, e.g. "16.00".
type: string
format: float
default: null
nullable: true
deduct_as_percentage:
description: >-
Whether the amount should be treated as a percentage to be deducted
per pay period.
type: boolean
readOnly: false
default: false
required:
- amount
- description
- court_ordered
GarnishmentsUpdateGarnishmentRequest:
type: object
properties:
description:
description: The description of the garnishment.
type: string
readOnly: false
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer)
for information on how to use this field.
type: string
active:
description: Whether or not this garnishment is currently active.
type: boolean
default: true
amount:
description: >-
The amount of the garnishment. Either a percentage or a fixed dollar
amount. Represented as a float, e.g. "8.00".
type: string
format: float
readOnly: false
court_ordered:
description: Whether the garnishment is court ordered.
type: boolean
readOnly: false
times:
description: >-
The number of times to apply the garnishment. Ignored if recurring
is true.
type: integer
readOnly: false
default: null
nullable: true
recurring:
description: Whether the garnishment should recur indefinitely.
type: boolean
readOnly: false
default: false
annual_maximum:
description: >-
The maximum deduction per annum. A null value indicates no maximum.
Represented as a float, e.g. "200.00".
format: float
readOnly: false
default: null
nullable: true
type: string
pay_period_maximum:
description: >-
The maximum deduction per pay period. A null value indicates no
maximum. Represented as a float, e.g. "16.00".
type: string
format: float
default: null
nullable: true
deduct_as_percentage:
description: >-
Whether the amount should be treated as a percentage to be deducted
per pay period.
type: boolean
readOnly: false
default: false
required:
- version
BankAccountsCreateFromPlaidTokenRequest:
type: object
required:
- owner_type
- owner_id
- processor_token
properties:
owner_type:
description: The owner type of the bank account
type: string
enum:
- Company
owner_id:
description: The owner uuid of the bank account
type: string
processor_token:
description: The Plaid processor token
type: string
TaxRequirementsUpdateStateTaxesRequest:
type: object
x-examples:
example-1:
requirement_sets:
- key: registrations
effective_from: null
state: GA
requirements:
- key: 71653ec0-00b5-4c66-a58b-22ecf21704c5
value: 1233214-AB
- key: 6c0911ab-5860-412e-bdef-6437cd881df5
value: 474747-22
- key: taxrates
effective_from: '2022-01-01'
state: GA
requirements:
- key: e0ac2284-8d30-4100-ae23-f85f9574868b
value: '0.05'
- key: depositschedules
effective_from: '2022-01-01'
state: GA
requirements:
- key: 6ddfcbeb-94d3-4003-bfc2-8c6e1ca9f70c
value: Semi-weekly
properties:
requirement_sets:
type: array
items:
type: object
properties:
key:
$ref: '#/components/schemas/Tax-Requirement-Set-Key'
effective_from:
$ref: '#/components/schemas/Tax-Requirement-Effective-From'
state:
$ref: '#/components/schemas/State'
requirements:
type: array
items:
type: object
properties:
key:
$ref: '#/components/schemas/Tax-Requirement-Key'
value:
type: string
nullable: true
ContractorPaymentsPreviewDebitDateRequest:
type: object
x-examples:
example-1:
contractor_payments:
- bonus: 0
check_date: 2022-09-2
contractor_uuid: 5376e95b-cca0-482b-bb81-aba5e360eb04
hours: 0
payment_method: Check
reimbursement: 0
wage: 123
hourly_rate: 0
- bonus: 0
check_date: 2022-09-2
contractor_uuid: 0c984dce-de9a-47db-8bfb-5f0c823afe6f
hours: 0
payment_method: Check
reimbursement: 0
wage: 456
hourly_rate: 0
properties:
contractor_payments:
type: array
items:
type: object
properties:
bonus:
type: integer
contractor_uuid:
type: string
date:
type: string
hourly_rate:
type: integer
hours:
type: integer
payment_method:
type: string
reimbursement:
type: integer
wage:
type: integer
ContractorPaymentsPreviewDebitDateRequest1:
type: object
properties: {}
TimeOffPoliciesUpdatePolicyRequest:
type: object
x-examples:
example-1:
name: test policy3
accrual_method: per_calendar_year
accrual_rate: '120.0'
properties:
name:
description: Name of the time off policy
type: string
accrual_method:
description: Accrual method of the time off policy
type: string
enum:
- unlimited
- per_pay_period
- per_calendar_year
- per_anniversary_year
- per_hour_worked
- per_hour_worked_no_overtime
- per_hour_paid
- per_hour_paid_no_overtime
accrual_rate:
description: >-
The rate at which the time off hours will accrue for an employee on
the policy. Represented as a float, e.g. "40.0".
type: string
format: float
accrual_rate_unit:
description: >-
The number of hours an employee has to work or be paid for to accrue
the number of hours set in the accrual rate. Only used for hourly
policies (per_hour_paid, per_hour_paid_no_overtime, per_hour_work,
per_hour_worked_no_overtime). Represented as a float, e.g. "40.0".
type: string
format: float
paid_out_on_termination:
description: >-
Boolean representing if an employees accrued time off hours will be
paid out on termination
type: boolean
accrual_waiting_period_days:
description: >-
Number of days before an employee on the policy will begin accruing
time off hours
type: integer
carryover_limit_hours:
description: >-
The max number of hours and employee can carryover from one year to
the next
type: string
format: float
max_accrual_hours_per_year:
description: The max number of hours and employee can accrue in a year
type: string
format: float
max_hours:
description: The max number of hours an employee can accrue
type: string
format: float
TimeOffPoliciesCreatePolicyRequest:
type: object
x-examples:
example-1:
name: test policy3
policy_type: sick
properties:
name:
description: Name of the time off policy
type: string
policy_type:
description: >-
Type of the time off policy. Currently only "vacation" and "sick"
are supported
type: string
accrual_method:
description: Accrual method of the time off policy
type: string
enum:
- unlimited
- per_pay_period
- per_calendar_year
- per_anniversary_year
- per_hour_worked
- per_hour_worked_no_overtime
- per_hour_paid
- per_hour_paid_no_overtime
accrual_rate:
description: >-
The rate at which the time off hours will accrue for an employee on
the policy. Represented as a float, e.g. "40.0".
type: string
format: float
accrual_rate_unit:
description: >-
The number of hours an employee has to work or be paid for to accrue
the number of hours set in the accrual rate. Only used for hourly
policies (per_hour_paid, per_hour_paid_no_overtime, per_hour_work,
per_hour_worked_no_overtime). Represented as a float, e.g. "40.0".
type: string
format: float
paid_out_on_termination:
description: >-
Boolean representing if an employees accrued time off hours will be
paid out on termination
type: boolean
accrual_waiting_period_days:
description: >-
Number of days before an employee on the policy will begin accruing
time off hours
type: integer
carryover_limit_hours:
description: >-
The max number of hours and employee can carryover from one year to
the next
type: string
format: float
max_accrual_hours_per_year:
description: The max number of hours and employee can accrue in a year
type: string
format: float
max_hours:
description: The max number of hours an employee can accrue
type: string
format: float
required:
- name
- policy_type
- accrual_method
TimeOffPoliciesAddEmployeesToPolicyRequest:
type: object
properties:
employees:
type: array
items:
type: object
properties:
uuid:
type: string
balance:
type: string
format: float
x-examples:
example-1:
employees:
- uuid: c61d1895-5cf8-4217-88c8-20d7c3132a04
TimeOffPoliciesRemoveEmployeesRequest:
type: object
properties:
employees:
type: array
items:
type: object
properties:
uuid:
type: string
x-examples:
example-1:
employees:
- uuid: c61d1895-5cf8-4217-88c8-20d7c3132a04
HolidayPayPoliciesCreateCompanyPolicyRequest:
type: object
properties:
federal_holidays:
description: >-
An object containing federal holiday objects, each containing a
boolean selected property.
type: object
properties:
new_years_day:
type: object
properties:
selected:
type: boolean
mlk_day:
type: object
properties:
selected:
type: boolean
presidents_day:
type: object
properties:
selected:
type: boolean
memorial_day:
type: object
properties:
selected:
type: boolean
juneteenth:
type: object
properties:
selected:
type: boolean
independence_day:
type: object
properties:
selected:
type: boolean
labor_day:
type: object
properties:
selected:
type: boolean
columbus_day:
type: object
properties:
selected:
type: boolean
veterans_day:
type: object
properties:
selected:
type: boolean
thanksgiving:
type: object
properties:
selected:
type: boolean
christmas_day:
type: object
properties:
selected:
type: boolean
HolidayPayPoliciesUpdatePolicyRequest:
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
federal_holidays:
description: >-
An object containing federal holiday objects, each containing a
boolean selected property.
type: object
properties:
new_years_day:
type: object
properties:
selected:
type: boolean
mlk_day:
type: object
properties:
selected:
type: boolean
presidents_day:
type: object
properties:
selected:
type: boolean
memorial_day:
type: object
properties:
selected:
type: boolean
juneteenth:
type: object
properties:
selected:
type: boolean
independence_day:
type: object
properties:
selected:
type: boolean
labor_day:
type: object
properties:
selected:
type: boolean
columbus_day:
type: object
properties:
selected:
type: boolean
veterans_day:
type: object
properties:
selected:
type: boolean
thanksgiving:
type: object
properties:
selected:
type: boolean
christmas_day:
type: object
properties:
selected:
type: boolean
required:
- version
HolidayPayPoliciesAddEmployeesToPolicyRequest:
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
employees:
description: An array of employee objects, each containing an employee_uuid.
type: array
items:
type: object
properties:
uuid:
type: string
required:
- version
HolidayPayPoliciesRemoveEmployeesRequest:
type: object
properties:
version:
description: >-
The current version of the object. See the [versioning
guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for
information on how to use this field.
type: string
employees:
description: An array of employee objects, each containing an employee_uuid.
type: array
items:
type: object
properties:
uuid:
type: string
required:
- version
HolidayPayPoliciesPreviewCompanyPaidHolidaysRequest:
type: object
properties:
year:
description: >-
If a year is passed, paid holidays for that year will be returned.
Otherwise, paid holidays for the next three years will be returned.
type: string
TimeOffPoliciesUpdateEmployeeBalanceRequest:
type: object
properties:
employees:
type: array
items:
type: object
properties:
uuid:
type: string
balance:
type: string
format: float
x-examples:
example-1:
employees:
- uuid: c61d1895-5cf8-4217-88c8-20d7c3132a04
balance: '40.0'
IntrospectionGetCurrentAccessTokenInfoResponse:
description: ''
type: object
properties:
scope:
description: Space delimited string of accessible scopes.
type: string
resource:
description: Information about the token resource.
type: object
properties:
type:
description: Type of object
type: string
uuid:
description: UUID of object
type: string
CompaniesCreatePartnerManagedCompanyResponse:
description: Object returned when creating a partner managed company
type: object
properties:
access_token:
description: >-
Access token that can be used for OAuth access to the account.
Access tokens expire 2 hours after they are issued.
type: string
readOnly: true
refresh_token:
description: Refresh token that can be exchanged for a new access token.
type: string
readOnly: true
company_uuid:
description: Gusto’s UUID for the company
type: string
readOnly: true
expires_in:
description: Time of access_token expiration in seconds
type: integer
readOnly: true
CompaniesMigrateToEmbeddedPayrollResponse:
description: ''
type: object
properties:
company_uuid:
description: The company UUID
type: string
migration_status:
description: The migration status
type: string
CompaniesAcceptTermsOfServiceResponse:
description: ''
type: object
properties:
latest_terms_accepted:
description: Whether the latest terms have been accepted by the user.
type: boolean
CompaniesGetTermsOfServiceStatusResponse:
description: ''
type: object
properties:
latest_terms_accepted:
description: Whether the latest terms have been accepted by the user.
type: boolean
required:
- email
- ip_address
- external_user_id
CompaniesGetAllAdminsResponse:
type: array
items:
$ref: '#/components/schemas/Admin'
SignatoriesGetCompanySignatoriesResponse:
type: array
items:
$ref: '#/components/schemas/Signatory'
CompaniesGetCustomFieldsResponse:
type: object
properties:
custom_fields:
type: array
items:
$ref: '#/components/schemas/Company-Custom-Field'
LocationsGetCompanyLocationsResponse:
type: array
items:
$ref: '#/components/schemas/Location'
LocationsGetMinimumWagesResponse:
type: array
items:
$ref: '#/components/schemas/Minimum-Wage'
BankAccountsListCompanyBankAccountsResponse:
type: array
items:
$ref: '#/components/schemas/Company-Bank-Account'
ExternalPayrollsListForCompanyResponse:
type: array
items:
$ref: '#/components/schemas/External-Payroll-Basic'
ExternalPayrollsGetTaxSuggestionsResponse:
type: array
items:
$ref: '#/components/schemas/External-Payroll-Tax-Suggestions'
ExternalPayrollsGetTaxLiabilitiesResponse:
type: array
items:
$ref: '#/components/schemas/Tax-Liabilities-Selections'
PaySchedulesListForCompanyResponse:
type: array
items:
$ref: '#/components/schemas/Pay-Schedule'
PaySchedulesPreviewPayScheduleDatesResponse:
description: Pay schedule preview
type: object
properties:
pay_periods:
description: A list of pay periods for the previewed pay schedule
type: array
items:
type: object
properties:
check_date:
description: The payment date, "Check date", for the pay period
type: string
run_payroll_by:
description: >-
The deadline to run payroll for direct deposit on the check
date
type: string
start_date:
description: The first day of the pay period
type: string
end_date:
description: The last day of the pay period
type: string
holidays:
description: A list of dates for bank closures
type: array
items:
type: string
PaySchedulesGetPayPeriodsResponse:
type: array
items:
$ref: '#/components/schemas/Pay-Period'
PaySchedulesGetUnprocessedTerminationPayPeriodsResponse:
type: array
items:
$ref: '#/components/schemas/Unprocessed-Termination-Pay-Period'
EmployeesListCompanyEmployeesResponse:
type: array
items:
$ref: '#/components/schemas/Employee'
DepartmentsGetAllWithEmployeesResponse:
type: array
items:
$ref: '#/components/schemas/Department'
EmployeeEmploymentsListEmployeeTerminationsResponse:
type: array
items:
$ref: '#/components/schemas/Termination'
EmployeeEmploymentsGetHistoryResponse:
type: array
items:
type: object
properties:
hire_date:
description: The employee's start day of work for an employment.
type: string
termination_date:
description: The employee's last day of work for an employment.
type: string
file_new_hire_report:
description: >-
The boolean flag indicating whether Gusto will file a new hire
report for the employee.
type: boolean
two_percent_shareholder:
description: >-
Whether the employee is a two percent shareholder of the company.
This field only applies to companies with an S-Corp entity type.
type: boolean
employment_status:
description: >-
The employee's employment status. Supplying an invalid option will
set the employment_status to *not_set*.
type: string
enum:
- part_time
- full_time
- part_time_eligible
- variable
- seasonal
- not_set
x-examples:
example-1:
hire_date: '2023-01-30'
termination_date: '2023-03-30'
file_new_hire_report: false
two_percent_shareholder: false
employment_status: seasonal
EmployeeAddressesGetHomeAddressesResponse:
type: array
items:
$ref: '#/components/schemas/Employee-Address'
EmployeeAddressesListWorkAddressesResponse:
type: array
items:
$ref: '#/components/schemas/Employee-Work-Address'
EmployeesGetCustomFieldsResponse:
type: object
properties:
custom_fields:
type: array
items:
$ref: '#/components/schemas/Employee-Custom-Field'
EmployeesGetOnboardingStatusResponse:
type: object
properties: {}
EmployeeTaxSetupGetStateTaxesResponse:
type: array
items:
$ref: '#/components/schemas/Employee-State-Tax'
EmployeeTaxSetupUpdateStateTaxesResponse:
description: ''
type: array
uniqueItems: true
x-examples:
example-1:
- state: CA
questions:
- key: filing_status
answers:
- valid_from: '2010-01-01'
valid_up_to: null
errors:
- string
items:
type: object
properties:
state:
type: string
questions:
type: array
uniqueItems: true
items:
type: object
properties:
key:
type: string
answers:
type: array
uniqueItems: true
items:
type: object
properties:
valid_from:
type: string
valid_up_to:
nullable: true
errors:
type: array
items:
type: string
required:
- valid_from
required:
- key
required:
- state
- questions
EmployeePaymentMethodListBankAccountsResponse:
type: array
items:
$ref: '#/components/schemas/Employee-Bank-Account'
JobsAndCompensationsGetEmployeeJobsResponse:
type: array
items:
$ref: '#/components/schemas/Job'
JobsAndCompensationsGetJobCompensationsResponse:
type: array
items:
$ref: '#/components/schemas/Compensation'
JobsAndCompensationsCreateCompensationResponse:
type: object
properties: {}
EarningTypesGetAllResponse:
type: object
properties:
default:
description: The default earning types for the company.
type: array
items:
$ref: '#/components/schemas/Earning-Type'
custom:
description: The custom earning types for the company.
type: array
items:
$ref: '#/components/schemas/Earning-Type'
ContractorsGetCompanyContractorsResponse:
type: array
items:
$ref: '#/components/schemas/Contractor'
ContractorPaymentMethodListBankAccountsResponse:
type: array
items:
$ref: '#/components/schemas/Contractor-Bank-Account'
ContractorPaymentMethodCreateBankAccountResponse:
type: object
properties: {}
WebhooksListSubscriptionsResponse:
type: array
items:
$ref: '#/components/schemas/Webhook-Subscription'
ContractorFormsListAllResponse:
type: array
items:
$ref: '#/components/schemas/Form_1099'
EmployeeFormsGenerateW2DocumentResponse:
allOf:
- properties:
employee_uuid:
description: The UUID of the employee
type: string
readOnly: true
- $ref: '#/components/schemas/Form'
ContractorsGetOnboardingStatusResponse:
type: object
properties: {}
PayrollsGetCompanyPayrollsResponse:
type: array
items:
$ref: '#/components/schemas/Payroll-Minimal'
TimeOffPoliciesCalculateAccruingTimeOffHoursResponse:
type: array
items:
$ref: '#/components/schemas/Accruing-Time-Off-Hour'
PayrollsGetAllPayrollBlockersResponse:
type: array
items:
$ref: '#/components/schemas/Payroll-Blocker'
PayrollsSkipPayrollResponse:
oneOf:
- $ref: '#/components/schemas/Unprocessable-Entity-Error-Object'
- $ref: '#/components/schemas/Payroll-Blockers-Error'
PayrollsCalculateGrossUpResponse:
oneOf:
- $ref: '#/components/schemas/Unprocessable-Entity-Error-Object'
- $ref: '#/components/schemas/Payroll-Blockers-Error'
PayrollsCalculateGrossUp422Response:
oneOf:
- $ref: '#/components/schemas/Unprocessable-Entity-Error-Object'
- $ref: '#/components/schemas/Payroll-Blockers-Error'
PayrollsSubmitPayrollResponse:
oneOf:
- $ref: '#/components/schemas/Unprocessable-Entity-Error-Object'
- $ref: '#/components/schemas/Payroll-Blockers-Error'
ContractorPaymentsGetWithinTimePeriodTotalsResponse:
oneOf:
- $ref: '#/components/schemas/Contractor-Payment-Summary'
- $ref: '#/components/schemas/Contractor-Payment-Summary-By-Dates'
CompanyFormsGetAllFormsResponse:
type: array
items:
$ref: '#/components/schemas/Form'
PayrollsGetEmployeePayStubsResponse:
type: array
items:
$ref: '#/components/schemas/Employee-Pay-Stub'
CompanyBenefitsGetBenefitsForCompanyResponse:
type: array
items:
$ref: '#/components/schemas/Company-Benefit'
CompanyBenefitsDeleteBenefitResponse:
type: object
properties:
errors:
type: object
properties:
base:
type: array
items:
type: object
properties:
type:
type: string
message:
type: string
full_message:
type: string
CompanyBenefitsListSupportedBenefitsResponse:
type: array
items:
$ref: '#/components/schemas/Supported-Benefit'
EmployeeBenefitsGetAllForEmployeeResponse:
type: array
items:
$ref: '#/components/schemas/Employee-Benefit'
GarnishmentsGetEmployeeGarnishmentsResponse:
type: array
items:
$ref: '#/components/schemas/Garnishment'
BankAccountsCreateFromPlaidTokenResponse:
oneOf:
- $ref: '#/components/schemas/Company-Bank-Account'
TaxRequirementsGetStatesResponse:
type: array
x-examples:
example-1:
- state: CA
setup_complete: true
- state: GA
setup_complete: false
items:
type: object
properties:
state:
$ref: '#/components/schemas/State'
setup_complete:
description: >-
If all requirements for the state have been satisfied such that
the company can complete
onboarding, the company is `setup_complete` in the state. A
company must be `setup_complete` in
all relevant states to complete the `state_setup` company
onboarding step.
type: boolean
ContractorPaymentsPreviewDebitDateResponse:
type: object
properties:
expected_debit_date:
description: >-
The calculated debit date. If the payment method is Direct Deposit,
the debit date will account for the company's ACH speed. If the
payment method is Check, the debit date will be the same as the
check date.
type: string
x-examples:
example-1:
expected_debit_date: '2022-08-16'
ContractorPaymentsPreviewDebitDate422Response:
type: object
properties:
errors:
type: object
properties:
base:
type: array
items:
type: object
properties:
type:
type: string
message:
type: string
full_message:
type: string
check_date:
type: array
items:
type: object
properties:
type:
type: string
message:
type: string
full_message:
type: string
x-examples:
example-1:
errors:
base:
- type: Invalid Object
message: Please enter a contractor payment before continuing.
full_message: Please enter a contractor payment before continuing.
check_date:
- type: Invalid Object
message: Please enter a contractor payment before continuing.
full_message: Please enter a contractor payment before continuing.
TimeOffPoliciesGetAllPoliciesResponse:
type: array
items:
$ref: '#/components/schemas/Time-Off-Policy'
EventsGet30DayEventsResponse:
type: array
items:
$ref: '#/components/schemas/Event'
RecoveryCasesListForCompanyResponse:
type: array
items:
$ref: '#/components/schemas/Recovery-Case'
AchTransactionsGetAllForCompanyResponse:
type: array
items:
$ref: '#/components/schemas/Ach-Transaction'
securitySchemes:
Authorization:
description: The access token
type: http
scheme: bearer
ApiKeyAuth:
description: Enter your token in the format **Token **
type: apiKey
in: header
name: Authorization
requestBodies:
post-employee-ytd-benefit-amounts-from-different-company:
content:
application/json:
schema:
$ref: >-
#/components/schemas/EmployeeBenefitsCreateYtdBenefitAmountsFromDifferentCompanyRequest
security:
- Authorization: []
x-readme:
explorer-enabled: true
proxy-enabled: true
_id: 65de5576cf8f57001d7c50f2