Query structured spec data via REST or MCP. Get exactly what your agent needs.
https://api.gusto-demo.com
https://api.gusto.com
No endpoints found for this provider.
Accruing-Time-Off-Hour
{
"type": "object",
"properties": {
"hours": {
"type": "string",
"description": "Hours accrued during this pay period."
},
"time_off_policy_uuid": {
"type": "string",
"description": "A unique identifier of the time off policy."
}
},
"description": "The representation of an unprocessed termination pay period."
}
Ach-Transaction
{
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "Unique identifier of an ACH transaction"
},
"amount": {
"type": "string",
"description": "The amount of money moved by the ACH transaction. This amount is always non-negative."
},
"error_code": {
"type": "string",
"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."
},
"description": {
"type": "string",
"description": "The description of the ACH transaction. Can be used to identify the ACH transaction on the recipient's bank statement."
},
"company_uuid": {
"type": "string",
"description": "Unique identifier of the company to which the ACH transaction belongs"
},
"payment_date": {
"type": "string",
"description": "The date of the payment associated with the ACH transaction"
},
"payment_status": {
"enum": [
"unsubmitted",
"submitted",
"successful",
"failed"
],
"type": "string",
"description": "The status of the ACH transaction"
},
"recipient_type": {
"enum": [
"Employee",
"Contractor"
],
"type": "string",
"description": "The type of recipient associated with the ACH transaction"
},
"recipient_uuid": {
"type": "string",
"description": "Unique identifier for the recipient associated with the ACH transaction"
},
"transaction_type": {
"type": "string",
"description": "The type of transaction associated with the ACH transaction"
},
"payment_direction": {
"enum": [
"credit",
"debit"
],
"type": "string",
"description": "The direction of the payment"
},
"payment_event_type": {
"enum": [
"Payroll",
"ContractorPayment"
],
"type": "string",
"description": "The type of payment event associated with the ACH transaction"
},
"payment_event_uuid": {
"type": "string",
"description": "Unique identifier for the payment event associated with the ACH transaction"
},
"payment_event_check_date": {
"type": "string",
"description": "The date of the payment event check associated with the ACH transaction"
}
},
"x-examples": {
"example": {
"uuid": "123e4567-e89b-12d3-a456-426655440000,",
"amount": "123.00,",
"error_code": "null,",
"description": "PAY 380654",
"company_uuid": "456e7890-e12b-34c5-d678-901234567890,",
"payment_date": "2023-10-17,",
"payment_status": "submitted,",
"recipient_type": "Employee,",
"recipient_uuid": "012e3456-f78d-90ab-12cd-345678901234,",
"transaction_type": "Credit employee pay,",
"payment_direction": "credit,",
"payment_event_type": "Payroll,",
"payment_event_uuid": "789e0123-e45f-67ab-c890-123456789012,",
"payment_event_check_date": "2023-10-02,"
}
},
"description": "Representation of an ACH transaction"
}
AchTransactionsGetAllForCompanyResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Ach-Transaction"
}
}
Address
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Versionable"
},
{
"type": "object",
"properties": {
"zip": {
"type": "string",
"readOnly": false
},
"city": {
"type": "string",
"readOnly": false
},
"state": {
"type": "string",
"readOnly": false
},
"active": {
"type": "boolean",
"readOnly": true,
"description": "The status of the location. Inactive locations have been deleted, but may still have historical data associated with them."
},
"country": {
"type": "string",
"default": "USA",
"readOnly": false
},
"street_1": {
"type": "string",
"readOnly": false
},
"street_2": {
"type": "string",
"nullable": true,
"readOnly": false
}
}
}
],
"example": {
"zip": "94107",
"city": "San Francisco",
"state": "CA",
"active": true,
"country": "USA",
"street_1": "412 Kiera Stravenue",
"street_2": "Suite 391"
}
}
Admin
{
"type": "object",
"title": "Admin",
"x-tags": [
"Admins"
],
"properties": {
"uuid": {
"type": "string",
"description": "The unique id of the admin."
},
"email": {
"type": "string",
"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."
},
"last_name": {
"type": "string",
"description": "The last name of the admin."
},
"first_name": {
"type": "string",
"description": "The first name of the admin."
}
},
"x-examples": {
"Example": {
"uuid": "987058cc-23ee-46e9-81ef-5cee086cceca",
"email": "jsmith99@gmail.com",
"last_name": "Smith",
"first_name": "John"
}
},
"description": "The representation of an admin user in Gusto."
}
Authentication
{
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "All of the scopes for which the access token provides access."
},
"created_at": {
"type": "string",
"description": "Datetime for when the new access token is created."
},
"expires_in": {
"type": "number",
"default": 7200,
"description": "The TTL of this token. After this amount of time, you must hit the refresh token endpoint to continue making authenticated requests."
},
"token_type": {
"type": "string",
"default": "bearer",
"description": "The literal string 'bearer'"
},
"access_token": {
"type": "string",
"description": "A new access token that can be used for subsequent authenticated requests"
},
"refresh_token": {
"type": "string",
"description": "A token that must be passed to the refresh token endpoint to get a new authenticated token."
}
},
"description": ""
}
BankAccountsCreateFromPlaidTokenRequest
{
"type": "object",
"required": [
"owner_type",
"owner_id",
"processor_token"
],
"properties": {
"owner_id": {
"type": "string",
"description": "The owner uuid of the bank account"
},
"owner_type": {
"enum": [
"Company"
],
"type": "string",
"description": "The owner type of the bank account"
},
"processor_token": {
"type": "string",
"description": "The Plaid processor token"
}
}
}
BankAccountsCreateFromPlaidTokenResponse
{
"oneOf": [
{
"$ref": "#/components/schemas/Company-Bank-Account"
}
]
}
BankAccountsCreateVerificationDepositsRequest
{
"type": "object",
"properties": {
"account_type": {
"enum": [
"Checking",
"Savings"
],
"type": "string",
"nullable": false,
"description": "The bank account type"
},
"account_number": {
"type": "string",
"nullable": false,
"description": "The bank account number"
},
"routing_number": {
"type": "string",
"nullable": false,
"description": "The bank routing number"
}
},
"description": ""
}
BankAccountsListCompanyBankAccountsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Company-Bank-Account"
}
}
BankAccountsVerifyMicroDepositsRequest
{
"type": "object",
"properties": {
"deposit_1": {
"type": "number",
"nullable": false,
"description": "The dollar amount of the first micro-deposit"
},
"deposit_2": {
"type": "number",
"nullable": false,
"description": "The dollar amount of the second micro-deposit"
}
},
"description": ""
}
Benefit-Summary
{
"type": "object",
"x-tags": [
"Company Benefits"
],
"properties": {
"end_date": {
"type": "string",
"description": "The end date of benefit summary."
},
"employees": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "The UUID of the employee"
},
"gross_pay": {
"type": "string",
"description": "Gross pay of this pay check."
},
"payroll_benefits": {
"type": "object",
"properties": {
"gross_pay": {
"type": "string"
},
"check_date": {
"type": "string"
},
"pay_period": {
"type": "object",
"properties": {
"end_date": {
"type": "string"
},
"start_date": {
"type": "string"
}
}
},
"payroll_type": {
"type": "string",
"description": "Whether it is regular or bonus payroll"
},
"payroll_uuid": {
"type": "string"
},
"company_benefit_deduction": {
"type": "string"
},
"company_benefit_contribution": {
"type": "string"
}
}
},
"benefit_deduction": {
"type": "string",
"description": "Sum of employee benefit deduction given the period of time for this specific employee."
},
"benefit_contribution": {
"type": "string",
"description": "Sum of company contribution given the period of time for this specific employee."
},
"company_benefit_deduction": {
"type": "string",
"description": "The aggregate of employee deduction for all employees given the period of time and benefit type."
},
"company_benefit_contribution": {
"type": "string",
"description": "The aggregate of company contribution for all employees given the period of time and benefit type."
}
},
"description": ""
},
"start_date": {
"type": "string",
"description": "The start date of benefit summary."
},
"description": {
"type": "string",
"description": "Description of the benefit."
},
"company_benefit_deduction": {
"type": "string",
"description": "The aggregate of employee deduction for all employees given the period of time and benefit type."
},
"company_benefit_contribution": {
"type": "string",
"description": "The aggregate of company contribution for all employees given the period of time and benefit type."
}
},
"description": ""
}
Benefit-Type-Requirements
{
"type": "object",
"x-tags": [
"Company Benefits"
],
"properties": {
"catch_up": {
"type": "object",
"properties": {
"choices": {
"type": "array",
"items": {
"type": "string"
}
},
"editable": {
"type": "boolean"
},
"required": {
"type": "boolean"
},
"default_value": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
},
"description": ""
},
"contribution": {
"type": "object",
"properties": {
"choices": {
"type": "array",
"items": {
"type": "string"
}
},
"editable": {
"type": "boolean"
},
"required": {
"type": "boolean"
},
"default_value": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
},
"description": ""
},
"limit_option": {
"type": "object",
"properties": {
"choices": {
"type": "array",
"items": {
"type": "string"
}
},
"editable": {
"type": "boolean"
},
"required": {
"type": "boolean"
},
"default_value": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
},
"description": ""
},
"coverage_amount": {
"type": "object",
"properties": {
"choices": {
"type": "array",
"items": {
"type": "string"
}
},
"editable": {
"type": "boolean"
},
"required": {
"type": "boolean"
},
"default_value": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
},
"description": ""
},
"employee_deduction": {
"type": "object",
"properties": {
"choices": {
"type": "array",
"items": {
"type": "string"
}
},
"editable": {
"type": "boolean"
},
"required": {
"type": "boolean"
},
"default_value": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
},
"description": ""
},
"deduct_as_percentage": {
"type": "object",
"properties": {
"choices": {
"type": "array",
"items": {
"type": "string"
}
},
"editable": {
"type": "boolean"
},
"required": {
"type": "boolean"
},
"default_value": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
},
"description": ""
},
"coverage_salary_multiplier": {
"type": "object",
"properties": {
"choices": {
"type": "array",
"items": {
"type": "string"
}
},
"editable": {
"type": "boolean"
},
"required": {
"type": "boolean"
},
"default_value": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
},
"description": ""
},
"company_contribution_annual_maximum": {
"type": "object",
"properties": {
"choices": {
"type": "array",
"items": {
"type": "string"
}
},
"editable": {
"type": "boolean"
},
"required": {
"type": "boolean"
},
"default_value": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
},
"description": ""
}
},
"description": ""
}
CompaniesAcceptTermsOfServiceRequest
{
"type": "object",
"required": [
"email",
"ip_address",
"external_user_id"
],
"properties": {
"email": {
"type": "string",
"description": "The user's email address on Gusto. You can retrieve the user's email via company's `/admins`, `/employees`, `/signatories`, and `/contractors` endpoints."
},
"ip_address": {
"type": "string",
"description": "The IP address of the user who viewed and accepted the Terms of Service."
},
"external_user_id": {
"type": "string",
"description": "The user ID on your platform."
}
}
}
CompaniesAcceptTermsOfServiceResponse
{
"type": "object",
"properties": {
"latest_terms_accepted": {
"type": "boolean",
"description": "Whether the latest terms have been accepted by the user."
}
},
"description": ""
}
CompaniesCreateAdminRequest
{
"type": "object",
"required": [
"first_name",
"last_name",
"email"
],
"properties": {
"email": {
"type": "string",
"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."
},
"last_name": {
"type": "string",
"description": "The last name of the admin."
},
"first_name": {
"type": "string",
"description": "The first name of the admin."
}
},
"description": ""
}
CompaniesCreatePartnerManagedCompanyRequest
{
"type": "object",
"required": [
"user",
"company"
],
"properties": {
"user": {
"type": "object",
"required": [
"first_name",
"last_name",
"email"
],
"properties": {
"email": {
"type": "string",
"description": "The email of the user who will be the primary payroll admin."
},
"phone": {
"type": "string",
"description": "The phone number of the user who will be the primary payroll admin."
},
"last_name": {
"type": "string",
"description": "The last name of the user who will be the primary payroll admin."
},
"first_name": {
"type": "string",
"description": "The first name of the user who will be the primary payroll admin."
}
},
"description": "Information for the user who will be the primary payroll administrator for the new company."
},
"company": {
"type": "object",
"required": [
"name"
],
"properties": {
"ein": {
"type": "string",
"description": "The employer identification number (EIN) of the company."
},
"name": {
"type": "string",
"description": "The legal name of the company."
},
"trade_name": {
"type": "string",
"description": "The name of the company."
}
}
}
}
}
CompaniesCreatePartnerManagedCompanyResponse
{
"type": "object",
"properties": {
"expires_in": {
"type": "integer",
"readOnly": true,
"description": "Time of access_token expiration in seconds"
},
"access_token": {
"type": "string",
"readOnly": true,
"description": "Access token that can be used for OAuth access to the account. Access tokens expire 2 hours after they are issued."
},
"company_uuid": {
"type": "string",
"readOnly": true,
"description": "Gusto’s UUID for the company"
},
"refresh_token": {
"type": "string",
"readOnly": true,
"description": "Refresh token that can be exchanged for a new access token."
}
},
"description": "Object returned when creating a partner managed company"
}
CompaniesGetAllAdminsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Admin"
}
}
CompaniesGetCustomFieldsResponse
{
"type": "object",
"properties": {
"custom_fields": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company-Custom-Field"
}
}
}
}
CompaniesGetTermsOfServiceStatusRequest
{
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"description": "The user's email address on Gusto. You can retrieve the user's email via company's `/admins`, `/employees`, `/signatories`, and `/contractors` endpoints."
}
}
}
CompaniesGetTermsOfServiceStatusResponse
{
"type": "object",
"required": [
"email",
"ip_address",
"external_user_id"
],
"properties": {
"latest_terms_accepted": {
"type": "boolean",
"description": "Whether the latest terms have been accepted by the user."
}
},
"description": ""
}
CompaniesMigrateToEmbeddedPayrollRequest
{
"type": "object",
"required": [
"email",
"ip_address",
"external_user_id"
],
"properties": {
"email": {
"type": "string",
"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."
},
"ip_address": {
"type": "string",
"description": "The IP address of the signatory who viewed and accepted the Terms of Service."
},
"external_user_id": {
"type": "string",
"description": "The signatory's user ID on your platform."
}
}
}
CompaniesMigrateToEmbeddedPayrollResponse
{
"type": "object",
"properties": {
"company_uuid": {
"type": "string",
"description": "The company UUID"
},
"migration_status": {
"type": "string",
"description": "The migration status"
}
},
"description": ""
}
Company
{
"type": "object",
"title": "Company",
"x-tags": [
"Companies"
],
"properties": {
"ein": {
"type": "string",
"readOnly": true,
"description": "The Federal Employer Identification Number of the company."
},
"name": {
"type": "string",
"readOnly": true,
"description": "The name of the company."
},
"slug": {
"type": "string",
"readOnly": true,
"description": "The slug of the name of the company."
},
"tier": {
"enum": [
"simple",
"plus",
"premium",
"core",
"complete",
"concierge",
"contractor_only",
"basic"
],
"type": "string",
"nullable": true,
"readOnly": true,
"description": "The Gusto product tier of the company (not applicable to Embedded partner managed companies)."
},
"uuid": {
"type": "string",
"readOnly": true,
"description": "A unique identifier of the company in Gusto."
},
"join_date": {
"type": "string",
"readOnly": true,
"description": "Company's first invoiceable event date"
},
"locations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Company-Address"
},
"readOnly": true,
"description": "The locations of the company.",
"uniqueItems": false
},
"trade_name": {
"type": "string",
"readOnly": true,
"description": "The trade name of the company."
},
"entity_type": {
"enum": [
"C-Corporation",
"S-Corporation",
"Sole proprietor",
"LLC",
"LLP",
"Limited partnership",
"Co-ownership",
"Association",
"Trusteeship",
"General partnership",
"Joint venture",
"Non-Profit"
],
"type": "string",
"readOnly": true,
"description": "The tax payer type of the company."
},
"funding_type": {
"enum": [
"ach",
"reverse_wire",
"wire_in",
"brex"
],
"type": "string",
"description": "Company's default funding type"
},
"is_suspended": {
"type": "boolean",
"description": "Whether or not the company is suspended in Gusto. Suspended companies may not run payroll."
},
"compensations": {
"type": "object",
"readOnly": true,
"properties": {
"fixed": {
"type": "array",
"items": {
"type": "object",
"readOnly": true,
"properties": {
"name": {
"type": "string",
"example": "Bonus",
"description": "The name of the fixed compensation."
}
}
},
"readOnly": true,
"description": "The available fixed compensation rates for the company.",
"uniqueItems": true
},
"hourly": {
"type": "array",
"items": {
"type": "object",
"readOnly": true,
"properties": {
"name": {
"type": "string",
"example": "Overtime",
"readOnly": true,
"description": "The name of the hourly compensation rate."
},
"multiple": {
"type": "number",
"example": 1.5,
"readOnly": true,
"description": "The amount multiplied by the base rate of a job to calculate compensation."
}
}
},
"readOnly": true,
"description": "The available hourly compensation rates for the company.",
"uniqueItems": true
},
"paid_time_off": {
"type": "array",
"items": {
"type": "object",
"readOnly": true,
"properties": {
"name": {
"type": "string",
"example": "Vacation Hours",
"readOnly": true,
"description": "The name of the paid time off type."
}
}
},
"readOnly": true,
"description": "The available types of paid time off for the company.",
"uniqueItems": true
}
},
"description": "The available company-wide compensation rates for the company."
},
"company_status": {
"enum": [
"Approved",
"Not Approved",
"Suspended"
],
"type": "string",
"readOnly": true,
"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."
},
"pay_schedule_type": {
"enum": [
"single",
"hourly_salaried",
"by_employee",
"by_department"
],
"type": "string",
"readOnly": true,
"description": "The pay schedule assignment type."
},
"primary_signatory": {
"type": "object",
"readOnly": true,
"properties": {
"email": {
"type": "string",
"readOnly": true
},
"phone": {
"type": "string",
"readOnly": true
},
"last_name": {
"type": "string",
"readOnly": true
},
"first_name": {
"type": "string",
"readOnly": true
},
"home_address": {
"type": "object",
"readOnly": true,
"properties": {
"zip": {
"type": "string",
"readOnly": true
},
"city": {
"type": "string",
"readOnly": true
},
"state": {
"type": "string",
"readOnly": true
},
"country": {
"type": "string",
"readOnly": true
},
"street_1": {
"type": "string",
"readOnly": true
},
"street_2": {
"type": "string",
"nullable": true,
"readOnly": true
}
}
},
"middle_initial": {
"type": "string",
"readOnly": true
}
},
"description": "The primary signatory of the company."
},
"is_partner_managed": {
"type": "boolean",
"readOnly": true,
"description": "Whether the company is fully managed by a partner via the API"
},
"primary_payroll_admin": {
"type": "object",
"properties": {
"email": {
"type": "string",
"readOnly": true
},
"phone": {
"type": "string",
"readOnly": true
},
"last_name": {
"type": "string",
"readOnly": true
},
"first_name": {
"type": "string",
"readOnly": true
}
},
"description": "The primary payroll admin of the company."
}
},
"x-examples": {
"Example": {
"ein": "00-0000001",
"name": "Shoppe Studios LLC",
"tier": "complete",
"locations": [
{
"zip": "94107",
"city": "San Francisco",
"state": "CA",
"active": true,
"country": "USA",
"street_1": "412 Kiera Stravenue",
"street_2": "Suite 391"
},
{
"zip": "23218",
"city": "Richmond",
"state": "VA",
"active": true,
"country": "USA",
"street_1": "644 Fay Vista",
"street_2": "Suite 842"
}
],
"trade_name": "Record Shoppe",
"entity_type": "C-Corporation",
"is_suspended": false,
"compensations": {
"fixed": [
{
"name": "Bonus"
},
{
"name": "Commission"
},
{
"name": "Paycheck Tips"
},
{
"name": "Cash Tips"
},
{
"name": "Correction Payment"
},
{
"name": "Severance"
},
{
"name": "Minimum Wage Adjustment"
},
{
"name": "Reimbursement"
}
],
"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
}
],
"paid_time_off": [
{
"name": "Vacation Hours"
},
{
"name": "Sick Hours"
},
{
"name": "Holiday Hours"
}
]
},
"company_status": "Approved",
"pay_schedule_type": "by_department",
"primary_signatory": {
"email": "louie.hessel7757869450111547@zemlak.biz",
"phone": null,
"last_name": "Carter",
"first_name": "Alda",
"home_address": {
"zip": "94107",
"city": "San Francisco",
"state": "CA",
"country": "USA",
"street_1": "524 Roob Divide",
"street_2": "Suite 565"
},
"middle_initial": ""
},
"is_partner_managed": false,
"primary_payroll_admin": {
"email": "louie.hessel7757869450111547@zemlak.biz",
"phone": "1-565-710-7559",
"last_name": "Labadie",
"first_name": "Ian"
}
}
},
"description": "The representation of a company in Gusto."
}
Company-Address
{
"type": "object",
"title": "",
"x-tags": [
"Locations"
],
"properties": {
"zip": {
"type": "string",
"readOnly": false
},
"city": {
"type": "string",
"readOnly": false
},
"state": {
"type": "string",
"readOnly": false
},
"active": {
"type": "boolean",
"readOnly": true,
"description": "The status of the location. Inactive locations have been deleted, but may still have historical data associated with them."
},
"country": {
"type": "string",
"default": "USA",
"readOnly": false
},
"street_1": {
"type": "string",
"readOnly": false
},
"street_2": {
"type": "string",
"nullable": true,
"readOnly": false
}
},
"x-examples": {
"Company Address": {
"zip": "94107",
"city": "San Francisco",
"state": "CA",
"active": true,
"country": "USA",
"street_1": "412 Kiera Stravenue",
"street_2": "Suite 391"
}
},
"description": "The representation of a company's address in Gusto."
}
Company-Bank-Account
{
"type": "object",
"x-tags": [
"Company Bank Accounts"
],
"properties": {
"name": {
"type": "string",
"description": "Name of bank account"
},
"uuid": {
"type": "string",
"description": "UUID of the bank account"
},
"account_type": {
"enum": [
"Checking",
"Savings"
],
"type": "string",
"description": "Bank account type"
},
"company_uuid": {
"type": "string",
"description": "UUID of the company"
},
"plaid_status": {
"enum": [
"connected",
"disconnected"
],
"type": "string",
"description": "The Plaid connection status of the bank account. Only applies when verification type is Plaid."
},
"routing_number": {
"type": "string",
"description": "The bank account's routing number"
},
"verification_type": {
"enum": [
"bank_deposits",
"plaid",
"plaid_external"
],
"type": "string",
"description": "The verification type of the bank account.\n\n'bank_deposits' means the bank account is connected by entering routing and accounting numbers and verifying through micro-deposits.\n'plaid' means the bank account is connected through Plaid."
},
"last_cached_balance": {
"type": "string",
"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."
},
"verification_status": {
"enum": [
"awaiting_deposits",
"ready_for_verification",
"verified"
],
"type": "string",
"description": "The verification status of the bank account.\n\n'awaiting_deposits' means the bank account is just created and money is being transferred.\n'ready_for_verification' means the micro-deposits are completed and the verification process can begin by using the verify endpoint.\n'verified' means the bank account is verified."
},
"balance_fetched_date": {
"type": "string",
"description": "The balance fetch date associated with the last_cached_balance. Only applies when verification type is Plaid."
},
"hidden_account_number": {
"type": "string",
"description": "Masked bank account number"
}
},
"x-examples": {
"Example": {
"name": "Employer Funding Account",
"uuid": "1263eae5-4411-48d9-bd6d-18ed93082e65",
"account_type": "Checking",
"company_uuid": "e2c4c0ce-2986-48b9-86cf-ec27f6ed9a36",
"routing_number": "851070439",
"verification_type": "bank_deposits",
"verification_status": "verified",
"hidden_account_number": "XXXX4087"
}
},
"description": "The company bank account"
}
Company-Benefit
{
"type": "object",
"properties": {
"uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the company benefit."
},
"active": {
"type": "boolean",
"default": true,
"description": "Whether this benefit is active for employee participation. Company benefits may only be deactivated if no employees are actively participating."
},
"version": {
"type": "string",
"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."
},
"deletable": {
"type": "boolean",
"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"
},
"description": {
"type": "string",
"minLength": 1,
"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”."
},
"benefit_type": {
"type": "number",
"readOnly": true,
"description": "The type of the benefit to which the company benefit belongs."
},
"responsible_for_employee_w2": {
"type": "boolean",
"description": "Whether the employer is subject to file W-2 forms for an employee on leave. Only applicable to third party sick pay benefits."
},
"supports_percentage_amounts": {
"type": "boolean",
"readOnly": true,
"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."
},
"responsible_for_employer_taxes": {
"type": "boolean",
"description": "Whether the employer is subject to pay employer taxes when an employee is on leave. Only applicable to third party sick pay benefits."
}
},
"x-examples": {
"Example": {
"uuid": "54e37c27-43e6-4ae5-a5b2-e29895a133be",
"active": true,
"version": "98jr3289h3298hr9329gf9egskt3kagri32qqgiqe3872",
"deletable": true,
"description": "Kaiser Permanente",
"benefit_type": 1,
"responsible_for_employee_w2": false,
"supports_percentage_amounts": true,
"responsible_for_employer_taxes": false
}
},
"description": "The representation of a company benefit."
}
Company-Benefit-With-Employee-Benefits
{
"type": "object",
"properties": {
"uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the company benefit."
},
"active": {
"type": "boolean",
"default": true,
"description": "Whether this benefit is active for employee participation. Company benefits may only be deactivated if no employees are actively participating."
},
"version": {
"type": "string",
"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."
},
"deletable": {
"type": "boolean",
"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"
},
"description": {
"type": "string",
"minLength": 1,
"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”."
},
"benefit_type": {
"type": "number",
"readOnly": true,
"description": "The type of the benefit to which the company benefit belongs (same as benefit_id)."
},
"employee_benefits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uuid": {
"type": "string"
},
"active": {
"type": "boolean",
"default": true,
"description": "Whether the employee benefit is active."
},
"contribution": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The company contribution scheme.\n\n\"amount\": The company contributes a fixed amount per payroll. If elective is true, the contribution is matching, dollar-for-dollar.\n\n\"percentage\": The company contributes a percentage of the payroll amount per payroll period. If elective is true, the contribution is matching, dollar-for-dollar.\n\n\"tiered\": The company contribution varies according to the size of the employee deduction."
},
"value": {
"oneOf": [
{
"type": "string"
},
{
"type": "object",
"properties": {
"tiers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rate": {
"type": "string",
"description": "The percentage of employee deduction within this tier the company contribution will match."
},
"threshold": {
"type": "string",
"description": "The percentage threshold at which this tier ends (inclusive).\n\nFor 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.\n\nIf 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."
},
"threshold_delta": {
"type": "string",
"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."
}
},
"description": "A single tier of a tiered matching scheme."
},
"description": ""
}
}
}
],
"description": "For the `amount` and `percentage` contribution types, the value of the corresponding amount or percentage.\n\nFor the `tiered` contribution type, an array of tiers."
}
},
"description": "An object representing the type and value of the company contribution."
},
"employee_uuid": {
"type": "string",
"description": "The UUID of the employee to which the benefit belongs."
},
"employee_deduction": {
"type": "string",
"default": "0.00",
"description": "The amount to be deducted, per pay period, from the employee's pay."
},
"company_benefit_uuid": {
"type": "string",
"description": "The UUID of the company benefit."
},
"company_contribution": {
"type": "string",
"description": "The value of the company contribution"
},
"deduct_as_percentage": {
"type": "boolean",
"default": false,
"description": "Whether the employee deduction amount should be treated as a percentage to be deducted from each payroll."
}
}
}
},
"responsible_for_employee_w2": {
"type": "boolean",
"description": "Whether the employer is subject to file W-2 forms for an employee on leave. Only applicable to third party sick pay benefits."
},
"supports_percentage_amounts": {
"type": "boolean",
"readOnly": true,
"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."
},
"responsible_for_employer_taxes": {
"type": "boolean",
"description": "Whether the employer is subject to pay employer taxes when an employee is on leave. Only applicable to third party sick pay benefits."
}
},
"x-examples": {
"Example": {
"uuid": "54e37c27-43e6-4ae5-a5b2-e29895a133be",
"active": true,
"version": "98jr3289h3298hr9329gf9egskt3kagri32qqgiqe3872",
"deletable": true,
"description": "Kaiser Permanente",
"benefit_type": 1,
"responsible_for_employee_w2": false,
"supports_percentage_amounts": true,
"responsible_for_employer_taxes": false
}
},
"description": "The representation of a company benefit."
}
Company-Custom-Field
{
"type": "object",
"x-tags": [
"Custom Fields"
],
"required": [
"uuid",
"name",
"type"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the company custom field"
},
"type": {
"$ref": "#/components/schemas/Custom-Field-Type"
},
"uuid": {
"type": "string",
"description": "UUID of the company custom field"
},
"description": {
"type": "string",
"description": "Description of the company custom field"
},
"selection_options": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true,
"description": "An array of options for fields of type radio. Otherwise, null."
}
},
"description": "A custom field on a company"
}
Company-Onboarding-Status
{
"type": "object",
"title": "",
"x-tags": [
"Companies"
],
"properties": {
"": {
"type": "string"
},
"uuid": {
"type": "string",
"description": "the UUID of the company"
},
"onboarding_steps": {
"type": "array",
"items": {
"type": "object",
"title": "Onboarding step",
"properties": {
"id": {
"type": "string",
"description": "The string identifier for each onboarding step"
},
"title": {
"type": "string",
"description": "The display name of the onboarding step"
},
"required": {
"type": "boolean",
"description": "The boolean flag indicating whether the step is required or optional"
},
"completed": {
"type": "boolean",
"description": "The boolean flag indicating whether the step is completed or not."
},
"skippable": {
"type": "boolean",
"description": "The boolean flag indicating whether the step can be skipped or not."
},
"requirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of onboarding step that are required to be completed in order to proceed with the current onboarding step."
}
}
},
"description": "a list of company onboarding steps"
},
"onboarding_completed": {
"type": "boolean",
"description": "a boolean flag for the company's onboarding status"
}
},
"x-examples": {
"Example": {
"uuid": "c44d66dc-c41b-4a60-9e25-5e93ff8583f2",
"onboarding_steps": [
{
"id": "add_addresses",
"title": "Add Your Company's Addresses",
"required": true,
"completed": true,
"skippable": false,
"requirements": []
},
{
"id": "add_employees",
"title": "Add Your Employees",
"required": true,
"completed": true,
"skippable": true,
"requirements": [
"add_addresses"
]
},
{
"id": "federal_tax_setup",
"title": "Enter Your Federal Tax Information",
"required": true,
"completed": true,
"skippable": false,
"requirements": [
"add_addresses",
"add_employees"
]
},
{
"id": "add_bank_info",
"title": "Add Your Bank Account",
"required": true,
"completed": true,
"skippable": false,
"requirements": []
},
{
"id": "payroll_schedule",
"title": "Select a Pay Schedule",
"required": true,
"completed": false,
"skippable": false,
"requirements": []
},
{
"id": "sign_all_forms",
"title": "Sign Documents",
"required": true,
"completed": false,
"skippable": false,
"requirements": [
"add_employees",
"federal_tax_setup",
"state_setup",
"add_bank_info",
"payroll_schedule"
]
},
{
"id": "verify_bank_info",
"title": "Verify Your Bank Account",
"required": true,
"completed": false,
"skippable": false,
"requirements": [
"add_bank_info"
]
}
],
"onboarding_completed": false
}
},
"description": "The representation of a company's onboarding status"
}
CompanyBenefitsCreateBenefitRequest
{
"type": "object",
"required": [
"benefit_id",
"description"
],
"properties": {
"active": {
"type": "boolean",
"default": true,
"description": "Whether this benefit is active for employee participation."
},
"description": {
"type": "string",
"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”."
},
"benefit_type": {
"type": "number",
"description": "The ID of the benefit to which the company benefit belongs."
},
"responsible_for_employee_w2": {
"type": "boolean",
"description": "Whether the employer is subject to file W-2 forms for an employee on leave. Only applicable to third party sick pay benefits."
},
"responsible_for_employer_taxes": {
"type": "boolean",
"description": "Whether the employer is subject to pay employer taxes when an employee is on leave. Only applicable to third party sick pay benefits."
}
},
"description": ""
}
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"
}
}
}
}
}
}
}
}
CompanyBenefitsGetBenefitsForCompanyResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Company-Benefit"
}
}
CompanyBenefitsListSupportedBenefitsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Supported-Benefit"
}
}
CompanyBenefitsUpdateBenefitRequest
{
"type": "object",
"required": [
"version"
],
"properties": {
"active": {
"type": "boolean",
"description": "Whether this benefit is active for employee participation. Company benefits may only be deactivated if no employees are actively participating."
},
"version": {
"type": "string",
"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."
},
"description": {
"type": "string",
"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”."
}
},
"description": ""
}
CompanyFormsGetAllFormsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Form"
}
}
CompanyFormsSignFormRequest
{
"type": "object",
"required": [
"signature_text",
"agree",
"signed_by_ip_address"
],
"properties": {
"agree": {
"type": "boolean",
"description": "whether you agree to sign electronically"
},
"signature_text": {
"type": "string",
"description": "The signature"
},
"signed_by_ip_address": {
"type": "string",
"description": "The IP address of the signatory who signed the form."
}
},
"description": ""
}
Compensation
{
"type": "object",
"x-tags": [
"Jobs and Compensations"
],
"properties": {
"rate": {
"type": "string",
"readOnly": false,
"description": "The dollar amount paid per payment unit."
},
"uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the compensation in Gusto."
},
"version": {
"type": "string",
"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."
},
"job_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the job to which the compensation belongs."
},
"flsa_status": {
"$ref": "#/components/schemas/Flsa-Status-Type"
},
"payment_unit": {
"enum": [
"Hour",
"Week",
"Month",
"Year",
"Paycheck"
],
"type": "string",
"readOnly": false,
"description": "The unit accompanying the compensation rate. If the employee is an owner, rate should be 'Paycheck'."
},
"effective_date": {
"type": "string",
"readOnly": false,
"description": "The effective date for this compensation. For the first compensation, this defaults to the job's hire date."
},
"adjust_for_minimum_wage": {
"type": "boolean",
"readOnly": true,
"description": "Indicates if the compensation could be adjusted to minimum wage during payroll calculation."
}
},
"x-examples": {
"Example": {
"rate": "70.00",
"uuid": "910b675b-af99-404e-b8d8-562a72b76b44",
"version": "98jr3289h3298hr9329gf9egskt3kagri32qqgiqe3872",
"job_uuid": "fe9d72aa-11aa-4f6c-ba3b-4de14598cff6",
"flsa_status": "Nonexempt",
"payment_unit": "Hour",
"effective_date": "2020-12-11",
"adjust_for_minimum_wage": false
}
},
"description": "The representation of compensation in Gusto."
}
Contractor
{
"type": "object",
"x-tags": [
"Contractors"
],
"properties": {
"ein": {
"type": "string",
"nullable": true,
"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": {
"enum": [
"Individual",
"Business"
],
"type": "string",
"description": "The contractor's type, either \"Individual\" or \"Business\". "
},
"uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the contractor in Gusto."
},
"email": {
"type": "string",
"nullable": true,
"description": "The contractor’s email address. This attribute is optional for “Individual” contractors and will be ignored for “Business” contractors. "
},
"address": {
"type": "object",
"readOnly": true,
"properties": {
"zip": {
"type": "string",
"readOnly": true
},
"city": {
"type": "string",
"readOnly": true
},
"state": {
"type": "string",
"readOnly": true
},
"country": {
"type": "string",
"readOnly": true
},
"street_1": {
"type": "string",
"readOnly": true
},
"street_2": {
"type": "string",
"nullable": true,
"readOnly": true
}
},
"description": "The contractor’s home address."
},
"has_ein": {
"type": "boolean",
"nullable": true,
"description": "Whether company's Employer Identification Number (EIN) is present"
},
"version": {
"type": "string",
"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."
},
"is_active": {
"type": "boolean",
"default": true,
"readOnly": true,
"description": "The status of the contractor with the company."
},
"last_name": {
"type": "string",
"nullable": true,
"description": "The contractor’s last name. This attribute is required for “Individual” contractors and will be ignored for “Business” contractors."
},
"onboarded": {
"type": "boolean",
"description": "The updated onboarding status for the contractor"
},
"wage_type": {
"enum": [
"Fixed",
"Hourly"
],
"type": "string",
"description": "The contractor's wage type, either \"Fixed\" or \"Hourly\"."
},
"first_name": {
"type": "string",
"nullable": true,
"description": "The contractor’s first name. This attribute is required for “Individual” contractors and will be ignored for “Business” contractors."
},
"start_date": {
"type": "string",
"readOnly": true,
"description": "The contractor's start date."
},
"work_state": {
"type": "string",
"nullable": true,
"description": "State where the contractor will be conducting the majority of their work for the company.\nThis value is used when generating the new hire report."
},
"hourly_rate": {
"type": "string",
"example": "50.0",
"description": "The contractor’s hourly rate. This attribute is required if the wage_type is “Hourly”."
},
"company_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the company the contractor is employed by."
},
"business_name": {
"type": "string",
"nullable": true,
"description": "The name of the contractor business. This attribute is required for “Business” contractors and will be ignored for “Individual” contractors."
},
"middle_initial": {
"type": "string",
"nullable": true,
"description": "The contractor’s middle initial. This attribute is optional for “Individual” contractors and will be ignored for “Business” contractors."
},
"onboarding_status": {
"enum": [
"onboarding_completed",
"admin_onboarding_review",
"admin_onboarding_incomplete"
],
"type": "string",
"description": "One of the \"onboarding_status\" enum values."
},
"file_new_hire_report": {
"type": "boolean",
"default": false,
"description": "The boolean flag indicating whether Gusto will file a new hire report for the contractor"
}
},
"description": "The representation of a contractor (individual or business) in Gusto."
}
Contractor-Address
{
"allOf": [
{
"$ref": "#/components/schemas/Address"
},
{
"type": "object",
"properties": {
"contractor_uuid": {
"type": "integer",
"description": "The UUID of the contractor"
}
}
}
]
}
Contractor-Bank-Account
{
"type": "object",
"title": "Contractor-Bank-Account",
"x-tags": [
"Contractor Payment Method"
],
"properties": {
"name": {
"type": "string",
"description": "Name for the bank account"
},
"uuid": {
"type": "string",
"description": "UUID of the bank account"
},
"account_type": {
"enum": [
"Checking",
"Savings"
],
"type": "string",
"description": "Bank account type"
},
"routing_number": {
"type": "string",
"description": "The bank account's routing number"
},
"contractor_uuid": {
"type": "string",
"description": "UUID of the employee"
},
"hidden_account_number": {
"type": "string",
"description": "Masked bank account number"
}
},
"x-examples": {
"Example": {
"value": {
"name": "BoA Checking Account",
"uuid": "1531e824-8d9e-4bd8-9f90-0d04608125d7",
"account_type": "Checking",
"employee_uuid": "9fcf1b1d-8886-4691-9283-383d3bdd4fd9",
"routing_number": "266905059",
"hidden_account_number": "XXXX1207"
}
}
}
}
Contractor-Body
{
"type": "object",
"properties": {
"ein": {
"type": "string",
"description": "The employer identification number of the contractor business.\nThis attribute is optional for `Business` contractors and will be ignored for `Individual` contractors."
},
"ssn": {
"type": "string",
"pattern": "[0-9]{9}",
"description": "This attribute is optional for `Individual` contractors and will be ignored for `Business` contractors.\nSocial security number is needed to file the annual 1099 tax form."
},
"type": {
"enum": [
"Individual",
"Business"
],
"type": "string",
"default": "Individual",
"description": "The contractor type."
},
"email": {
"type": "string",
"description": "The contractor’s email address."
},
"is_active": {
"type": "boolean",
"description": "The status of the contractor."
},
"last_name": {
"type": "string",
"description": "The contractor’s last name.\nThis attribute is required for `Individual` contractors and will be ignored for `Business` contractors."
},
"wage_type": {
"enum": [
"Fixed",
"Hourly"
],
"type": "string",
"description": "The contractor’s wage type.\n"
},
"first_name": {
"type": "string",
"description": "The contractor’s first name.\nThis attribute is required for `Individual` contractors and will be ignored for `Business` contractors."
},
"start_date": {
"type": "string",
"example": "2020-01-11",
"description": "The day when the contractor will start working for the company.\n"
},
"work_state": {
"type": "string",
"nullable": true,
"description": "State where the contractor will be conducting the majority of their work for the company.\nThis value is used when generating the new hire report.\nThis attribute is required for `Individual` contractors if `file_new_hire_report` is true and will be ignored for `Business` contractors."
},
"hourly_rate": {
"type": "string",
"example": "40.0",
"description": "The contractor’s hourly rate. This attribute is required if the wage_type is `Hourly`."
},
"business_name": {
"type": "string",
"description": "The name of the contractor business. This attribute is required for `Business` contractors and will be ignored for `Individual` contractors."
},
"middle_initial": {
"type": "string",
"description": "The contractor’s middle initial.\nThis attribute is optional for `Individual` contractors and will be ignored for `Business` contractors."
},
"self_onboarding": {
"type": "boolean",
"default": false,
"description": "Whether the contractor or the payroll admin will complete onboarding in Gusto.\nSelf-onboarding is recommended so that contractors receive Gusto accounts.\nIf self_onboarding is true, then email is required."
},
"file_new_hire_report": {
"type": "boolean",
"default": false,
"description": "The boolean flag indicating whether Gusto will file a new hire report for the contractor.\nThis attribute is optional for `Individual` contractors and will be ignored for `Business` contractors."
}
}
}
Contractor-Onboarding-Status
{
"type": "object",
"title": "Contractor-Onboarding-Status",
"x-tags": [
"Contractor"
],
"properties": {
"uuid": {
"type": "string",
"description": "Unique identifier for this contractor."
},
"onboarding_steps": {
"type": "array",
"items": {
"type": "object",
"title": "Onboarding step",
"properties": {
"id": {
"type": "string",
"description": "String identifier for the onboarding step."
},
"title": {
"type": "string",
"description": "User-friendly description of the onboarding step."
},
"required": {
"type": "boolean",
"description": "When true, this step is required."
},
"completed": {
"type": "boolean",
"description": "When true, this step has been completed."
},
"requirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of onboarding steps required to begin this step."
}
}
},
"description": "List of steps required to onboard a contractor."
},
"onboarding_status": {
"enum": [
"onboarding_completed",
"admin_onboarding_review",
"admin_onboarding_incomplete"
],
"type": "string",
"description": "One of the \"onboarding_status\" enum values."
}
},
"description": "The representation of an contractor's onboarding status."
}
Contractor-Payment
{
"type": "object",
"title": "Contractor Payment",
"x-tags": [
"Contractor Payments"
],
"properties": {
"date": {
"type": "string",
"readOnly": true,
"description": "The payment date."
},
"uuid": {
"type": "string",
"readOnly": true,
"description": "The unique identifier of the contractor payment in Gusto."
},
"wage": {
"type": "string",
"readOnly": true,
"description": "The fixed wage of the payment, regardless of hours worked."
},
"bonus": {
"type": "string",
"readOnly": true,
"description": "The bonus amount in the payment."
},
"hours": {
"type": "string",
"readOnly": true,
"description": "The number of hours worked for the payment."
},
"status": {
"enum": [
"Funded",
"Unfunded"
],
"type": "string",
"description": "Contractor payment status"
},
"wage_type": {
"enum": [
"Hourly",
"Fixed"
],
"type": "string",
"readOnly": true,
"description": "The wage type for the payment."
},
"may_cancel": {
"type": "boolean",
"readOnly": true,
"description": "Determine if the contractor payment can be cancelled."
},
"wage_total": {
"type": "string",
"readOnly": true,
"description": "(hours * hourly_rate) + wage + bonus"
},
"hourly_rate": {
"type": "string",
"readOnly": true,
"description": "The rate per hour worked for the payment."
},
"reimbursement": {
"type": "string",
"readOnly": true,
"description": "The reimbursement amount in the payment."
},
"payment_method": {
"enum": [
"Direct Deposit",
"Check",
"Historical Payment",
"Correction Payment"
],
"type": "string",
"readOnly": true,
"description": "The payment method."
},
"contractor_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the contractor."
}
},
"x-examples": {
"Example": {
"date": "2020-10-19",
"uuid": "04552eb9-7829-4b18-ae96-6983552948df",
"wage": "0.0",
"bonus": "20.0",
"hours": "40.0",
"status": "Funded",
"wage_type": "Hourly",
"may_cancel": true,
"wage_total": "740.00",
"hourly_rate": "18.0",
"reimbursement": "100.0",
"payment_method": "Direct Deposit"
}
},
"description": "The representation of a single contractor payment."
}
Contractor-Payment-Method
{
"type": "object",
"title": "Contractor-Payment-Method",
"x-tags": [
"Contractor Payment Method"
],
"properties": {
"type": {
"enum": [
"Direct Deposit",
"Check"
],
"type": "string",
"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."
},
"splits": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Payment-Method-Bank-Account"
},
"nullable": true
},
"version": {
"type": "string",
"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."
},
"split_by": {
"enum": [
"Amount",
"Percentage"
],
"type": "string",
"nullable": true,
"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."
}
},
"x-examples": {
"Example-1": {
"value": {
"type": "Direct Deposit",
"splits": [
{
"name": "BoA Checking Account",
"uuid": "e88f9436-b74e-49a8-87e9-777b9bfe715e",
"priority": 1,
"split_amount": 100
}
],
"version": "63859768485e218ccf8a449bb60f14ed",
"split_by": "Percentage"
}
},
"Example-2": {
"value": {
"type": "Check",
"version": "63859768485e218ccf8a449bb60f14ed"
}
}
},
"description": ""
}
Contractor-Payment-Receipt
{
"type": "object",
"properties": {
"totals": {
"type": "object",
"properties": {
"company_debit": {
"type": "string",
"description": "The total company debit for the contractor payment."
}
},
"description": "The subtotals for the contractor payment."
},
"license": {
"type": "string",
"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.\""
},
"licensee": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Always the fixed string \"San Francisco\""
},
"name": {
"type": "string",
"description": "Always the fixed string \"Gusto, Zenpayroll Inc.\""
},
"state": {
"type": "string",
"description": "Always the fixed string \"CA\""
},
"address": {
"type": "string",
"description": "Always the fixed string \"525 20th St\""
},
"postal_code": {
"type": "string",
"description": "Always the fixed string \"94107\""
},
"phone_number": {
"type": "string",
"description": "Always the fixed string \"4157778888\""
}
},
"description": "The licensed payroll processor"
},
"debit_date": {
"type": "string",
"format": "date",
"example": "2022-05-30",
"description": "The debit date for the contractor payment."
},
"license_uri": {
"type": "string",
"description": "URL for the license information for the licensed payroll processor. Always the fixed string \"https://gusto.com/about/licenses\""
},
"company_uuid": {
"type": "string",
"description": "A unique identifier of the company making the contractor payment."
},
"name_of_sender": {
"type": "string",
"description": "The name of the company making the contractor payment."
},
"right_to_refund": {
"type": "string",
"description": "URL for information related to right to refund. Always the fixed string \"https://gusto.com/about/licenses\""
},
"name_of_recipient": {
"type": "string",
"description": "The individual or company name of the contractor receiving payment."
},
"contractor_payments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"wage": {
"type": "string",
"description": "The fixed wage of the payment, regardless of hours worked."
},
"bonus": {
"type": "string",
"description": "The bonus amount in the payment."
},
"reimbursement": {
"type": "string",
"description": "The reimbursement amount in the payment."
},
"payment_method": {
"type": "string",
"description": "The payment method.\n\n`Direct Deposit` `Check` `Historical Payment` `Correction Payment`"
},
"contractor_type": {
"type": "string",
"description": "The type of contractor.\n\n`Individual` `Business`"
},
"contractor_uuid": {
"type": "string",
"description": "The UUID of the contractor."
},
"contractor_last_name": {
"type": "string",
"description": "The last name of the contractor. Applies when `contractor_type` is `Individual`."
},
"contractor_first_name": {
"type": "string",
"description": "The first name of the contractor. Applies when `contractor_type` is `Individual`."
},
"contractor_business_name": {
"type": "string",
"description": "The business name of the employee. Applies when `contractor_type` is `Business`."
}
}
},
"description": "An array of contractor payments for this contractor payment."
},
"liability_of_licensee": {
"type": "string",
"description": "URL for information related to right to liability of licensee. Always the fixed string \"https://gusto.com/about/licenses\""
},
"contractor_payment_uuid": {
"type": "string",
"description": "A unique identifier of the contractor payment receipt."
}
},
"x-examples": {
"example-1": {
"totals": {
"company_debit": "748.34"
},
"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.",
"licensee": {
"city": "San Francisco",
"name": "Gusto, Zenpayroll Inc.",
"state": "CA",
"address": "525 20th St",
"postal_code": "94107",
"phone_number": "4157778888"
},
"debit_date": "2022-06-02",
"license_uri": "https://gusto.com/about/licenses",
"company_uuid": "c827aa0d-3928-4d5a-ab1f-400641a7d2b8",
"name_of_sender": "Torp and Sons and Sons",
"right_to_refund": "https://gusto.com/about/licenses",
"name_of_recipient": "Patricia Hamill",
"contractor_payments": [
{
"wage": "448.34",
"bonus": "248.00",
"reimbursement": "100.00",
"payment_method": "Direct Deposit",
"contractor_type": "Individual",
"contractor_uuid": "f83d0bd8-7e20-43b9-834c-6d514ef6cb47",
"contractor_last_name": "Hamill",
"contractor_first_name": "Patricia",
"contractor_business_name": ""
}
],
"liability_of_licensee": "https://gusto.com/about/licenses",
"contractor_payment_uuid": "afccb970-357e-4013-81f5-85dafc74f9b6"
}
}
}
Contractor-Payment-Summary
{
"type": "object",
"x-tags": [
"Contractor Payments"
],
"properties": {
"total": {
"type": "object",
"readOnly": true,
"properties": {
"wages": {
"type": "string",
"readOnly": true,
"description": "The total wages for contractor payments within a given time period."
},
"reimbursements": {
"type": "string",
"readOnly": true,
"description": "The total reimbursements for contractor payments within a given time period."
}
},
"description": "The wage and reimbursement totals for all contractor payments within a given time period."
},
"contractor_payments": {
"type": "array",
"items": {
"type": "object",
"readOnly": true,
"properties": {
"payments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Contractor-Payment"
},
"readOnly": true,
"description": "The contractor’s payments within a given time period.\n",
"uniqueItems": false
},
"wage_total": {
"type": "string",
"readOnly": true,
"description": "The total wages for the contractor within a given time period."
},
"contractor_uuid": {
"type": "number",
"readOnly": true,
"description": "The UUID of the contractor."
},
"reimbursement_total": {
"type": "string",
"readOnly": true,
"description": "The total reimbursements for the contractor within a given time period."
}
},
"description": ""
},
"readOnly": true,
"description": "The individual contractor payments, within a given time period, grouped by contractor.",
"uniqueItems": false
}
},
"x-examples": {
"Example": {
"total": {
"wages": "1840.0",
"reimbursements": "110.0"
},
"contractor_payments": [
{
"payments": [
{
"date": "2020-10-19",
"uuid": "04552eb9-7829-4b18-ae96-6983552948df",
"wage": "0.0",
"bonus": "20.0",
"hours": "40.0",
"wage_type": "Hourly",
"may_cancel": true,
"wage_total": "740.00",
"hourly_rate": "18.0",
"reimbursement": "100.0",
"payment_method": "Direct Deposit",
"contractor_uuid": "bc57832c-d8bc-43a7-ae99-3a03380ff037"
},
{
"date": "2020-10-19",
"uuid": "25cfeb96-17fc-4fdf-8941-57f3fb9eea00",
"wage": "1000.0",
"bonus": "100.0",
"hours": "0.00",
"wage_type": "Fixed",
"may_cancel": true,
"wage_total": "1100.0",
"hourly_rate": "0.0",
"reimbursement": "10.0",
"payment_method": "Direct Deposit",
"contractor_uuid": "bc57832c-d8bc-43a7-ae99-3a03380ff037"
}
],
"wage_total": "1840.0",
"contractor_uuid": "bc57832c-d8bc-43a7-ae99-3a03380ff037",
"reimbursement_total": "110.0"
}
]
}
},
"description": "The representation of the summary of contractor payments for a given company in a given time period."
}
Contractor-Payment-Summary-By-Dates
{
"type": "object",
"x-tags": [
"Contractor Payments"
],
"properties": {
"total": {
"type": "object",
"readOnly": true,
"properties": {
"wages": {
"type": "string",
"readOnly": true,
"description": "The total wages for contractor payments within a given time period."
},
"reimbursements": {
"type": "string",
"readOnly": true,
"description": "The total reimbursements for contractor payments within a given time period."
}
},
"description": "The wage and reimbursement totals for all contractor payments within a given time period."
},
"contractor_payments": {
"type": "array",
"items": {
"type": "object",
"readOnly": true,
"properties": {
"payments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Contractor-Payment"
},
"readOnly": true,
"description": "The contractor’s payments within a given time period.\n",
"uniqueItems": false
},
"check_date": {
"type": "string",
"readOnly": true,
"description": "The payment check date."
},
"wage_total": {
"type": "string",
"readOnly": true,
"description": "The total wages for the contractor within a given time period."
},
"contractor_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the contractor."
},
"reimbursement_total": {
"type": "string",
"readOnly": true,
"description": "The total reimbursements for the contractor within a given time period."
}
},
"description": ""
},
"readOnly": true,
"description": "The individual contractor payments, within a given time period, grouped by check date.",
"uniqueItems": false
}
},
"x-examples": {
"Example": {
"total": {
"wages": "1840.0",
"reimbursements": "110.0"
},
"contractor_payments": [
{
"payments": [
{
"date": "2020-10-19",
"uuid": "04552eb9-7829-4b18-ae96-6983552948df",
"wage": "0.0",
"bonus": "20.0",
"hours": "40.0",
"wage_type": "Hourly",
"wage_total": "740.00",
"hourly_rate": "18.0",
"reimbursement": "100.0",
"payment_method": "Direct Deposit",
"contractor_uuid": "bc57832c-d8bc-43a7-ae99-3a03380ff037"
},
{
"date": "2020-10-19",
"uuid": "25cfeb96-17fc-4fdf-8941-57f3fb9eea00",
"wage": "1000.0",
"bonus": "100.0",
"hours": "0.00",
"wage_type": "Fixed",
"wage_total": "1100.0",
"hourly_rate": "0.0",
"reimbursement": "10.0",
"payment_method": "Direct Deposit",
"contractor_uuid": "bc57832c-d8bc-43a7-ae99-3a03380ff037"
}
],
"check_date": "2020-10-19",
"wage_total": "1840.0",
"reimbursement_total": "110.0"
}
]
}
},
"description": "The representation of the summary of contractor payments for a given company in a given time period."
}
ContractorFormsCreate1099FormRequest
{
"type": "object",
"required": [
"contractor_id"
],
"properties": {
"year": {
"type": "integer",
"description": "Must be equal to or more recent than 2015. If not specified, defaults to the previous year.\n"
},
"contractor_id": {
"type": "string",
"description": "The contractor UUID."
}
}
}
ContractorFormsListAllResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Form_1099"
}
}
ContractorPaymentMethodCreateBankAccountRequest
{
"type": "object",
"required": [
"name",
"routing_number",
"account_number",
"account_type"
],
"properties": {
"name": {
"type": "string"
},
"account_type": {
"enum": [
"Checking",
"Savings"
],
"type": "string"
},
"account_number": {
"type": "string"
},
"routing_number": {
"type": "string"
}
}
}
ContractorPaymentMethodCreateBankAccountResponse
{
"type": "object",
"properties": {}
}
ContractorPaymentMethodListBankAccountsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Contractor-Bank-Account"
}
}
ContractorPaymentMethodUpdateBankAccountRequest
{
"allOf": [
{
"$ref": "#/components/schemas/Versionable-Required"
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"enum": [
"Direct Deposit",
"Check"
],
"type": "string",
"description": "The payment method type. If type is Direct Deposit, the contractor is required to have a bank account.\nsee [Bank account endpoint](./post-v1-contractors-contractor_uuid-bank_accounts)"
}
}
}
]
}
ContractorPaymentsCreatePaymentRequest
{
"type": "object",
"required": [
"contractor_uuid",
"date"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"example": "2020-01-01",
"description": "The contractor receiving the payment"
},
"wage": {
"type": "number",
"example": 5000,
"description": "If the contractor is on a fixed wage, this is the fixed wage payment for the contractor, regardless of hours worked"
},
"bonus": {
"type": "number",
"example": 500,
"description": "If the contractor is on an hourly wage, this is the bonus the contractor earned"
},
"hours": {
"type": "number",
"example": 40,
"description": "If the contractor is on an hourly wage, this is the number of hours that the contractor worked for the payment"
},
"reimbursement": {
"type": "number",
"example": 20,
"description": "Reimbursed wages for the contractor"
},
"payment_method": {
"enum": [
"Direct Deposit",
"Check",
"Historical Payment"
],
"type": "string",
"default": "Direct Deposit"
},
"contractor_uuid": {
"type": "string",
"description": "The contractor receiving the payment"
}
}
}
ContractorPaymentsGetWithinTimePeriodTotalsResponse
{
"oneOf": [
{
"$ref": "#/components/schemas/Contractor-Payment-Summary"
},
{
"$ref": "#/components/schemas/Contractor-Payment-Summary-By-Dates"
}
]
}
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."
}
]
}
}
}
}
ContractorPaymentsPreviewDebitDateRequest
{
"type": "object",
"properties": {
"contractor_payments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"wage": {
"type": "integer"
},
"bonus": {
"type": "integer"
},
"hours": {
"type": "integer"
},
"hourly_rate": {
"type": "integer"
},
"reimbursement": {
"type": "integer"
},
"payment_method": {
"type": "string"
},
"contractor_uuid": {
"type": "string"
}
}
}
}
},
"x-examples": {
"example-1": {
"contractor_payments": [
{
"wage": 123,
"bonus": 0,
"hours": 0,
"check_date": "2022-09-02",
"hourly_rate": 0,
"reimbursement": 0,
"payment_method": "Check",
"contractor_uuid": "5376e95b-cca0-482b-bb81-aba5e360eb04"
},
{
"wage": 456,
"bonus": 0,
"hours": 0,
"check_date": "2022-09-02",
"hourly_rate": 0,
"reimbursement": 0,
"payment_method": "Check",
"contractor_uuid": "0c984dce-de9a-47db-8bfb-5f0c823afe6f"
}
]
}
}
}
ContractorPaymentsPreviewDebitDateRequest1
{
"type": "object",
"properties": {}
}
ContractorPaymentsPreviewDebitDateResponse
{
"type": "object",
"properties": {
"expected_debit_date": {
"type": "string",
"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."
}
},
"x-examples": {
"example-1": {
"expected_debit_date": "2022-08-16"
}
}
}
ContractorsChangeOnboardingStatusRequest
{
"type": "object",
"required": [
"onboarding_status"
],
"properties": {
"onboarding_status": {
"enum": [
"onboarding_completed"
],
"type": "string",
"default": "onboarding_completed",
"description": "The updated onboarding status for the employee"
}
}
}
ContractorsCreateNewContractorRequest
{
"allOf": [
{
"$ref": "#/components/schemas/Contractor-Body"
},
{
"required": [
"type",
"wage_type",
"start_date"
]
}
]
}
ContractorsGetCompanyContractorsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Contractor"
}
}
ContractorsGetOnboardingStatusResponse
{
"type": "object",
"properties": {}
}
ContractorsUpdateAddressRequest
{
"allOf": [
{
"$ref": "#/components/schemas/Versionable-Required"
},
{
"type": "object",
"properties": {
"zip": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"street_1": {
"type": "string"
},
"street_2": {
"type": "string"
}
}
}
]
}
ContractorsUpdateContractorRequest
{
"allOf": [
{
"$ref": "#/components/schemas/Versionable-Required"
},
{
"$ref": "#/components/schemas/Contractor-Body"
}
]
}
Created-At-Type
{
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "Datetime for when the resource was created."
}
Custom-Field-Type
{
"enum": [
"text",
"currency",
"number",
"date",
"radio"
],
"type": "string",
"x-tags": [
"Custom Fields"
],
"description": "Input type for the custom field."
}
Department
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Versionable"
},
{
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "The UUID of the department"
},
"title": {
"type": "string",
"description": "Name of the department"
},
"employees": {
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string"
}
}
},
"description": "Array of employees assigned to the department."
},
"contractors": {
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string"
}
}
},
"description": "Array of contractors assigned to the department."
},
"company_uuid": {
"type": "string",
"description": "The UUID of the company"
}
}
}
]
}
DepartmentsAddPeopleToDepartmentRequest
{
"type": "object",
"properties": {
"version": {
"type": "string",
"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."
},
"employees": {
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string"
}
}
},
"description": "Array of employees to add to the department"
},
"contractors": {
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string"
}
}
},
"description": "Array of contractors to add to the department"
}
}
}
DepartmentsCreateDepartmentRequest
{
"type": "object",
"properties": {
"title": {
"type": "string"
}
}
}
DepartmentsGetAllWithEmployeesResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Department"
}
}
DepartmentsRemovePeopleFromDepartmentRequest
{
"type": "object",
"properties": {
"version": {
"type": "string",
"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."
},
"employees": {
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string"
}
}
},
"description": "Array of employees to remove from a department"
},
"contractors": {
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string"
}
}
},
"description": "Array of contractors to remove from a department"
}
}
}
DepartmentsUpdateDepartmentRequest
{
"type": "object",
"required": [
"version"
],
"properties": {
"title": {
"type": "string"
},
"version": {
"type": "string",
"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."
}
}
}
Earning-Type
{
"type": "object",
"x-tags": [
"Earning Types"
],
"properties": {
"name": {
"type": "string",
"description": "The name of the earning type."
},
"uuid": {
"type": "string",
"readOnly": true,
"description": "The ID of the earning type."
}
},
"x-examples": {
"Example": {
"name": "Cash Tips",
"uuid": "f5618c94-ed7d-4366-b2c4-ff05e430064f"
}
},
"description": ""
}
EarningTypesCreateCustomEarningTypeRequest
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "The name of the custom earning type."
}
}
}
EarningTypesGetAllResponse
{
"type": "object",
"properties": {
"custom": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Earning-Type"
},
"description": "The custom earning types for the company."
},
"default": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Earning-Type"
},
"description": "The default earning types for the company."
}
}
}
EarningTypesUpdateTypeRequest
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the custom earning type."
}
}
}
Employee
{
"type": "object",
"title": "Employee",
"x-tags": [
"Employees"
],
"readOnly": true,
"properties": {
"ssn": {
"type": "string",
"description": "Deprecated. This field always returns an empty string."
},
"jobs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Job"
}
},
"uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the employee in Gusto."
},
"email": {
"type": "string",
"nullable": true,
"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)."
},
"phone": {
"type": "string"
},
"has_ssn": {
"type": "boolean",
"description": "Indicates whether the employee has an SSN in Gusto."
},
"version": {
"type": "string",
"readOnly": true,
"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."
},
"last_name": {
"type": "string"
},
"onboarded": {
"type": "boolean",
"readOnly": true,
"description": "Whether the employee has completed onboarding."
},
"department": {
"type": "string",
"nullable": true,
"readOnly": true,
"description": "The employee's department in the company."
},
"first_name": {
"type": "string"
},
"terminated": {
"type": "boolean",
"readOnly": true,
"description": "Whether the employee is terminated."
},
"work_email": {
"type": "string",
"nullable": true,
"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)."
},
"company_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the company the employee is employed by."
},
"garnishments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Garnishment"
}
},
"manager_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the employee's manager."
},
"terminations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Termination"
}
},
"custom_fields": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Employee-Custom-Field"
},
"description": "Custom fields are only included for the employee if the include param has the custom_fields value set"
},
"date_of_birth": {
"type": "string",
"nullable": true,
"readOnly": true
},
"middle_initial": {
"type": "string",
"nullable": true
},
"payment_method": {
"enum": [
"Direct Deposit",
"Check"
],
"type": "string",
"default": "Check",
"nullable": false,
"description": "The employee's payment method"
},
"onboarding_status": {
"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"
],
"type": "string",
"readOnly": true,
"description": "The current onboarding status of the employee"
},
"preferred_first_name": {
"type": "string",
"description": ""
},
"eligible_paid_time_off": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Paid-Time-Off"
}
},
"two_percent_shareholder": {
"type": "boolean",
"description": "Whether the employee is a two percent shareholder of the company. This field only applies to companies with an S-Corp entity type."
},
"current_employment_status": {
"enum": [
"full_time",
"part_time_under_twenty_hours",
"part_time_twenty_plus_hours",
"variable",
"seasonal"
],
"type": "string",
"nullable": true,
"readOnly": true,
"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."
}
},
"x-examples": {
"Example": {
"ssn": "",
"jobs": [
{
"rate": "22.00",
"uuid": "5d5e3ce5-ea8f-4885-90e5-7ebaed03f7c5",
"title": "Client Support Manager",
"primary": true,
"version": "91179081a7309c9fbd31bb3cf7b9893e",
"hire_date": "2020-01-20",
"payment_unit": "Hour",
"compensations": [
{
"rate": "22.00",
"uuid": "94f17a77-cfe5-436a-af94-422bbf8248ff",
"version": "233f0096a8015e62d9795fadf1fd300d",
"job_uuid": "64711ac0-83ff-4aaf-bec1-db72f5a44e56",
"flsa_status": "Nonexempt",
"payment_unit": "Hour",
"effective_date": "2021-01-20",
"adjust_for_minimum_wage": false
}
],
"employee_uuid": "a987bce1-6d06-43f8-9978-9db886f479fb",
"current_compensation_uuid": "798a962f-0fcf-491e-9b71-cfa6a1db114f"
}
],
"uuid": "9779767c-6044-48e0-bf68-aeb370b9a2e7",
"email": "kory7757869450111548@barton-hermiston.io",
"phone": "1234567890",
"has_ssn": true,
"version": "414dedaca594b77135e0b8d2f398516d",
"last_name": "Boehm",
"onboarded": true,
"department": null,
"first_name": "Nicole",
"terminated": false,
"work_email": "vanessa.boehm@example.com",
"company_uuid": "c44d66dc-c41b-4a60-9e25-5e93ff8583f2",
"garnishments": [],
"manager_uuid": "5e53e257-c8d6-45aa-aa8a-ec99283a3acd",
"terminations": [],
"custom_fields": [
{
"id": "ee515986-f3ca-49da-b576-2691b95262f9",
"name": "employee_level",
"type": "text",
"value": "2",
"description": "Employee Level",
"company_custom_field_id": "ea7e5d57-6abb-47d7-b654-347c142886c0"
},
{
"id": "3796e08d-c2e3-434c-b4de-4ce1893e7b59",
"name": "t-shirt size",
"type": "text",
"value": "md",
"description": "What is your t-shirt size?",
"company_custom_field_id": "299650e4-e970-4acf-9bf0-6f05585d20ba"
}
],
"date_of_birth": "1996-05-08",
"middle_initial": "M",
"onboarding_status": "onboarding_completed",
"preferred_first_name": "Vanessa",
"eligible_paid_time_off": [
{
"name": "Sick Hours",
"policy_name": "Sick Policy",
"policy_uuid": "8dc8f324-3c03-4b42-8602-02476fa21c1b",
"accrual_rate": "208.0",
"accrual_unit": "Hour",
"accrual_method": "per_hour_worked",
"accrual_period": "Year",
"accrual_balance": "71.0",
"paid_at_termination": false,
"maximum_accrual_balance": "240.0"
},
{
"name": "Vacation Hours",
"policy_name": "Vacation Policy",
"policy_uuid": "ab59de61-239f-4805-933b-0e3360ed291c",
"accrual_rate": "208.0",
"accrual_unit": "Hour",
"accrual_period": "Year",
"accrual_balance": "34.0",
"paid_at_termination": true,
"maximum_accrual_balance": "240.0"
}
],
"two_percent_shareholder": false
}
},
"description": "The representation of an employee in Gusto."
}
Employee-Address
{
"allOf": [
{
"$ref": "#/components/schemas/Address"
},
{
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "The UUID of the employee address"
},
"employee_uuid": {
"type": "string",
"description": "The UUID of the employee"
},
"effective_date": {
"type": "string",
"format": "date",
"description": "The date the employee started living at the address."
},
"courtesy_withholding": {
"type": "boolean",
"description": "Determines if home taxes should be withheld and paid for employee."
}
}
}
],
"example": {
"zip": "94107",
"city": "San Francisco",
"uuid": "9557fe01-f8f8-4c14-a61c-ca6221a9f118",
"state": "CA",
"active": true,
"country": "USA",
"street_1": "333 Kiera Stravenue",
"street_2": "Suite 391",
"employee_uuid": "da441196-43a9-4d23-ad5d-f37ce6bb99c0",
"effective_date": "2021-01-01",
"courtesy_withholding": true
}
}
Employee-Bank-Account
{
"type": "object",
"title": "Employee-Bank-Account",
"x-tags": [
"Employee Payment Method"
],
"properties": {
"name": {
"type": "string",
"description": "Name for the bank account"
},
"uuid": {
"type": "string",
"description": "UUID of the bank account"
},
"account_type": {
"enum": [
"Checking",
"Savings"
],
"type": "string",
"description": "Bank account type"
},
"employee_uuid": {
"type": "string",
"description": "UUID of the employee"
},
"routing_number": {
"type": "string",
"description": "The bank account's routing number"
},
"hidden_account_number": {
"type": "string",
"description": "Masked bank account number"
}
},
"x-examples": {
"Example": {
"value": {
"name": "BoA Checking Account",
"uuid": "1531e824-8d9e-4bd8-9f90-0d04608125d7",
"account_type": "Checking",
"employee_uuid": "9fcf1b1d-8886-4691-9283-383d3bdd4fd9",
"routing_number": "266905059",
"hidden_account_number": "XXXX1207"
}
}
}
}
Employee-Benefit
{
"type": "object",
"title": "",
"properties": {
"uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the employee benefit."
},
"active": {
"type": "boolean",
"default": true,
"description": "Whether the employee benefit is active."
},
"version": {
"type": "string",
"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."
},
"catch_up": {
"type": "boolean",
"default": false,
"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."
},
"elective": {
"type": "boolean",
"default": false,
"description": "Whether the company contribution is elective (aka matching). For \"tiered\" contribution types, this is always true."
},
"contribution": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The company contribution scheme.\n\n\"amount\": The company contributes a fixed amount per payroll. If elective is true, the contribution is matching, dollar-for-dollar.\n\n\"percentage\": The company contributes a percentage of the payroll amount per payroll period. If elective is true, the contribution is matching, dollar-for-dollar.\n\n\"tiered\": The company contribution varies according to the size of the employee deduction."
},
"value": {
"oneOf": [
{
"type": "string"
},
{
"type": "object",
"properties": {
"tiers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rate": {
"type": "string",
"description": "The percentage of employee deduction within this tier the company contribution will match."
},
"threshold": {
"type": "string",
"description": "The percentage threshold at which this tier ends (inclusive).\n\nFor 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.\n\nIf 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."
},
"threshold_delta": {
"type": "string",
"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."
}
},
"description": "A single tier of a tiered matching scheme."
},
"description": ""
}
}
}
],
"description": "For the `amount` and `percentage` contribution types, the value of the corresponding amount or percentage.\n\nFor the `tiered` contribution type, an array of tiers."
}
},
"description": "An object representing the type and value of the company contribution."
},
"limit_option": {
"type": "string",
"nullable": true,
"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\"."
},
"employee_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the employee to which the benefit belongs."
},
"coverage_amount": {
"type": "string",
"nullable": true,
"description": "The amount that the employee is insured for. Note: company contribution cannot be present if coverage amount is set."
},
"employee_deduction": {
"type": "string",
"default": "0.00",
"description": "The amount to be deducted, per pay period, from the employee's pay."
},
"company_benefit_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the company benefit."
},
"company_contribution": {
"type": "string",
"default": "0.00",
"deprecated": true,
"description": "The amount to be paid, per pay period, by the company. This field will not appear for tiered contribution types."
},
"deduct_as_percentage": {
"type": "boolean",
"default": false,
"description": "Whether the employee deduction amount should be treated as a percentage to be deducted from each payroll."
},
"contribute_as_percentage": {
"type": "boolean",
"default": false,
"deprecated": true,
"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."
},
"coverage_salary_multiplier": {
"type": "string",
"default": "0.00",
"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."
},
"retirement_loan_identifier": {
"type": "string",
"description": "Identifier for a 401(k) loan assigned by the 401(k) provider"
},
"deduction_reduces_taxable_income": {
"enum": [
"unset",
"reduces_taxable_income",
"does_not_reduce_taxable_income",
null
],
"type": "string",
"default": "unset",
"nullable": true,
"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."
},
"employee_deduction_annual_maximum": {
"type": "string",
"nullable": true,
"description": "The maximum employee deduction amount per year. A null value signifies no limit."
},
"company_contribution_annual_maximum": {
"type": "string",
"nullable": true,
"description": "The maximum company contribution amount per year. A null value signifies no limit."
}
},
"x-examples": {
"Example": {
"uuid": "e91ca856-a915-4339-9b18-29f9cd66b031",
"active": true,
"version": "09j3d29jqdpj92109j9j2d90dq",
"catch_up": false,
"elective": false,
"contribution": {
"type": "amount",
"value": "100.00"
},
"limit_option": null,
"employee_uuid": "73274962-63ce-4e5c-b689-1df8d4df09f4",
"coverage_amount": null,
"employee_deduction": "100.00",
"company_benefit_uuid": "54e37c27-43e6-4ae5-a5b2-e29895a133be",
"company_contribution": "100.00",
"deduct_as_percentage": false,
"contribute_as_percentage": false,
"coverage_salary_multiplier": "0.00",
"retirement_loan_identifier": null,
"deduction_reduces_taxable_income": null,
"employee_deduction_annual_maximum": "200.00",
"company_contribution_annual_maximum": "200.00"
},
"Tiered Example": {
"uuid": "e91ca856-a915-4339-9b18-29f9cd66b031",
"active": true,
"version": "09j3d29jqdpj92109j9j2d90dq",
"catch_up": false,
"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"
}
]
}
},
"limit_option": null,
"employee_uuid": "73274962-63ce-4e5c-b689-1df8d4df09f4",
"coverage_amount": null,
"employee_deduction": "100.00",
"company_benefit_uuid": "54e37c27-43e6-4ae5-a5b2-e29895a133be",
"deduct_as_percentage": false,
"coverage_salary_multiplier": "0.00",
"deduction_reduces_taxable_income": null,
"employee_deduction_annual_maximum": "200.00",
"company_contribution_annual_maximum": "200.00"
}
},
"description": "The representation of an employee benefit."
}
Employee-Custom-Field
{
"type": "object",
"x-tags": [
"Custom Fields"
],
"required": [
"id",
"company_custom_field_id",
"name",
"type",
"value"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"$ref": "#/components/schemas/Custom-Field-Type"
},
"value": {
"type": "string"
},
"description": {
"type": "string"
},
"selection_options": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true,
"description": "An array of options for fields of type radio. Otherwise, null."
},
"company_custom_field_id": {
"type": "string",
"description": "This is the id of the response object from when you get the company custom fields"
}
},
"x-examples": {
"Employee Level": {
"id": "ae4e2cd5-e9b6-40f9-88a1-415a02365dd0",
"name": "employee_level",
"value": "2",
"description": "Employee Level",
"company_custom_field_id": "da84500d-d05c-4e4f-bcf2-43152ca33278"
}
},
"description": "A custom field of an employee"
}
Employee-Federal-Tax
{
"type": "object",
"title": "Employee-Federal-Tax",
"x-tags": [
"Employee Tax Setup"
],
"properties": {
"version": {
"type": "string",
"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."
},
"two_jobs": {
"type": "boolean",
"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."
},
"deductions": {
"type": "string"
},
"other_income": {
"type": "string",
"description": "Other income amount."
},
"w4_data_type": {
"enum": [
"pre_2020_w4",
"rev_2020_w4"
],
"type": "string",
"description": "The version of w4 form."
},
"filing_status": {
"type": "string",
"description": "It determines which tax return form an individual will use and is an important factor in computing taxable income. One of:\n- Single\n- Married\n- Head of Household\n- Exempt from withholding\n- Married, but withhold as Single (does not apply to rev_2020_w4 form)"
},
"dependents_amount": {
"type": "string",
"description": "A dependent is a person other than the taxpayer or spouse who entitles the taxpayer to claim a dependency exemption."
},
"extra_withholding": {
"type": "string",
"description": "An employee can request an additional amount to be withheld from each paycheck."
},
"additional_withholding": {
"type": "boolean",
"description": "*does not apply to rev_2020_w4 form*"
},
"federal_withholding_allowance": {
"type": "string",
"description": "*does not apply to rev_2020_w4 form*\n\nAn exemption from paying a certain amount of income tax."
}
},
"x-examples": {
"Example": {
"value": {
"version": "56a489ce86ed6c1b0f0cecc4050a0b01",
"two_jobs": true,
"deductions": "0.0",
"other_income": "0.0",
"w4_data_type": "rev_2020_w4",
"filing_status": "Single",
"dependents_amount": "0.0",
"extra_withholding": "0.0"
}
}
}
}
Employee-Onboarding-Status
{
"type": "object",
"title": "Employee-Onboarding-Status",
"x-tags": [
"Employees"
],
"properties": {
"uuid": {
"type": "string",
"description": "Unique identifier for this employee."
},
"onboarding_steps": {
"type": "array",
"items": {
"type": "object",
"title": "Onboarding step",
"properties": {
"id": {
"type": "string",
"description": "String identifier for the onboarding step."
},
"title": {
"type": "string",
"description": "User-friendly description of the onboarding step."
},
"required": {
"type": "boolean",
"description": "When true, this step has been completed."
},
"completed": {
"type": "boolean",
"description": "When true, this step has been completed."
},
"requirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of onboarding steps required to begin this step."
}
}
},
"description": "List of steps required to onboard an employee."
},
"onboarding_status": {
"type": "string",
"description": "One of the \"onboarding_status\" enum values."
}
},
"x-examples": {
"Example - Employee Self-Onboarding": {
"uuid": "c44d66dc-c41b-4a60-9e25-5e93ff8583f2",
"onboarding_steps": [
{
"id": "personal_details",
"title": "Personal details",
"required": true,
"completed": false,
"requirements": []
},
{
"id": "compensation_details",
"title": "Enter compensation details",
"required": true,
"completed": false,
"requirements": []
},
{
"id": "add_work_address",
"title": "Add work address",
"required": true,
"completed": false,
"requirements": []
},
{
"id": "add_home_address",
"title": "Add home address",
"required": true,
"completed": false,
"requirements": []
},
{
"id": "federal_tax_setup",
"title": "Enter federal tax withholdings",
"required": true,
"completed": false,
"requirements": []
},
{
"id": "state_tax_setup",
"title": "Enter state tax information",
"required": true,
"completed": false,
"requirements": [
"add_work_address",
"add_home_address"
]
},
{
"id": "direct_deposit_setup",
"title": "Direct deposit setup",
"required": true,
"completed": false,
"requirements": []
},
{
"id": "employee_form_signing",
"title": "Employee form signing",
"required": true,
"completed": false,
"requirements": [
"federal_tax_setup",
"state_tax_setup"
]
},
{
"id": "admin_review",
"title": "Admin review",
"required": true,
"completed": false,
"requirements": [
"personal_details",
"compensation_details",
"add_home_address",
"add_work_address",
"federal_tax_setup",
"state_tax_setup"
]
}
],
"onboarding_status": "self_onboarding_invited"
},
"Example - Employee Onboarding by Admin": {
"uuid": "c44d66dc-c41b-4a60-9e25-5e93ff8583f2",
"onboarding_steps": [
{
"id": "personal_details",
"title": "Personal details",
"required": true,
"completed": false,
"requirements": []
},
{
"id": "compensation_details",
"title": "Enter compensation details",
"required": true,
"completed": false,
"requirements": []
},
{
"id": "add_work_address",
"title": "Add work address",
"required": true,
"completed": false,
"requirements": []
},
{
"id": "add_home_address",
"title": "Add home address",
"required": true,
"completed": false,
"requirements": []
},
{
"id": "federal_tax_setup",
"title": "Enter federal tax withholdings",
"required": true,
"completed": false,
"requirements": []
},
{
"id": "state_tax_setup",
"title": "Enter state tax information",
"required": true,
"completed": false,
"requirements": [
"add_work_address",
"add_home_address"
]
},
{
"id": "direct_deposit_setup",
"title": "Direct deposit setup",
"required": false,
"completed": false,
"requirements": []
},
{
"id": "employee_form_signing",
"title": "Employee form signing",
"required": true,
"completed": false,
"requirements": [
"federal_tax_setup",
"state_tax_setup"
]
},
{
"id": "file_new_hire_report",
"title": "File new hire report",
"required": true,
"completed": false,
"requirements": [
"add_work_address"
]
}
],
"onboarding_status": "admin_onboarding_incomplete"
}
},
"description": "The representation of an employee's onboarding status."
}
Employee-Pay-Stub
{
"type": "object",
"x-tags": [
"Payrolls"
],
"properties": {
"uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the employee pay stub."
},
"net_pay": {
"type": "string",
"readOnly": true,
"description": "The net pay amount for the pay stub."
},
"gross_pay": {
"type": "string",
"readOnly": true,
"description": "The gross pay amount for the pay stub."
},
"check_date": {
"type": "string",
"readOnly": true,
"description": "The check date of the pay stub."
},
"check_amount": {
"type": "string",
"readOnly": true,
"description": "The check amount for the pay stub."
},
"payroll_uuid": {
"type": "string",
"readOnly": true,
"description": "A unique identifier of the payroll to which the pay stub belongs."
}
},
"description": "The representation of an employee pay stub information."
}
Employee-Payment-Method
{
"type": "object",
"title": "Employee-Payment-Method",
"x-tags": [
"Employee Payment Method"
],
"properties": {
"type": {
"enum": [
"Direct Deposit",
"Check"
],
"type": "string",
"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."
},
"splits": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Payment-Method-Bank-Account"
},
"nullable": true
},
"version": {
"type": "string",
"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."
},
"split_by": {
"enum": [
"Amount",
"Percentage"
],
"type": "string",
"nullable": true,
"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."
}
},
"x-examples": {
"Example-1": {
"value": {
"type": "Direct Deposit",
"splits": [
{
"name": "BoA Checking Account",
"uuid": "e88f9436-b74e-49a8-87e9-777b9bfe715e",
"priority": 1,
"split_amount": 500
},
{
"name": "Chase Checking Account",
"uuid": "0d2b7f73-05d6-4184-911d-269edeecc30a",
"priority": 2,
"split_amount": 1000
},
{
"name": "US Bank Checking Account",
"uuid": "1531e824-8d9e-4bd8-9f90-0d04608125d7",
"priority": 3,
"split_amount": null
}
],
"version": "63859768485e218ccf8a449bb60f14ed",
"split_by": "Amount"
}
},
"Example-2": {
"value": {
"type": "Direct Deposit",
"splits": [
{
"name": "BoA Checking Account",
"uuid": "e88f9436-b74e-49a8-87e9-777b9bfe715e",
"priority": 1,
"split_amount": 60
},
{
"name": "Chase Checking Account",
"uuid": "0d2b7f73-05d6-4184-911d-269edeecc30a",
"priority": 2,
"split_amount": 40
}
],
"version": "63859768485e218ccf8a449bb60f14ed",
"split_by": "Percentage"
}
},
"Example-3": {
"value": {
"type": "Check",
"version": "63859768485e218ccf8a449bb60f14ed"
}
}
},
"description": ""
}
Employee-State-Tax
{
"type": "object",
"title": "Employee-State-Tax",
"x-tags": [
"Employee Tax Setup"
],
"required": [
"employee_uuid",
"state",
"questions"
],
"properties": {
"state": {
"type": "string",
"description": "Two letter US state abbreviation"
},
"questions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Employee-State-Tax-Question"
}
},
"employee_uuid": {
"type": "string",
"description": "The employee's uuid"
},
"is_work_state": {
"type": "boolean"
},
"file_new_hire_report": {
"type": "boolean"
}
},
"x-examples": {
"example-1": {
"state": "CA",
"questions": [
{
"key": "filing_status",
"label": "Filing Status",
"answers": [
{
"value": "S",
"valid_from": "2010-01-01",
"valid_up_to": null
}
],
"description": "The Head of Household status applies to unmarried individuals who have a relative living with them in their home. If unsure, read the <a target='_blank' data-bypass rel='noopener noreferrer' tabindex='99' href='https://www.ftb.ca.gov/file/personal/filing-status/index.html'>CA Filing Status explanation</a>.\n",
"input_question_format": {
"type": "Select",
"options": [
{
"label": "Single",
"value": "S"
},
{
"label": "Married one income",
"value": "M"
},
{
"label": "Married dual income",
"value": "MD"
},
{
"label": "Head of household",
"value": "H"
},
{
"label": "Do Not Withhold",
"value": "E"
}
]
}
},
{
"key": "withholding_allowance",
"label": "Withholding Allowance",
"answers": [
{
"value": 1,
"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 <a target='_blank' data-bypass rel='noopener noreferrer' tabindex='99' href='http://www.edd.ca.gov/pdf_pub_ctr/de4.pdf'>CA DE-4 form</a> to calculate the value manually.\n",
"input_question_format": {
"type": "Number"
}
},
{
"key": "additional_withholding",
"label": "Additional Withholding",
"answers": [
{
"value": "0.0",
"valid_from": "2010-01-01",
"valid_up_to": null
}
],
"description": "You can withhold an additional amount of California income taxes here.",
"input_question_format": {
"type": "Currency"
}
},
{
"key": "file_new_hire_report",
"label": "File a New Hire Report?",
"answers": [
{
"value": true,
"valid_from": "2010-01-01",
"valid_up_to": null
}
],
"options": [
{
"label": "Yes, file the state new hire report for me.",
"value": true
},
{
"label": "No, I have already filed.",
"value": false
}
],
"description": "State law requires you to file a new hire report within 20 days of hiring or re-hiring an employee.",
"input_question_format": {
"type": "Select"
}
}
],
"employee_uuid": "2005e601-3c78-410a-9d40-b960ae130383"
}
}
}
Employee-State-Tax-Answer
{
"type": "object",
"title": "Employee-State-Tax-Answer",
"x-tags": [
"Employee Tax Setup"
],
"properties": {
"value": {
"type": "string",
"description": "The answer to the corresponding question - this may be a string, number, boolean, or null."
},
"valid_from": {
"type": "string",
"description": "The effective date of the answer - currently always “2010-01-01”."
},
"valid_up_to": {
"nullable": true,
"description": "The effective end date of the answer - currently always null."
}
},
"x-examples": {
"example-1": {
"value": "0.0",
"valid_from": "2010-01-01",
"valid_up_to": null
}
}
}
Employee-State-Tax-Input-Question-Format
{
"type": "object",
"title": "Employee-State-Tax-Input-Question-Format",
"x-tags": [
"Employee Tax Setup"
],
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"description": "Describes the type of question - Text, Number, Select, Currency, Date"
},
"options": {
"type": "array",
"items": {
"type": "object",
"required": [
"label"
],
"properties": {
"label": {
"type": "string",
"description": "A display label that corresponds to the answer value"
},
"value": {
"type": "string",
"description": "An allowed value to answer the question"
}
}
},
"description": "For \"Select\" type questions, the allowed values and display labels.",
"uniqueItems": true
}
},
"x-examples": {
"number-example": {
"type": "Number"
},
"select-example": {
"type": "Select",
"options": [
{
"label": "Single",
"value": "S"
},
{
"label": "Married one income",
"value": "M"
},
{
"label": "Married dual income",
"value": "MD"
},
{
"label": "Head of household",
"value": "H"
},
{
"label": "Do Not Withhold",
"value": "E"
}
]
}
}
}
Employee-State-Tax-Question
{
"type": "object",
"title": "Employee-State-Tax-Question",
"x-tags": [
"Employee Tax Setup"
],
"required": [
"label",
"description",
"key",
"input_question_format",
"answers"
],
"properties": {
"key": {
"type": "string",
"description": "A unique identifier of the question (for the given state) - used for updating the answer."
},
"label": {
"type": "string",
"description": "A short title for the question"
},
"answers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Employee-State-Tax-Answer"
}
},
"description": {
"type": "string",
"description": "An explaination of the question - this may contain inline html formatted links."
},
"input_question_format": {
"$ref": "#/components/schemas/Employee-State-Tax-Input-Question-Format"
}
},
"x-examples": {
"example-1": {
"key": "filing_status",
"label": "Filing Status",
"answers": [
{
"value": "S",
"valid_from": "2010-01-01",
"valid_up_to": null
}
],
"description": "The Head of Household status applies to unmarried individuals who have a relative living with them in their home. If unsure, read the <a target='_blank' data-bypass rel='noopener noreferrer' tabindex='99' href='https://www.ftb.ca.gov/file/personal/filing-status/index.html'>CA Filing Status explanation</a>.\n",
"input_question_format": {
"type": "Select",
"options": [
{
"label": "Single",
"value": "S"
},
{
"label": "Married one income",
"value": "M"
},
{
"label": "Married dual income",
"value": "MD"
},
{
"label": "Head of household",
"value": "H"
},
{
"label": "Do Not Withhold",
"value": "E"
}
]
}
}
}
}
Employee-Work-Address
{
"type": "object",
"example": {
"zip": "28572",
"city": "Pink Hill",
"uuid": "34925ef7-6234-440d-83b8-788a24d0d69a",
"state": "NC",
"active": true,
"country": "USA",
"version": "6a22da647ed391f184a212e6e83a541d",
"street_1": "977 Marks Viaduct",
"street_2": null,
"employee_uuid": "2363b9c0-6625-4425-9261-47627fd68783",
"location_uuid": "aba6d0fd-7294-4997-b1a4-bc9268c45932",
"effective_date": "2023-05-15"
},
"properties": {
"zip": {
"type": "string",
"readOnly": true
},
"city": {
"type": "string",
"readOnly": true
},
"uuid": {
"type": "string",
"readOnly": true,
"description": "The unique identifier of this work address."
},
"state": {
"type": "string",
"readOnly": true
},
"active": {
"type": "boolean",
"readOnly": true,
"description": "Signifies if this address is the active work address for the current date"
},
"country": {
"type": "string",
"default": "USA",
"readOnly": true
},
"version": {
"type": "string",
"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."
},
"street_1": {
"type": "string",
"readOnly": true
},
"street_2": {
"type": "string",
"nullable": true,
"readOnly": true
},
"employee_uuid": {
"type": "string",
"description": "UUID reference to the employee for this work address."
},
"location_uuid": {
"type": "string",
"description": "UUID reference to the company location for this work address."
},
"effective_date": {
"type": "string",
"description": "The date the employee began working at this location."
}
}
}
EmployeeAddressesCreateHomeAddressRequest
{
"type": "object",
"required": [
"version"
],
"properties": {
"zip": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"street_1": {
"type": "string"
},
"street_2": {
"type": "string",
"nullable": true
},
"effective_date": {
"type": "string",
"format": "date"
},
"courtesy_withholding": {
"type": "boolean"
}
},
"description": ""
}
EmployeeAddressesCreateWorkAddressRequest
{
"type": "object",
"properties": {
"location_uuid": {
"type": "string",
"description": "Reference to a company location"
},
"effective_date": {
"type": "string",
"format": "date",
"description": "Date the employee began working at the company location"
}
},
"description": ""
}
EmployeeAddressesGetHomeAddressesResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Employee-Address"
}
}
EmployeeAddressesListWorkAddressesResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Employee-Work-Address"
}
}
EmployeeAddressesUpdateHomeAddressRequest
{
"type": "object",
"required": [
"version"
],
"properties": {
"zip": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"version": {
"type": "string",
"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."
},
"street_1": {
"type": "string"
},
"street_2": {
"type": "string",
"nullable": true
},
"effective_date": {
"type": "string",
"format": "date"
},
"courtesy_withholding": {
"type": "boolean"
}
},
"description": ""
}
EmployeeAddressesUpdateWorkAddressRequest
{
"type": "object",
"properties": {
"version": {
"type": "string",
"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."
},
"location_uuid": {
"type": "string",
"description": "Reference to a company location"
},
"effective_date": {
"type": "string",
"format": "date"
}
},
"description": ""
}
EmployeeBenefitsCreateBenefitRecordRequest
{
"type": "object",
"required": [
"company_benefit_uuid"
],
"properties": {
"active": {
"type": "boolean",
"default": true,
"description": "Whether the employee benefit is active."
},
"catch_up": {
"type": "boolean",
"default": false,
"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."
},
"elective": {
"type": "boolean",
"default": false,
"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`."
},
"contribution": {
"type": "object",
"properties": {
"type": {
"enum": [
"tiered",
"percentage",
"amount"
],
"type": "string",
"description": "The company contribution scheme.\n\n`amount`: The company contributes a fixed amount per payroll. If elective is true, the contribution is matching, dollar-for-dollar.\n\n`percentage`: The company contributes a percentage of the payroll amount per payroll period. If elective is true, the contribution is matching, dollar-for-dollar.\n\n`tiered`: The size of the company contribution corresponds to the size of the employee deduction relative to a tiered matching scheme."
},
"value": {
"oneOf": [
{
"type": "string",
"description": "For the `amount` and `percentage` contribution types, the value of the corresponding amount or percentage."
},
{
"type": "array",
"items": {
"type": "object",
"properties": {
"rate": {
"type": "string",
"description": "The percentage of employee deduction within this tier the company contribution will match."
},
"threshold": {
"type": "string",
"description": "The percentage threshold at which this tier ends (inclusive).\n\nFor 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.\n\nIf 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."
}
},
"description": "A single tier of a tiered matching scheme."
},
"description": "For `tiered` contribution types, an array of tiers."
}
],
"description": "For the `amount` and `percentage` contribution types, the value of the corresponding amount or percentage.\n\nFor the `tiered` contribution type, an array of tiers."
}
},
"description": "An object representing the company contribution type and value."
},
"limit_option": {
"type": "string",
"nullable": true,
"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\"."
},
"coverage_amount": {
"type": "string",
"nullable": true,
"description": "The amount that the employee is insured for. Note: company contribution cannot be present if coverage amount is set."
},
"employee_deduction": {
"type": "string",
"default": "0.00",
"description": "The amount to be deducted, per pay period, from the employee's pay."
},
"company_benefit_uuid": {
"type": "string",
"description": "The UUID of the company benefit."
},
"company_contribution": {
"type": "string",
"default": "0.00",
"deprecated": true,
"description": "The amount to be paid, per pay period, by the company."
},
"deduct_as_percentage": {
"type": "boolean",
"default": false,
"description": "Whether the employee deduction amount should be treated as a percentage to be deducted from each payroll."
},
"contribute_as_percentage": {
"type": "boolean",
"default": false,
"deprecated": true,
"description": "Whether the company contribution amount should be treated as a percentage to be deducted from each payroll."
},
"coverage_salary_multiplier": {
"type": "string",
"default": "0.00",
"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."
},
"deduction_reduces_taxable_income": {
"enum": [
"unset",
"reduces_taxable_income",
"does_not_reduce_taxable_income",
null
],
"type": "string",
"nullable": true,
"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."
},
"employee_deduction_annual_maximum": {
"type": "string",
"nullable": true,
"description": "The maximum employee deduction amount per year. A null value signifies no limit."
},
"company_contribution_annual_maximum": {
"type": "string",
"nullable": true,
"description": "The maximum company contribution amount per year. A null value signifies no limit."
}
},
"description": ""
}
EmployeeBenefitsCreateYtdBenefitAmountsFromDifferentCompanyRequest
{
"type": "object",
"required": [
"benefit_id",
"tax_year",
"ytd_employee_deduction_amount",
"ytd_company_contribution_amount"
],
"properties": {
"tax_year": {
"type": "number",
"maximum": 2999,
"minimum": 2000,
"description": "The tax year for which this amount applies."
},
"benefit_type": {
"type": "number",
"description": "The benefit type supported by Gusto."
},
"ytd_employee_deduction_amount": {
"type": "string",
"default": "0.00",
"description": "The year-to-date employee deduction made outside the current company."
},
"ytd_company_contribution_amount": {
"type": "string",
"default": "0.00",
"description": "The year-to-date company contribution made outside the current company."
}
}
}
EmployeeBenefitsGetAllForEmployeeResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Employee-Benefit"
}
}
EmployeeBenefitsUpdateBenefitRecordRequest
{
"type": "object",
"required": [
"version"
],
"properties": {
"active": {
"type": "boolean",
"description": "Whether the employee benefit is active."
},
"version": {
"type": "string",
"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."
},
"catch_up": {
"type": "boolean",
"default": false,
"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."
},
"elective": {
"type": "boolean",
"default": false,
"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`."
},
"contribution": {
"type": "object",
"properties": {
"type": {
"enum": [
"amount",
"percentage",
"tiered"
],
"type": "string",
"description": "The company contribution scheme.\n\n`amount`: The company contributes a fixed amount per payroll. If elective is true, the contribution is matching, dollar-for-dollar.\n\n`percentage`: The company contributes a percentage of the payroll amount per payroll period. If elective is true, the contribution is matching, dollar-for-dollar.\n\n`tiered`: The size of the company contribution corresponds to the size of the employee deduction relative to a tiered matching scheme."
},
"value": {
"oneOf": [
{
"type": "string",
"description": "For the `amount` and `percentage` contribution types, the value of the corresponding amount or percentage."
},
{
"type": "array",
"items": {
"type": "object",
"properties": {
"rate": {
"type": "string",
"description": "The percentage of employee deduction within this tier the company contribution will match."
},
"threshold": {
"type": "string",
"description": "The percentage threshold at which this tier ends (inclusive).\n\nFor 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.\n\nIf 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."
}
},
"description": "A single tier of a tiered matching scheme."
},
"description": "For `tiered` contribution types, an array of tiers."
}
],
"description": "For the `amount` and `percentage` contribution types, the value of the corresponding amount or percentage.\n\nFor the `tiered` contribution type, an array of tiers."
}
},
"description": "An object representing the type and value of the company contribution."
},
"limit_option": {
"type": "string",
"nullable": true,
"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\"."
},
"coverage_amount": {
"type": "string",
"nullable": true,
"description": "The amount that the employee is insured for. Note: company contribution cannot be present if coverage amount is set."
},
"employee_deduction": {
"type": "string",
"default": "0.00",
"description": "The amount to be deducted, per pay period, from the employee's pay."
},
"company_contribution": {
"type": "string",
"default": "0.00",
"deprecated": true,
"description": "The amount to be paid, per pay period, by the company."
},
"deduct_as_percentage": {
"type": "boolean",
"description": "Whether the employee deduction amount should be treated as a percentage to be deducted from each payroll."
},
"contribute_as_percentage": {
"type": "boolean",
"default": false,
"deprecated": true,
"description": "Whether the company contribution amount should be treated as a percentage to be deducted from each payroll."
},
"coverage_salary_multiplier": {
"type": "string",
"default": "0.00",
"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."
},
"deduction_reduces_taxable_income": {
"enum": [
"unset",
"reduces_taxable_income",
"does_not_reduce_taxable_income",
null
],
"type": "string",
"default": "unset",
"nullable": true,
"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."
},
"employee_deduction_annual_maximum": {
"type": "string",
"nullable": true,
"description": "The maximum employee deduction amount per year. A null value signifies no limit."
},
"company_contribution_annual_maximum": {
"type": "string",
"nullable": true,
"description": "The maximum company contribution amount per year. A null value signifies no limit."
}
}
}
EmployeeEmploymentsCreateTerminationRequest
{
"type": "object",
"required": [
"effective_date"
],
"properties": {
"effective_date": {
"type": "string",
"description": "The employee's last day of work."
},
"run_termination_payroll": {
"type": "boolean",
"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."
}
},
"description": ""
}
EmployeeEmploymentsGetHistoryResponse
{
"type": "array",
"items": {
"type": "object",
"properties": {
"hire_date": {
"type": "string",
"description": "The employee's start day of work for an employment."
},
"termination_date": {
"type": "string",
"description": "The employee's last day of work for an employment."
},
"employment_status": {
"enum": [
"part_time",
"full_time",
"part_time_eligible",
"variable",
"seasonal",
"not_set"
],
"type": "string",
"description": "The employee's employment status. Supplying an invalid option will set the employment_status to *not_set*."
},
"file_new_hire_report": {
"type": "boolean",
"description": "The boolean flag indicating whether Gusto will file a new hire report for the employee."
},
"two_percent_shareholder": {
"type": "boolean",
"description": "Whether the employee is a two percent shareholder of the company. This field only applies to companies with an S-Corp entity type."
}
},
"x-examples": {
"example-1": {
"hire_date": "2023-01-30",
"termination_date": "2023-03-30",
"employment_status": "seasonal",
"file_new_hire_report": false,
"two_percent_shareholder": false
}
}
}
}
EmployeeEmploymentsListEmployeeTerminationsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Termination"
}
}
EmployeeEmploymentsUpdateRehireRequest
{
"allOf": [
{
"$ref": "#/components/schemas/Versionable-Required"
},
{
"$ref": "#/components/schemas/Rehire-Body"
}
]
}
EmployeeEmploymentsUpdateTerminationRequest
{
"allOf": [
{
"$ref": "#/components/schemas/Versionable-Required"
},
{
"type": "object",
"required": [
"effective_date"
],
"properties": {
"effective_date": {
"type": "string",
"description": "The employee's last day of work."
},
"run_termination_payroll": {
"type": "boolean",
"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."
}
},
"description": ""
}
]
}
EmployeeFormsGenerateW2DocumentRequest
{
"type": "object",
"required": [
"employee_id"
],
"properties": {
"year": {
"type": "integer",
"description": "Must be equal to or more recent than 2015. If not specified, defaults to the previous year.\n"
},
"employee_id": {
"type": "string",
"description": "The employee UUID."
}
}
}
EmployeeFormsGenerateW2DocumentResponse
{
"allOf": [
{
"properties": {
"employee_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the employee"
}
}
},
{
"$ref": "#/components/schemas/Form"
}
]
}
EmployeeFormsSignFormRequest
{
"type": "object",
"required": [
"signature_text",
"agree",
"signed_by_ip_address"
],
"properties": {
"agree": {
"type": "boolean",
"description": "whether you agree to sign electronically"
},
"signature_text": {
"type": "string",
"description": "The signature"
},
"signed_by_ip_address": {
"type": "string",
"description": "The IP address of the signatory who signed the form."
}
},
"description": ""
}
EmployeePaymentMethodCreateBankAccountRequest
{
"type": "object",
"required": [
"name",
"routing_number",
"account_number",
"account_type"
],
"properties": {
"name": {
"type": "string"
},
"account_type": {
"enum": [
"Checking",
"Savings"
],
"type": "string"
},
"account_number": {
"type": "string"
},
"routing_number": {
"type": "string"
}
}
}
EmployeePaymentMethodListBankAccountsRequest
{
"type": "object",
"properties": {}
}
EmployeePaymentMethodListBankAccountsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Employee-Bank-Account"
}
}
EmployeePaymentMethodUpdatePaymentMethodRequest
{
"type": "object",
"required": [
"version",
"type"
],
"properties": {
"type": {
"enum": [
"Direct Deposit",
"Check"
],
"type": "string",
"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."
},
"splits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The bank account name"
},
"uuid": {
"type": "string",
"description": "The bank account ID\n"
},
"priority": {
"type": "integer",
"description": "The order of priority for each payment split, with priority 1 being the first bank account paid. Priority must be unique and sequential."
},
"split_amount": {
"type": "integer",
"nullable": true,
"description": "The cents amount allocated for each payment split"
}
}
}
},
"version": {
"type": "string",
"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."
},
"split_by": {
"enum": [
"Amount",
"Percentage"
],
"type": "string",
"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."
}
}
}
EmployeeTaxSetupGetStateTaxesResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Employee-State-Tax"
}
}
EmployeeTaxSetupUpdateFederalTaxesRequest
{
"type": "object",
"required": [
"version"
],
"properties": {
"version": {
"type": "string",
"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."
},
"two_jobs": {
"type": "boolean"
},
"deductions": {
"type": "string"
},
"other_income": {
"type": "string"
},
"w4_data_type": {
"type": "string"
},
"filing_status": {
"type": "string"
},
"dependents_amount": {
"type": "string"
},
"extra_withholding": {
"type": "string",
"nullable": true
}
},
"description": ""
}
EmployeeTaxSetupUpdateStateTaxesRequest
{
"type": "object",
"required": [
"states"
],
"properties": {
"states": {
"type": "array",
"items": {
"type": "object",
"required": [
"state"
],
"properties": {
"state": {
"type": "string"
},
"questions": {
"type": "array",
"items": {
"type": "object",
"required": [
"key"
],
"properties": {
"key": {
"type": "string"
},
"answers": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"valid_from"
],
"properties": {
"value": {
"type": "string"
},
"valid_from": {
"type": "string"
},
"valid_up_to": {
"nullable": true
}
}
},
"uniqueItems": true
}
}
},
"uniqueItems": true
}
}
},
"uniqueItems": true
}
},
"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
}
]
}
]
}
]
}
},
"description": ""
}
EmployeeTaxSetupUpdateStateTaxesResponse
{
"type": "array",
"items": {
"type": "object",
"required": [
"state",
"questions"
],
"properties": {
"state": {
"type": "string"
},
"questions": {
"type": "array",
"items": {
"type": "object",
"required": [
"key"
],
"properties": {
"key": {
"type": "string"
},
"answers": {
"type": "array",
"items": {
"type": "object",
"required": [
"valid_from"
],
"properties": {
"errors": {
"type": "array",
"items": {
"type": "string"
}
},
"valid_from": {
"type": "string"
},
"valid_up_to": {
"nullable": true
}
}
},
"uniqueItems": true
}
}
},
"uniqueItems": true
}
}
},
"x-examples": {
"example-1": [
{
"state": "CA",
"questions": [
{
"key": "filing_status",
"answers": [
{
"errors": [
"string"
],
"valid_from": "2010-01-01",
"valid_up_to": null
}
]
}
]
}
]
},
"description": "",
"uniqueItems": true
}
EmployeesCreateEmployeeRequest
{
"type": "object",
"required": [
"first_name",
"last_name"
],
"properties": {
"ssn": {
"type": "string",
"pattern": "[0-9]{9}"
},
"email": {
"type": "string"
},
"last_name": {
"type": "string"
},
"first_name": {
"type": "string"
},
"date_of_birth": {
"type": "string"
},
"middle_initial": {
"type": "string"
},
"self_onboarding": {
"type": "boolean",
"description": "If true, employee is expected to self-onboard. If false, payroll admin is expected to enter in the employee's onboarding information"
}
},
"description": ""
}
EmployeesGetCustomFieldsResponse
{
"type": "object",
"properties": {
"custom_fields": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Employee-Custom-Field"
}
}
}
}
EmployeesGetOnboardingStatusResponse
{
"type": "object",
"properties": {}
}
EmployeesListCompanyEmployeesRequest
{
"type": "object",
"properties": {}
}
EmployeesListCompanyEmployeesResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Employee"
}
}
EmployeesUpdateEmployeeRequest
{
"type": "object",
"required": [
"version"
],
"properties": {
"ssn": {
"type": "string",
"pattern": "[0-9]{9}"
},
"email": {
"type": "string"
},
"version": {
"type": "string",
"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."
},
"last_name": {
"type": "string"
},
"first_name": {
"type": "string"
},
"date_of_birth": {
"type": "string"
},
"middle_initial": {
"type": "string"
},
"two_percent_shareholder": {
"type": "boolean",
"description": "Whether the employee is a two percent shareholder of the company. This field only applies to companies with an S-Corp entity type."
}
},
"description": ""
}
EmployeesUpdateOnboardingStatusRequest
{
"type": "object",
"required": [
"onboarding_status"
],
"properties": {
"onboarding_status": {
"type": "string",
"description": "The updated onboarding status for the employee"
}
}
}
Event
{
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "Unique identifier for the event."
},
"timestamp": {
"type": "integer",
"description": "Time at which this event was created. Measured in seconds since the Unix epoch."
},
"event_type": {
"type": "string",
"description": "Description of the event (e.g., payroll.submitted, or company.form.signed)."
},
"entity_type": {
"type": "string",
"description": "Name of the entity that the event corresponds to."
},
"entity_uuid": {
"type": "string",
"description": "Unique identifier for the entity."
},
"resource_type": {
"enum": [
"Company"
],
"type": "string",
"description": "Name of the parent resource of the described entity."
},
"resource_uuid": {
"type": "string",
"description": "Unique identifier for the parent resource."
}
},
"x-examples": {
"example": {
"uuid": "f7397a24-57ad-4fae-b011-d258e8232900",
"timestamp": 1686784995,
"event_type": "employee.bank_account.created",
"entity_type": "BankAccount",
"entity_uuid": "92a20431-9489-4bde-ad27-6feb20b969d5",
"resource_type": "Company",
"resource_uuid": "92a20431-9489-4bde-ad27-6feb20b969d5"
}
},
"description": "Representation of an Event"
}
EventsGet30DayEventsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Event"
}
}
External-Payroll
{
"type": "object",
"title": "",
"x-tags": [
"External Payrolls"
],
"properties": {
"uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the external payroll."
},
"status": {
"enum": [
"unprocessed",
"processed"
],
"type": "string",
"readOnly": true,
"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."
},
"metadata": {
"type": "object",
"readOnly": true,
"properties": {
"deletable": {
"type": "boolean",
"readOnly": true,
"description": "Determines if the external payroll can be deleted."
}
},
"description": "Stores metadata of the external payroll."
},
"check_date": {
"type": "string",
"readOnly": true,
"description": "External payroll's check date."
},
"company_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the company."
},
"applicable_taxes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"employer_tax": {
"type": "boolean",
"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."
},
"resident_tax": {
"type": "boolean",
"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."
}
}
},
"readOnly": true,
"description": "Applicable taxes based on company provisioning."
},
"applicable_benefits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"active": {
"type": "boolean"
},
"description": {
"type": "string"
}
}
},
"readOnly": true,
"description": "Applicable benefits based on company provisioning."
},
"applicable_earnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"category": {
"type": "string"
},
"earning_id": {
"type": "number"
},
"input_type": {
"type": "string"
},
"earning_type": {
"type": "string"
}
}
},
"readOnly": true,
"description": "Applicable earnings based on company provisioning."
},
"external_payroll_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"taxes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"format": "float"
},
"tax_id": {
"type": "integer"
}
}
}
},
"benefits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"benefit_id": {
"type": "integer"
},
"employee_deduction_amount": {
"type": "string",
"format": "float"
},
"company_contribution_amount": {
"type": "string",
"format": "float"
}
}
}
},
"earnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"hours": {
"type": "string",
"format": "float"
},
"amount": {
"type": "string",
"format": "float"
},
"earning_id": {
"type": "integer"
},
"earning_type": {
"type": "string"
}
}
}
},
"employee_uuid": {
"type": "string"
}
}
},
"readOnly": true,
"description": "External payroll items for employees"
},
"payment_period_end_date": {
"type": "string",
"readOnly": true,
"description": "External payroll's pay period end date."
},
"payment_period_start_date": {
"type": "string",
"readOnly": true,
"description": "External payroll's pay period start date."
}
},
"x-examples": {
"Example": {
"uuid": "c5fdae57-5483-4529-9aae-f0edceed92d4",
"status": "unprocessed",
"metadata": {
"deletable": true
},
"check_date": "2022-06-03",
"company_uuid": "bcb305b0-2855-4025-8d22-e484a9e6b7c9",
"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
}
],
"applicable_benefits": [
{
"id": 22,
"active": true,
"description": "Kaiser"
},
{
"id": 25,
"active": true,
"description": "HSA"
}
],
"applicable_earnings": [
{
"name": "Regular Wages",
"category": "default",
"earning_id": 1,
"input_type": "amount",
"earning_type": "CompanyPayType"
},
{
"name": "Cash Tips",
"category": "default",
"earning_id": 4,
"input_type": "amount",
"earning_type": "CompanyEarningType"
}
],
"external_payroll_items": [
{
"taxes": [
{
"amount": 400,
"tax_id": 1
},
{
"amount": 60,
"tax_id": 2
}
],
"benefits": [
{
"benefit_id": 22,
"employee_deduction_amount": 50,
"company_contribution_amount": 100
},
{
"benefit_id": 25,
"employee_deduction_amount": 300,
"company_contribution_amount": 0
}
],
"earnings": [
{
"hours": 0,
"amount": 10000,
"earning_id": 1,
"earning_type": "CompanyPayType"
},
{
"hours": 0,
"amount": 500,
"earning_id": 4,
"earning_type": "CompanyEarningType"
}
],
"employee_uuid": "44f7cba9-7a3d-4f08-b7bd-6fcf5211f8ca"
}
],
"payment_period_end_date": "2022-05-30",
"payment_period_start_date": "2022-05-15"
}
},
"description": "The representation of an external payroll."
}
External-Payroll-Basic
{
"type": "object",
"title": "",
"x-tags": [
"External Payrolls"
],
"properties": {
"uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the external payroll."
},
"status": {
"enum": [
"unprocessed",
"processed"
],
"type": "string",
"readOnly": true,
"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."
},
"check_date": {
"type": "string",
"readOnly": true,
"description": "External payroll's check date."
},
"company_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the company."
},
"payment_period_end_date": {
"type": "string",
"readOnly": true,
"description": "External payroll's pay period end date."
},
"payment_period_start_date": {
"type": "string",
"readOnly": true,
"description": "External payroll's pay period start date."
}
},
"x-examples": {
"Example": {
"uuid": "c5fdae57-5483-4529-9aae-f0edceed92d4",
"check_date": "2022-06-03",
"company_uuid": "bcb305b0-2855-4025-8d22-e484a9e6b7c9",
"payment_period_end_date": "2022-05-30",
"payment_period_start_date": "2022-05-15"
}
},
"description": "The representation of an external payroll with minimal information."
}
External-Payroll-Tax-Suggestions
{
"type": "object",
"title": "",
"x-tags": [
"External Payrolls"
],
"properties": {
"employee_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the employee."
},
"tax_suggestions": {
"type": "object",
"readOnly": true,
"properties": {
"amount": {
"type": "string",
"readOnly": true,
"description": "Calculated tax amount."
},
"tax_id": {
"type": "integer",
"readOnly": true,
"description": "The ID of the tax."
}
},
"description": "Possible tax liabilities selections."
}
},
"x-examples": {
"Example": {
"employee_uuid": "d21848d5-446f-48a8-9430-30fbefeabda4",
"tax_suggestions": [
{
"amount": 500,
"tax_id": 1
},
{
"amount": 100,
"tax_id": 2
},
{
"amount": 30,
"tax_id": 4
}
]
}
},
"description": "The representation of an external payroll with minimal information."
}
ExternalPayrollsCreateNewPayrollRequest
{
"type": "object",
"required": [
"check_date",
"payment_period_start_date",
"payment_period_end_date"
],
"properties": {
"check_date": {
"type": "string",
"description": "External payroll's check date."
},
"payment_period_end_date": {
"type": "string",
"description": "External payroll's pay period end date."
},
"payment_period_start_date": {
"type": "string",
"description": "External payroll's pay period start date."
}
},
"description": ""
}
ExternalPayrollsGetTaxLiabilitiesResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Tax-Liabilities-Selections"
}
}
ExternalPayrollsGetTaxSuggestionsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/External-Payroll-Tax-Suggestions"
}
}
ExternalPayrollsListForCompanyResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/External-Payroll-Basic"
}
}
ExternalPayrollsUpdatePayrollItemsRequest
{
"type": "object",
"properties": {
"replace_fields": {
"type": "boolean",
"description": "Patch update external payroll items when set to true, otherwise it will overwrite the previous changes."
},
"external_payroll_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"taxes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"description": "The amount of the tax."
},
"tax_id": {
"type": "integer",
"description": "The ID of the tax."
}
}
},
"description": "An array of taxes for the employee. Depends on your company selections, taxes include federal income tax, social security, medicare, and more."
},
"benefits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"benefit_id": {
"type": "integer",
"description": "The ID of the benefit."
},
"employee_deduction_amount": {
"type": "string",
"description": "Employee deduction amount towards the benefit"
},
"company_contribution_amount": {
"type": "string",
"description": "Company contribution amount towards the benefit"
}
},
"description": "An array of benefits for the employee. Depends on your company selections, benefits include 401k, health insurance and more."
}
},
"earnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"hours": {
"type": "string",
"description": "The hour of the compensation for the pay period."
},
"amount": {
"type": "string",
"description": "The amount of the earning."
},
"earning_id": {
"type": "integer",
"description": "The ID of the earning."
},
"earning_type": {
"enum": [
"CompanyPayType",
"CompanyEarningType"
],
"type": "string",
"description": "The earning type for the compensation."
}
},
"description": "An array of earnings for the employee. Depends on your company selections, earnings includes wages, hours, bonuses, tips, commission and more."
}
},
"employee_uuid": {
"type": "string",
"description": "The UUID of the employee."
}
},
"description": "Submit wages, benefits, taxes for each employee"
}
}
}
}
ExternalPayrollsUpdateTaxLiabilitiesRequest
{
"type": "object",
"properties": {
"liability_selections": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tax_id": {
"type": "integer",
"description": "The ID of the tax."
},
"unpaid_liability_amount": {
"type": "number",
"description": "A selection of unpaid liability amount."
},
"last_unpaid_external_payroll_uuid": {
"type": "string",
"nullable": true,
"description": "The UUID of the last unpaid external payroll uuid. It should be null when the full amount of tax liability has been paid."
}
},
"description": ""
}
}
}
}
Federal-Tax-Details
{
"type": "object",
"title": "Federal-Tax-Details",
"x-tags": [
"Federal Tax Details"
],
"properties": {
"has_ein": {
"type": "boolean",
"description": "Whether company's Employer Identification Number (EIN) is present"
},
"version": {
"type": "string",
"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."
},
"legal_name": {
"type": "string",
"description": "The legal name of the company"
},
"filing_form": {
"type": "string",
"description": "The form used by the company for federal tax filing. One of:\n- 941 (Quarterly federal tax return form)\n- 944 (Annual federal tax return form)"
},
"ein_verified": {
"type": "boolean",
"description": "Whether the EIN was able to be verified as a valid EIN with the IRS. "
},
"tax_payer_type": {
"type": "string",
"description": "What type of tax entity the company is. One of:\n- C-Corporation\n- S-Corporation\n- Sole proprietor\n- LLC\n- LLP\n- Limited partnership\n- Co-ownership\n- Association\n- Trusteeship\n- General partnership\n- Joint venture\n- Non-Profit"
},
"taxable_as_scorp": {
"type": "boolean",
"description": "Whether the company is taxed as an S-Corporation. Tax payer types that may be taxed as an S-Corporation include:\n- S-Corporation\n- C-Corporation\n- LLC"
}
},
"x-examples": {
"Example": {
"value": {
"has_ein": true,
"version": "string",
"legal_name": "string",
"filing_form": "string",
"ein_verified": true,
"tax_payer_type": "string",
"taxable_as_scorp": false
}
}
}
}
FederalTaxDetailsUpdateAttributesRequest
{
"type": "object",
"required": [
"version"
],
"properties": {
"ein": {
"type": "string",
"description": "The EIN of of the company"
},
"version": {
"type": "string",
"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."
},
"legal_name": {
"type": "string",
"description": "The legal name of the company"
},
"filing_form": {
"type": "string",
"description": "The form used by the company for federal tax filing. One of:\n- 941 (Quarterly federal tax return)\n- 944 (Annual federal tax return)"
},
"tax_payer_type": {
"enum": [
"C-Corporation",
"S-Corporation",
"Sole proprietor",
"LLC",
"LLP",
"Limited partnership",
"Co-ownership",
"Association",
"Trusteeship",
"General partnership",
"Joint venture",
"Non-Profit"
],
"type": "string",
"description": "What type of tax entity the company is"
},
"taxable_as_scorp": {
"type": "boolean",
"description": "Whether this company should be taxed as an S-Corporation"
}
}
}
Flow
{
"type": "object",
"title": "Flow",
"x-tags": [
"Flows"
],
"properties": {
"url": {
"type": "string"
},
"expires_at": {
"type": "string"
}
},
"x-examples": {
"Example": {
"url": "https://flows.gusto-demo.com/flows/lO2BHHAMCScPVV9G5WEURW0Im_nP9mGYloQgjUWbenQ",
"expires_at": "2021-12-28 04:25:48"
}
},
"description": "The representation of a flow in Gusto white-label UI."
}
FlowsGenerateLinkRequest
{
"type": "object",
"required": [
"flow_type"
],
"properties": {
"flow_type": {
"type": "string",
"description": "flow type"
},
"entity_type": {
"enum": [
"Company",
"Employee"
],
"type": "string",
"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."
},
"entity_uuid": {
"type": "string",
"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."
}
}
}
Flsa-Status-Type
{
"enum": [
"Exempt",
"Salaried Nonexempt",
"Nonexempt",
"Owner",
"Commission Only Exempt",
"Commission Only Nonexempt"
],
"type": "string",
"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. "
}
Form
{
"type": "object",
"title": "Form",
"x-tags": [
"Forms"
],
"properties": {
"name": {
"type": "string",
"readOnly": true,
"description": "The type identifier of the form"
},
"uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the form"
},
"year": {
"type": "integer",
"nullable": true,
"readOnly": true,
"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."
},
"draft": {
"type": "boolean",
"readOnly": true,
"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."
},
"title": {
"type": "string",
"readOnly": true,
"description": "The title of the form"
},
"quarter": {
"type": "integer",
"nullable": true,
"readOnly": true,
"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."
},
"description": {
"type": "string",
"readOnly": true,
"description": "The description of the form"
},
"requires_signing": {
"type": "boolean",
"readOnly": true,
"description": "A boolean flag that indicates whether the form needs signing or not. Note that this value will change after the form is signed."
}
},
"x-examples": {
"Example": {
"name": "company_direct_deposit",
"uuid": "48cdd5ec-a4dd-4840-a424-ad79f38d8408",
"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.",
"requires_signing": true
}
}
}
Form-Pdf
{
"type": "object",
"title": "Form Pdf",
"properties": {
"uuid": {
"type": "string",
"readOnly": true,
"description": "the UUID of the form"
},
"document_url": {
"type": "string",
"description": "the URL of the form"
}
}
}
Form_1099
{
"type": "object",
"title": "Form",
"x-tags": [
"Forms"
],
"properties": {
"name": {
"type": "string",
"readOnly": true,
"description": "The type identifier of the form"
},
"uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the form"
},
"year": {
"type": "integer",
"nullable": true,
"readOnly": true,
"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."
},
"draft": {
"type": "boolean",
"readOnly": true,
"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."
},
"title": {
"type": "string",
"readOnly": true,
"description": "The title of the form"
},
"quarter": {
"type": "integer",
"nullable": true,
"readOnly": true,
"description": "The quarter of this form. This value is currently always null since it is not present on any contractor forms."
},
"description": {
"type": "string",
"readOnly": true,
"description": "The description of the form"
},
"contractor_uuid": {
"type": "string",
"readOnly": true,
"description": "The contractor UUID"
},
"requires_signing": {
"type": "boolean",
"readOnly": true,
"description": "A boolean flag that indicates whether the form needs signing or not. Note that this value will change after the form is signed."
}
},
"x-examples": {
"Example": {
"name": "US_1099",
"uuid": "48cdd5ec-a4dd-4840-a424-ad79f38d8408",
"year": 2020,
"draft": false,
"title": "Form 1099: 2020",
"quarter": null,
"description": "Form 1099 records your annual income as a contractor.",
"contractor_uuid": "123dd616-6dbc-4724-938a-403f6217a933",
"requires_signing": false
}
}
}
Garnishment
{
"type": "object",
"properties": {
"uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the garnishment in Gusto."
},
"times": {
"type": "integer",
"default": null,
"nullable": true,
"readOnly": false,
"description": "The number of times to apply the garnishment. Ignored if recurring is true."
},
"active": {
"type": "boolean",
"default": true,
"description": "Whether or not this garnishment is currently active."
},
"amount": {
"type": "string",
"format": "float",
"readOnly": false,
"description": "The amount of the garnishment. Either a percentage or a fixed dollar amount. Represented as a float, e.g. \"8.00\"."
},
"version": {
"type": "string",
"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."
},
"recurring": {
"type": "boolean",
"default": false,
"readOnly": false,
"description": "Whether the garnishment should recur indefinitely."
},
"description": {
"type": "string",
"readOnly": false,
"description": "The description of the garnishment."
},
"court_ordered": {
"type": "boolean",
"readOnly": false,
"description": "Whether the garnishment is court ordered."
},
"employee_uuid": {
"type": "integer",
"readOnly": true,
"description": "The UUID of the employee to which this garnishment belongs."
},
"annual_maximum": {
"type": "string",
"format": "float",
"default": null,
"nullable": true,
"readOnly": false,
"description": "The maximum deduction per annum. A null value indicates no maximum. Represented as a float, e.g. \"200.00\"."
},
"pay_period_maximum": {
"type": "string",
"format": "float",
"default": null,
"nullable": true,
"description": "The maximum deduction per pay period. A null value indicates no maximum. Represented as a float, e.g. \"16.00\"."
},
"deduct_as_percentage": {
"type": "boolean",
"default": false,
"readOnly": false,
"description": "Whether the amount should be treated as a percentage to be deducted per pay period."
}
},
"x-examples": {
"Example": {
"uuid": "4c7841a2-1363-497e-bc0f-664703c7484f",
"times": 5,
"active": true,
"amount": "8.00",
"version": "52b7c567242cb7452e89ba2bc02cb476",
"recurring": false,
"description": "Company loan to employee",
"court_ordered": false,
"employee_uuid": "a6b53294-f871-4db2-bbd4-8c3d1fe56440",
"annual_maximum": null,
"pay_period_maximum": "100.00",
"deduct_as_percentage": true
}
},
"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."
}
GarnishmentsCreateGarnishmentRequest
{
"type": "object",
"required": [
"amount",
"description",
"court_ordered"
],
"properties": {
"times": {
"type": "integer",
"default": null,
"nullable": true,
"readOnly": false,
"description": "The number of times to apply the garnishment. Ignored if recurring is true."
},
"active": {
"type": "boolean",
"default": true,
"description": "Whether or not this garnishment is currently active."
},
"amount": {
"type": "string",
"format": "float",
"readOnly": false,
"description": "The amount of the garnishment. Either a percentage or a fixed dollar amount. Represented as a float, e.g. \"8.00\"."
},
"recurring": {
"type": "boolean",
"default": false,
"readOnly": false,
"description": "Whether the garnishment should recur indefinitely."
},
"description": {
"type": "string",
"readOnly": false,
"description": "The description of the garnishment."
},
"court_ordered": {
"type": "boolean",
"readOnly": false,
"description": "Whether the garnishment is court ordered."
},
"annual_maximum": {
"type": "string",
"format": "float",
"default": null,
"nullable": true,
"readOnly": false,
"description": "The maximum deduction per annum. A null value indicates no maximum. Represented as a float, e.g. \"200.00\"."
},
"pay_period_maximum": {
"type": "string",
"format": "float",
"default": null,
"nullable": true,
"description": "The maximum deduction per pay period. A null value indicates no maximum. Represented as a float, e.g. \"16.00\"."
},
"deduct_as_percentage": {
"type": "boolean",
"default": false,
"readOnly": false,
"description": "Whether the amount should be treated as a percentage to be deducted per pay period."
}
},
"description": ""
}
GarnishmentsGetEmployeeGarnishmentsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Garnishment"
}
}
GarnishmentsUpdateGarnishmentRequest
{
"type": "object",
"required": [
"version"
],
"properties": {
"times": {
"type": "integer",
"default": null,
"nullable": true,
"readOnly": false,
"description": "The number of times to apply the garnishment. Ignored if recurring is true."
},
"active": {
"type": "boolean",
"default": true,
"description": "Whether or not this garnishment is currently active."
},
"amount": {
"type": "string",
"format": "float",
"readOnly": false,
"description": "The amount of the garnishment. Either a percentage or a fixed dollar amount. Represented as a float, e.g. \"8.00\"."
},
"version": {
"type": "string",
"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."
},
"recurring": {
"type": "boolean",
"default": false,
"readOnly": false,
"description": "Whether the garnishment should recur indefinitely."
},
"description": {
"type": "string",
"readOnly": false,
"description": "The description of the garnishment."
},
"court_ordered": {
"type": "boolean",
"readOnly": false,
"description": "Whether the garnishment is court ordered."
},
"annual_maximum": {
"type": "string",
"format": "float",
"default": null,
"nullable": true,
"readOnly": false,
"description": "The maximum deduction per annum. A null value indicates no maximum. Represented as a float, e.g. \"200.00\"."
},
"pay_period_maximum": {
"type": "string",
"format": "float",
"default": null,
"nullable": true,
"description": "The maximum deduction per pay period. A null value indicates no maximum. Represented as a float, e.g. \"16.00\"."
},
"deduct_as_percentage": {
"type": "boolean",
"default": false,
"readOnly": false,
"description": "Whether the amount should be treated as a percentage to be deducted per pay period."
}
}
}
Generated-Document
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Current status of the Generated Document"
},
"request_uuid": {
"type": "string",
"description": "A unique identifier of the Generated Document request"
},
"document_urls": {
"type": "array",
"items": {
"type": "string"
},
"description": "The array of urls to access the documents."
}
},
"x-examples": {
"example-1": {
"status": "succeeded",
"request_uuid": "p83d0ca8-7d41-42a9-834y-7d218ef6cb20",
"document_urls": [
"https://document.url.com"
]
}
}
}
Gross-Up-Pay
{
"type": "object",
"properties": {
"gross_up": {
"type": "string",
"description": "Gross up earnings."
}
}
}
Holiday-Pay-Policy
{
"type": "object",
"required": [
"version",
"company_uuid",
"federal_holidays",
"employees"
],
"properties": {
"version": {
"type": "string",
"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."
},
"employees": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uuid": {
"type": "string"
}
}
},
"description": "List of employee uuids under a time off policy"
},
"company_uuid": {
"type": "string",
"description": "A unique identifier for the company owning the holiday pay policy"
},
"federal_holidays": {
"type": "array",
"items": {
"type": "object",
"properties": {
"mlk_day": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"name": {
"type": "string"
},
"selected": {
"type": "boolean"
}
}
},
"labor_day": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"name": {
"type": "string"
},
"selected": {
"type": "boolean"
}
}
},
"juneteenth": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"name": {
"type": "string"
},
"selected": {
"type": "boolean"
}
}
},
"columbus_day": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"name": {
"type": "string"
},
"selected": {
"type": "boolean"
}
}
},
"memorial_day": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"name": {
"type": "string"
},
"selected": {
"type": "boolean"
}
}
},
"thanksgiving": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"name": {
"type": "string"
},
"selected": {
"type": "boolean"
}
}
},
"veterans_day": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"name": {
"type": "string"
},
"selected": {
"type": "boolean"
}
}
},
"new_years_day": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"name": {
"type": "string"
},
"selected": {
"type": "boolean"
}
}
},
"presidents_day": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"name": {
"type": "string"
},
"selected": {
"type": "boolean"
}
}
},
"independence_day": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"name": {
"type": "string"
},
"selected": {
"type": "boolean"
}
}
}
}
},
"description": "List of the eleven supported federal holidays and their details"
}
},
"x-examples": {
"example": {
"version": "1b37938b017c7fd7116bada007072290",
"employees": {
"uuid": "1ca3cd25-3eda-48c6-ac88-f0e7fb91a15a"
},
"company_uuid": "b7845189-f12b-4378-918a-d2b9de3dc4ea",
"federal_holidays": {
"mlk_day": {
"date": "Third Monday in January",
"name": "Martin Luther King, Jr. Day",
"selected": true
},
"labor_day": {
"date": "First Monday in September",
"name": "Labor Day",
"selected": false
},
"juneteenth": {
"date": "June 19",
"name": "Juneteenth",
"selected": false
},
"columbus_day": {
"date": "Second Monday in October",
"name": "Columbus Day (Indigenous Peoples' Day)",
"selected": false
},
"memorial_day": {
"date": "Last Monday in May",
"name": "Memorial Day",
"selected": true
},
"thanksgiving": {
"date": "Fourth Thursday in November",
"name": "Thanksgiving",
"selected": true
},
"veterans_day": {
"date": "November 11",
"name": "Veterans Day",
"selected": true
},
"christmas_day": {
"date": "December 25",
"name": "Christmas Day",
"selected": true
},
"new_years_day": {
"date": "January 1",
"name": "New Year's Day",
"selected": true
},
"presidents_day": {
"date": "Third Monday in February",
"name": "Presidents' Day",
"selected": false
},
"independence_day": {
"date": "July 4",
"name": "Independence Day",
"selected": true
}
}
}
},
"description": "Representation of a Holiday Pay Policy"
}
HolidayPayPoliciesAddEmployeesToPolicyRequest
{
"type": "object",
"required": [
"version"
],
"properties": {
"version": {
"type": "string",
"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."
},
"employees": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uuid": {
"type": "string"
}
}
},
"description": "An array of employee objects, each containing an employee_uuid."
}
}
}
HolidayPayPoliciesCreateCompanyPolicyRequest
{
"type": "object",
"properties": {
"federal_holidays": {
"type": "object",
"properties": {
"mlk_day": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
},
"labor_day": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
},
"juneteenth": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
},
"columbus_day": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
},
"memorial_day": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
},
"thanksgiving": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
},
"veterans_day": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
},
"christmas_day": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
},
"new_years_day": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
},
"presidents_day": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
},
"independence_day": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
}
},
"description": "An object containing federal holiday objects, each containing a boolean selected property."
}
}
}
HolidayPayPoliciesPreviewCompanyPaidHolidaysRequest
{
"type": "object",
"properties": {
"year": {
"type": "string",
"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."
}
}
}
HolidayPayPoliciesRemoveEmployeesRequest
{
"type": "object",
"required": [
"version"
],
"properties": {
"version": {
"type": "string",
"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."
},
"employees": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uuid": {
"type": "string"
}
}
},
"description": "An array of employee objects, each containing an employee_uuid."
}
}
}
HolidayPayPoliciesUpdatePolicyRequest
{
"type": "object",
"required": [
"version"
],
"properties": {
"version": {
"type": "string",
"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."
},
"federal_holidays": {
"type": "object",
"properties": {
"mlk_day": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
},
"labor_day": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
},
"juneteenth": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
},
"columbus_day": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
},
"memorial_day": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
},
"thanksgiving": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
},
"veterans_day": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
},
"christmas_day": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
},
"new_years_day": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
},
"presidents_day": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
},
"independence_day": {
"type": "object",
"properties": {
"selected": {
"type": "boolean"
}
}
}
},
"description": "An object containing federal holiday objects, each containing a boolean selected property."
}
}
}
Industry
{
"type": "object",
"title": "Industry",
"x-tags": [
"Industry"
],
"properties": {
"title": {
"type": "string",
"readOnly": true,
"description": "Industry title"
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
},
"readOnly": true,
"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."
},
"naics_code": {
"type": "string",
"readOnly": true,
"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."
},
"company_uuid": {
"type": "string",
"readOnly": true,
"description": "Company uuid"
}
},
"x-examples": {
"Example": {
"title": "Computer Training",
"sic_codes": [
"8243"
],
"naics_code": "611420",
"company_uuid": "423dd616-6dbc-4724-938a-403f6217a933"
}
}
}
IndustrySelectionUpdateCompanyIndustrySelectionRequest
{
"type": "object",
"required": [
"title",
"naics_code"
],
"properties": {
"title": {
"type": "string",
"description": "Industry title"
},
"sic_codes": {
"type": "array",
"items": {
"type": "string"
},
"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."
},
"naics_code": {
"type": "string",
"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"
}
},
"description": ""
}
IntrospectionExchangeRefreshTokenRequest
{
"type": "object",
"required": [
"client_id",
"client_secret",
"grant_type",
"refresh_token"
],
"properties": {
"client_id": {
"type": "string",
"description": "Your client id"
},
"grant_type": {
"type": "string",
"description": "this should be the literal string 'refresh_token'"
},
"redirect_uri": {
"type": "string",
"description": "The redirect URI you set up via the Developer Portal"
},
"client_secret": {
"type": "string",
"description": "Your client secret"
},
"refresh_token": {
"type": "string",
"description": "The `refresh_token` being exchanged for an access token code"
}
},
"description": ""
}
IntrospectionGetCurrentAccessTokenInfoResponse
{
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "Space delimited string of accessible scopes."
},
"resource": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Type of object"
},
"uuid": {
"type": "string",
"description": "UUID of object"
}
},
"description": "Information about the token resource."
}
},
"description": ""
}
Invoice-Data
{
"type": "object",
"properties": {
"active_companies": {
"type": "array",
"items": {
"type": "object",
"properties": {
"company_uuid": {
"type": "string",
"description": "unique identifier for the company associated with the invoice data"
},
"active_employees": {
"type": "integer",
"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."
},
"active_contractors": {
"type": "integer",
"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."
},
"initial_invoice_period": {
"type": "string",
"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."
}
}
},
"description": "The list of companies that are active within the invoice period"
}
},
"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"
}
]
}
},
"description": "Representation of a partners invoice data"
}
Job
{
"type": "object",
"title": "Job",
"x-tags": [
"Jobs and Compensations"
],
"properties": {
"rate": {
"type": "string",
"readOnly": true,
"description": "The current compensation rate of the job."
},
"uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the job."
},
"title": {
"type": "string",
"default": null,
"nullable": true,
"readOnly": false,
"description": "The title for the job."
},
"primary": {
"type": "boolean",
"readOnly": true,
"description": "Whether this is the employee's primary job. The value will be set to true unless an existing job exists for the employee."
},
"version": {
"type": "string",
"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."
},
"hire_date": {
"type": "string",
"readOnly": false,
"description": "The date when the employee was hired or rehired for the job."
},
"payment_unit": {
"type": "string",
"readOnly": true,
"description": "The payment unit of the current compensation for the job."
},
"compensations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Compensation"
},
"readOnly": true
},
"employee_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the employee to which the job belongs."
},
"state_wc_covered": {
"type": "boolean",
"readOnly": false,
"description": "Whether this job is eligible for workers' compensation coverage in the state of Washington (WA)."
},
"state_wc_class_code": {
"type": "string",
"readOnly": false,
"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."
},
"two_percent_shareholder": {
"type": "boolean",
"readOnly": false,
"description": "Whether the employee owns at least 2% of the company."
},
"current_compensation_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the current compensation of the job."
}
},
"x-examples": {
"Example": {
"rate": "78000.00",
"uuid": "d6d1035e-8a21-4e1d-89d5-fa894f9aff97",
"title": "Account Director",
"primary": true,
"version": "d0e719137f89ca3dd334dd4cc248ffbb",
"hire_date": "2020-01-20",
"payment_unit": "Year",
"compensations": [
{
"rate": "78000.00",
"uuid": "ea8b0b90-1112-4f9d-bb93-bf029bc8537a",
"version": "994b75511d1debac5d7e2ddeae13679f",
"job_uuid": "d6d1035e-8a21-4e1d-89d5-fa894f9aff97",
"flsa_status": "Exempt",
"payment_unit": "Year",
"effective_date": "2021-01-20",
"adjust_for_minimum_wage": false
}
],
"employee_uuid": "948daac8-4355-4ece-9e2a-229898accb22",
"current_compensation_uuid": "ea8b0b90-1112-4f9d-bb93-bf029bc8537a"
}
},
"description": "The representation of a job in Gusto."
}
JobsAndCompensationsCreateCompensationRequest
{
"type": "object",
"required": [
"payment_unit",
"flsa_status"
],
"properties": {
"rate": {
"type": "string",
"description": "The dollar amount paid per payment unit."
},
"flsa_status": {
"$ref": "#/components/schemas/Flsa-Status-Type"
},
"payment_unit": {
"enum": [
"Hour",
"Week",
"Month",
"Year",
"Paycheck"
],
"type": "string",
"description": "The unit accompanying the compensation rate. If the employee is an owner, rate should be 'Paycheck'."
},
"minimum_wages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "The UUID of the minimum wage record. Required if adjust_for_minimum_wage set to true"
}
},
"description": "The minimum wage record you want to apply to the compensation"
}
},
"effective_date": {
"type": "string",
"description": "The date when the compensation takes effect."
},
"adjust_for_minimum_wage": {
"type": "boolean",
"description": "Determines whether the compensation should be adjusted for minimum wage. Only applies to Nonexempt employees."
}
},
"description": ""
}
JobsAndCompensationsCreateCompensationResponse
{
"type": "object",
"properties": {}
}
JobsAndCompensationsCreateJobRequest
{
"type": "object",
"required": [
"title",
"hire_date"
],
"properties": {
"title": {
"type": "string",
"description": "The job title"
},
"hire_date": {
"type": "string",
"description": "The date when the employee was hired or rehired for the job."
},
"state_wc_covered": {
"type": "boolean",
"description": "Whether this job is eligible for workers' compensation coverage in the state of Washington (WA)."
},
"state_wc_class_code": {
"type": "string",
"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."
},
"two_percent_shareholder": {
"type": "boolean",
"description": "Whether the employee owns at least 2% of the company."
}
},
"description": ""
}
JobsAndCompensationsGetEmployeeJobsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Job"
}
}
JobsAndCompensationsGetJobCompensationsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Compensation"
}
}
JobsAndCompensationsUpdateCompensationRequest
{
"type": "object",
"required": [
"version"
],
"properties": {
"rate": {
"type": "string",
"description": "The dollar amount paid per payment unit."
},
"version": {
"type": "string",
"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."
},
"flsa_status": {
"$ref": "#/components/schemas/Flsa-Status-Type"
},
"payment_unit": {
"enum": [
"Hour",
"Week",
"Month",
"Year",
"Paycheck"
],
"type": "string",
"description": "The unit accompanying the compensation rate. If the employee is an owner, rate should be 'Paycheck'."
},
"minimum_wages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "The UUID of the minimum wage record. Required if adjust_for_minimum_wage set to true"
}
},
"description": "The minimum wage record you want to apply to the compensation"
}
},
"adjust_for_minimum_wage": {
"type": "boolean",
"description": "Determines whether the compensation should be adjusted for minimum wage. Only applies to Nonexempt employees."
}
},
"description": ""
}
JobsAndCompensationsUpdateJobRequest
{
"type": "object",
"required": [
"version"
],
"properties": {
"title": {
"type": "string",
"description": "The job title"
},
"version": {
"type": "string",
"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."
},
"hire_date": {
"type": "string",
"description": "The date when the employee was hired or rehired for the job."
},
"state_wc_covered": {
"type": "boolean",
"description": "Whether this job is eligible for workers' compensation coverage in the state of Washington (WA)."
},
"state_wc_class_code": {
"type": "string",
"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."
},
"two_percent_shareholder": {
"type": "boolean",
"description": "Whether the employee owns at least 2% of the company."
}
},
"description": ""
}
Location
{
"type": "object",
"title": "",
"x-tags": [
"Locations"
],
"properties": {
"zip": {
"type": "string",
"readOnly": false
},
"city": {
"type": "string",
"readOnly": false
},
"uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the location object."
},
"state": {
"type": "string",
"readOnly": false
},
"active": {
"type": "boolean",
"readOnly": true,
"description": "The status of the location. Inactive locations have been deleted, but may still have historical data associated with them."
},
"country": {
"type": "string",
"default": "USA",
"readOnly": false
},
"version": {
"type": "string",
"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."
},
"street_1": {
"type": "string",
"readOnly": false
},
"street_2": {
"type": "string",
"nullable": true,
"readOnly": false
},
"created_at": {
"type": "string",
"description": "Datetime for when location is created"
},
"updated_at": {
"type": "string",
"description": "Datetime for when location is updated"
},
"company_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID for the company to which the location belongs. Only included if the location belongs to a company."
},
"phone_number": {
"type": "string",
"readOnly": false,
"description": "The phone number for the location. Required for company locations. Optional for employee locations."
},
"filing_address": {
"type": "boolean",
"nullable": true,
"description": "Specifies if the location is the company's filing address. Only included if the location belongs to a company."
},
"mailing_address": {
"type": "boolean",
"nullable": true,
"description": "Specifies if the location is the company's mailing address. Only included if the location belongs to a company."
}
},
"x-examples": {
"Company Location": {
"zip": "94107",
"city": "San Francisco",
"uuid": "064a4107-c9f4-4fad-acbf-f12cd81c0d6c",
"state": "CA",
"active": true,
"country": "USA",
"version": "7d9753112507b9dda4fb97910f39b06e",
"street_1": "412 Kiera Stravenue",
"street_2": "Suite 391",
"created_at": "2023-09-12T16:42:25.000-07:00",
"updated_at": "2023-09-12T16:42:25.000-07:00",
"company_uuid": "768a1043-f6bf-4f0b-a606-98465ea01ad7",
"phone_number": "5825710808"
}
},
"description": "The representation of an address in Gusto."
}
LocationsCreateCompanyLocationRequest
{
"type": "object",
"required": [
"phone_number",
"street_1",
"city",
"state",
"zip"
],
"properties": {
"zip": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"country": {
"type": "string",
"default": "USA"
},
"street_1": {
"type": "string"
},
"street_2": {
"type": "string",
"nullable": true
},
"phone_number": {
"type": "string",
"pattern": "[0-9]{10}"
},
"filing_address": {
"type": "boolean",
"description": "Specify if this location is the company's filing address."
},
"mailing_address": {
"type": "boolean",
"description": "Specify if this location is the company's mailing address."
}
},
"description": ""
}
LocationsCreateCompanyLocationRequest1
{
"type": "object",
"required": [
"phone_number",
"street_1",
"street_2",
"city",
"state",
"zip",
"country"
],
"properties": {
"zip": {
"type": "string",
"minLength": 1
},
"city": {
"type": "string",
"minLength": 1
},
"state": {
"type": "string",
"minLength": 1
},
"country": {
"type": "string",
"minLength": 1
},
"street_1": {
"type": "string",
"minLength": 1
},
"street_2": {
"type": "string",
"nullable": true,
"minLength": 1
},
"phone_number": {
"type": "string",
"minLength": 1
}
},
"description": ""
}
LocationsGetCompanyLocationsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Location"
}
}
LocationsGetMinimumWagesResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Minimum-Wage"
}
}
LocationsUpdateLocationRequest
{
"allOf": [
{
"$ref": "#/components/schemas/Versionable-Required"
},
{
"type": "object",
"properties": {
"zip": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"country": {
"type": "string"
},
"street_1": {
"type": "string"
},
"street_2": {
"type": "string",
"nullable": true
},
"phone_number": {
"type": "string",
"pattern": "[0-9]{10}"
},
"filing_address": {
"type": "boolean",
"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."
},
"mailing_address": {
"type": "boolean",
"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."
}
},
"description": ""
}
]
}
Minimum-Wage
{
"type": "object",
"required": [
"uuid",
"wage",
"wage_type",
"effective_date",
"authority"
],
"properties": {
"uuid": {
"type": "string",
"description": "unique identifier of a minimum wage"
},
"wage": {
"type": "string",
"format": "float",
"description": "The wage rate for a minimum wage record. Represented as a float, e.g. \"15.0\"."
},
"notes": {
"type": "string",
"description": "Description of parties the minimum wage applies to."
},
"authority": {
"type": "string",
"description": "The governing authority that created the minimum wage, e.g. \"City\", \"State\", or \"Federal\"."
},
"wage_type": {
"type": "string",
"description": "The type of wage the minimum wage applies to, e.g. \"Regular\", \"Regular-Industry-Specific\"."
},
"effective_date": {
"type": "string",
"format": "date",
"description": "The date the minimum wage rule is effective on."
}
},
"x-examples": {
"example": {
"uuid": "70c523ff-c71e-4474-9c83-a4ea51bd54a8",
"wage": "13.0",
"notes": "Employers with 6 or more employees",
"authority": "State",
"wage_type": "Regular",
"effective_date": "2022-01-01"
}
},
"description": "Representation of a Minimum Wage"
}
Notification
{
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "Unique identifier of a notification."
},
"title": {
"type": "string",
"description": "The title of the notification. This highlights the actionable component of the notification."
},
"due_at": {
"type": "string",
"description": "Timestamp of when the notification is due. If the notification has no due date, this field will be null."
},
"message": {
"type": "string",
"description": "The message of the notification. This provides additional context for the user and recommends a specific action to resolve the notification."
},
"category": {
"type": "string",
"description": "The notification's category."
},
"resources": {
"type": "array",
"items": {
"type": "object",
"required": [
"entity_type",
"entity_uuid"
],
"properties": {
"entity_type": {
"type": "string",
"description": "The type of entity being described, could be “Contractor”, “Employee”, “BankAccount”, “Payroll”, “ContractorPayment”, “RecoveryCase”, or “Signatory”"
},
"entity_uuid": {
"type": "string",
"description": "Unique identifier of the entity"
},
"reference_type": {
"type": "string",
"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."
},
"reference_uuid": {
"type": "string",
"description": "Optional. Unique identifier of the reference."
}
}
},
"description": "An array of entities relevant to the notification"
},
"actionable": {
"type": "boolean",
"description": "Indicates whether a notification requires action or not. If false, the notification provides critical information only."
},
"company_uuid": {
"type": "string",
"description": "Unique identifier of the company to which the notification belongs."
},
"published_at": {
"type": "string",
"description": "Timestamp of when the notification was published."
}
},
"x-examples": {
"example": {
"uuid": "7b1d0df1-6403-4a06-8768-c1dd7d24d27a",
"title": "Action required: Additional information needed to process payroll",
"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",
"company_uuid": "88f7cca1-dcad-4d20-84db-7fb80303d69f"
}
},
"description": "Representation of a notification"
}
Off-Cycle-Reason-Type
{
"enum": [
"Benefit reversal",
"Bonus",
"Correction",
"Dismissed employee",
"Hired employee",
"Wage correction",
"Tax reconciliation",
"Reversal",
"Disability insurance distribution",
"Transition from old pay schedule"
],
"type": "string",
"nullable": true,
"readOnly": true,
"description": "The off-cycle reason. Only included for off-cycle payrolls."
}
Paid-Holidays
{
"type": "object",
"properties": {
"schema": {
"type": "object",
"properties": {
"end_date": {
"type": "string",
"description": "the holiday's end date (YYYY-MM-DD)"
},
"start_date": {
"type": "string",
"description": "the holiday's start date (YYYY-MM-DD)"
},
"holiday_key": {
"type": "string",
"description": "the holiday's identifier"
},
"holiday_name": {
"type": "string",
"description": "the holiday's official name"
}
}
}
},
"description": "Representation of a company's paid holidays as descibed by their Holiday Pay Policy"
}
Paid-Time-Off
{
"type": "object",
"x-tags": [
"Payrolls"
],
"properties": {
"name": {
"enum": [
"Vacation Hours",
"Sick Hours",
"Holiday Hours"
],
"type": "string",
"readOnly": true,
"description": "The name of the paid time off type."
},
"policy_name": {
"type": "string",
"readOnly": true,
"description": "The name of the time off policy."
},
"policy_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the time off policy."
},
"accrual_rate": {
"type": "string",
"readOnly": true,
"description": "The number of accrual units accrued per accrual period."
},
"accrual_unit": {
"type": "string",
"example": "Hour",
"readOnly": true,
"description": "The unit the PTO type is accrued in."
},
"accrual_method": {
"type": "string",
"example": "unlimited",
"readOnly": true,
"description": "The accrual method of the time off policy"
},
"accrual_period": {
"type": "string",
"example": "Year",
"readOnly": true,
"description": "The frequency at which the PTO type is accrued."
},
"accrual_balance": {
"type": "string",
"readOnly": true,
"description": "The number of accrual units accrued."
},
"paid_at_termination": {
"type": "boolean",
"readOnly": true,
"description": "Whether the accrual balance is paid to the employee upon termination."
},
"maximum_accrual_balance": {
"type": "string",
"nullable": true,
"readOnly": true,
"description": "The maximum number of accrual units allowed. A null value signifies no maximum."
}
},
"x-examples": {
"Example": {
"name": "Sick Hours",
"policy_name": "Sick Policy",
"policy_uuid": "8dc8f324-3c03-4b42-8602-02476fa21c1b",
"accrual_rate": "208.0",
"accrual_unit": "Hour",
"accrual_period": "Year",
"accrual_balance": "64.0",
"paid_at_termination": false,
"maximum_accrual_balance": "240.0"
}
},
"description": "The representation of paid time off in Gusto."
}
Pay-Period
{
"type": "object",
"x-tags": [
"Payrolls"
],
"properties": {
"payroll": {
"type": "object",
"readOnly": true,
"properties": {
"processed": {
"type": "boolean",
"readOnly": true,
"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."
},
"check_date": {
"type": "string",
"readOnly": true,
"description": "The date on which employees will be paid for the payroll if the payroll is submitted on time."
},
"payroll_type": {
"enum": [
"regular",
"transition"
],
"type": "string",
"readOnly": true,
"description": "Whether it is regular pay period or transition pay period."
},
"payroll_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the payroll for this pay period."
},
"payroll_deadline": {
"type": "string",
"format": "date-time",
"readOnly": true,
"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."
}
},
"description": "Information about the payroll for the pay period."
},
"end_date": {
"type": "string",
"minLength": 1,
"description": "The end date, inclusive, of the pay period."
},
"start_date": {
"type": "string",
"readOnly": true,
"description": "The start date, inclusive, of the pay period."
},
"pay_schedule_uuid": {
"type": "string",
"readOnly": true,
"description": "A unique identifier of the pay schedule to which the pay period belongs."
}
},
"description": "The representation of a pay period."
}
Pay-Schedule
{
"type": "object",
"title": "Pay Schedule",
"x-tags": [
"Pay Schedules"
],
"properties": {
"name": {
"type": "string",
"nullable": true,
"readOnly": true,
"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."
},
"uuid": {
"type": "string",
"readOnly": true,
"description": "The unique identifier of the pay schedule in Gusto."
},
"day_1": {
"type": "integer",
"nullable": true,
"readOnly": true,
"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."
},
"day_2": {
"type": "integer",
"nullable": true,
"readOnly": true,
"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."
},
"active": {
"type": "boolean",
"readOnly": true,
"description": "Whether this pay schedule is associated with any employees. A pay schedule is inactive when it's unassigned."
},
"frequency": {
"enum": [
"Every week",
"Every other week",
"Twice per month",
"Monthly",
"Quarterly",
"Annually"
],
"type": "string",
"readOnly": true,
"description": "The frequency that employees on this pay schedule are paid with Gusto."
},
"auto_pilot": {
"type": "boolean",
"description": "With Autopilot® enabled, payroll will run automatically one day before your payroll deadlines."
},
"custom_name": {
"type": "string",
"readOnly": true,
"description": "A custom name for a pay schedule, defaults to the pay frequency description."
},
"anchor_pay_date": {
"type": "string",
"readOnly": true,
"description": "The first date that employees on this pay schedule are paid with Gusto."
},
"anchor_end_of_pay_period": {
"type": "string",
"readOnly": true,
"description": "The last date of the first pay period. This can be the same date as the anchor pay date."
}
},
"x-examples": {
"Example": {
"name": "Engineering",
"uuid": "f2a69c38-e2f9-4e31-b5c5-4754fc60a052",
"day_1": 15,
"day_2": 31,
"frequency": "Twice per month",
"auto_pilot": false,
"custom_name": "A new monthly pay schedule",
"anchor_pay_date": "2020-05-15",
"anchor_end_of_pay_period": "2020-05-08"
}
},
"description": "The representation of a pay schedule."
}
Pay-Schedule-Assignment
{
"type": "object",
"x-tags": [
"Pay Schedules"
],
"properties": {
"type": {
"enum": [
"single",
"hourly_salaried",
"by_employee",
"by_department"
],
"type": "string",
"readOnly": true,
"description": "The pay schedule assignment type."
},
"employees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Pay-Schedule-Assignment-Employee"
},
"nullable": true,
"readOnly": true,
"description": "List of employees and their pay schedules."
},
"departments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Pay-Schedule-Assignment-Department"
},
"nullable": true,
"readOnly": true,
"description": "List of departments and their pay schedules."
},
"hourly_pay_schedule_uuid": {
"type": "string",
"nullable": true,
"readOnly": true,
"description": "Pay schedule for hourly employees."
},
"default_pay_schedule_uuid": {
"type": "string",
"nullable": true,
"readOnly": true,
"description": "Default pay schedule for employees."
},
"salaried_pay_schedule_uuid": {
"type": "string",
"nullable": true,
"readOnly": true,
"description": "Pay schedule for salaried employees."
}
},
"x-examples": {
"example-1": {
"type": "by_employee",
"employees": {
"employee_uuid": "f0238368-f2cf-43e2-9a07-b0265f2cec69",
"pay_schedule_uuid": "c277ac52-9871-4a96-a1e6-0c449684602a"
}
}
},
"description": "The representation of a pay schedule assignment."
}
Pay-Schedule-Assignment-Body
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"enum": [
"single",
"hourly_salaried",
"by_employee",
"by_department"
],
"type": "string",
"description": "The pay schedule assignment type."
},
"employees": {
"type": "array",
"items": {
"type": "object",
"properties": {
"employee_uuid": {
"type": "string",
"description": "Employee UUID"
},
"pay_schedule_uuid": {
"type": "string",
"description": "Pay schedule UUID"
}
}
},
"description": "List of employees and their pay schedules."
},
"departments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"department_uuid": {
"type": "string",
"description": "Department UUID"
},
"pay_schedule_uuid": {
"type": "string",
"description": "Pay schedule UUID"
}
}
},
"description": "List of departments and their pay schedules."
},
"hourly_pay_schedule_uuid": {
"type": "string",
"description": "Pay schedule for hourly employees."
},
"default_pay_schedule_uuid": {
"type": "string",
"description": "Default pay schedule for employees."
},
"salaried_pay_schedule_uuid": {
"type": "string",
"description": "Pay schedule for salaried employees."
}
}
}
Pay-Schedule-Assignment-Department
{
"type": "object",
"x-tags": [
"Pay Schedules"
],
"properties": {
"department_uuid": {
"type": "string",
"description": "The UUID of the department."
},
"pay_schedule_uuid": {
"type": "string",
"description": "The department's pay schedule UUID."
}
},
"x-examples": {
"example-1": {
"department_uuid": "43b39ada-dc49-4879-9594-fe95f67ae434",
"pay_schedule_uuid": "3f029a58-155d-4c30-8361-cc266b2c1f11"
}
}
}
Pay-Schedule-Assignment-Employee
{
"type": "object",
"x-tags": [
"Pay Schedules"
],
"properties": {
"employee_uuid": {
"type": "string",
"description": "The UUID of the employee."
},
"pay_schedule_uuid": {
"type": "string",
"description": "The employee's pay schedule UUID."
}
},
"x-examples": {
"example-1": {
"employee_uuid": "43b39ada-dc49-4879-9594-fe95f67ae434",
"pay_schedule_uuid": "3f029a58-155d-4c30-8361-cc266b2c1f11"
}
}
}
Pay-Schedule-Assignment-Employee-Change
{
"type": "object",
"x-tags": [
"Pay Schedules"
],
"properties": {
"last_name": {
"type": "string",
"readOnly": true,
"description": "The employee's last name."
},
"first_name": {
"type": "string",
"readOnly": true,
"description": "The employee's first name."
},
"employee_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the employee."
},
"pay_frequency": {
"type": "string",
"readOnly": true,
"description": "New pay schedule frequency and name."
},
"first_pay_period": {
"$ref": "#/components/schemas/Pay-Schedule-Assignment-Pay-Period"
},
"transition_pay_period": {
"$ref": "#/components/schemas/Pay-Schedule-Assignment-Transition-Pay-Period"
}
},
"x-examples": {
"example-1": {
"last_name": "Parker",
"first_name": "Penny",
"employee_uuid": "43b39ada-dc49-4879-9594-fe95f67ae434",
"pay_frequency": "Twice per month — Salaried pay schedule",
"first_pay_period": {
"end_date": "2023-08-01",
"check_date": "2023-08-02",
"start_date": "2023-07-01",
"pay_schedule_uuid": "3f029a58-155d-4c30-8361-cc266b2c1f11"
},
"transition_pay_period": {
"end_date": "2023-06-30",
"start_date": "2023-06-20"
}
}
}
}
Pay-Schedule-Assignment-Pay-Period
{
"type": "object",
"x-tags": [
"Pay Schedules"
],
"properties": {
"end_date": {
"type": "string",
"description": "Pay period end date."
},
"check_date": {
"type": "string",
"description": "Pay period check date."
},
"start_date": {
"type": "string",
"description": "Pay period start date."
},
"pay_schedule_uuid": {
"type": "string",
"description": "The pay schedule UUID."
}
},
"x-examples": {
"example-1": {
"end_date": "2023-08-01",
"check_date": "2023-08-02",
"start_date": "2023-07-01",
"pay_schedule_uuid": "3f029a58-155d-4c30-8361-cc266b2c1f11"
}
},
"description": "Pay schedule assignment first pay period information."
}
Pay-Schedule-Assignment-Preview
{
"type": "object",
"x-tags": [
"Pay Schedules"
],
"properties": {
"type": {
"enum": [
"single",
"hourly_salaried",
"by_employee",
"by_department"
],
"type": "string",
"readOnly": true,
"description": "The pay schedule assignment type."
},
"employee_changes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Pay-Schedule-Assignment-Employee-Change"
},
"description": "A list of pay schedule changes including pay period and transition pay period."
}
},
"x-examples": {
"example-1": {
"type": "hourly_salaried",
"employee_changes": {
"last_name": "Parker",
"first_name": "Penny",
"employee_uuid": "43b39ada-dc49-4879-9594-fe95f67ae434",
"pay_frequency": "Twice per month — Salaried pay schedule",
"first_pay_period": {
"end_date": "2023-08-01",
"check_date": "2023-08-02",
"start_date": "2023-07-01",
"pay_schedule_uuid": "3f029a58-155d-4c30-8361-cc266b2c1f11"
},
"transition_pay_period": {
"end_date": "2023-06-30",
"start_date": "2023-06-20"
}
}
}
},
"description": "The representation of a pay schedule assignment preview."
}
Pay-Schedule-Assignment-Transition-Pay-Period
{
"type": "object",
"x-tags": [
"Pay Schedules"
],
"properties": {
"end_date": {
"type": "string",
"description": "Pay period end date."
},
"start_date": {
"type": "string",
"description": "Pay period start date."
}
},
"x-examples": {
"example-1": {
"end_date": "2023-08-01",
"start_date": "2023-07-01"
}
},
"description": "Pay schedule assignment transition pay period information."
}
PaySchedulesCreateNewRequest
{
"type": "object",
"required": [
"frequency",
"anchor_pay_date",
"anchor_end_of_pay_period"
],
"properties": {
"day_1": {
"type": "integer",
"nullable": true,
"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."
},
"day_2": {
"type": "integer",
"nullable": true,
"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."
},
"frequency": {
"enum": [
"Every week",
"Every other week",
"Twice per month",
"Monthly"
],
"type": "string",
"description": "The frequency that employees on this pay schedule are paid with Gusto."
},
"custom_name": {
"type": "string",
"description": "A custom pay schedule name, defaults to the pay frequency description."
},
"anchor_pay_date": {
"type": "string",
"example": "2020-05-15",
"description": "The first date that employees on this pay schedule are paid with Gusto."
},
"anchor_end_of_pay_period": {
"type": "string",
"example": "2020-05-08",
"description": "The last date of the first pay period. This can be the same date as the anchor pay date."
}
},
"description": ""
}
PaySchedulesGetPayPeriodsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Pay-Period"
}
}
PaySchedulesGetUnprocessedTerminationPayPeriodsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Unprocessed-Termination-Pay-Period"
}
}
PaySchedulesListForCompanyResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Pay-Schedule"
}
}
PaySchedulesPreviewPayScheduleDatesResponse
{
"type": "object",
"properties": {
"holidays": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of dates for bank closures"
},
"pay_periods": {
"type": "array",
"items": {
"type": "object",
"properties": {
"end_date": {
"type": "string",
"description": "The last day of the pay period"
},
"check_date": {
"type": "string",
"description": "The payment date, \"Check date\", for the pay period"
},
"start_date": {
"type": "string",
"description": "The first day of the pay period"
},
"run_payroll_by": {
"type": "string",
"description": "The deadline to run payroll for direct deposit on the check date"
}
}
},
"description": "A list of pay periods for the previewed pay schedule"
}
},
"description": "Pay schedule preview"
}
PaySchedulesUpdatePayScheduleRequest
{
"type": "object",
"required": [
"version"
],
"properties": {
"day_1": {
"type": "integer",
"nullable": true,
"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."
},
"day_2": {
"type": "integer",
"nullable": true,
"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."
},
"version": {
"type": "string",
"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."
},
"frequency": {
"enum": [
"Every week",
"Every other week",
"Twice per month",
"Monthly"
],
"type": "string",
"description": "The frequency that employees on this pay schedule are paid with Gusto."
},
"auto_pilot": {
"type": "boolean",
"description": "With Autopilot® enabled, payroll will run automatically one day before your payroll deadlines."
},
"custom_name": {
"type": "string",
"description": "A custom pay schedule name."
},
"anchor_pay_date": {
"type": "string",
"example": "2020-05-15",
"description": "The first date that employees on this pay schedule are paid with Gusto."
},
"anchor_end_of_pay_period": {
"type": "string",
"example": "2020-05-08",
"description": "The last date of the first pay period. This can be the same date as the anchor pay date."
}
},
"description": ""
}
Payment-Configs
{
"type": "object",
"title": "Payment-Configs",
"x-tags": [
"Payment Configs"
],
"properties": {
"company_uuid": {
"type": "string",
"readOnly": true,
"description": "Company uuid"
},
"partner_uuid": {
"type": "string",
"readOnly": true,
"description": "Partner uuid"
},
"payment_speed": {
"type": "string",
"readOnly": true,
"description": "Payment speed for 1-day, 2-day, 4-day"
},
"fast_payment_limit": {
"type": "string",
"readOnly": true,
"description": "Payment limit for 1-day or 2-day payroll"
}
},
"x-examples": {
"Example": {
"company_uuid": "423dd616-6dbc-4724-938a-403f6217a933",
"partner_uuid": "556f05d0-48e0-4c47-bce5-db9aea923043",
"payment_speed": "2-day",
"fast_payment_limit": "5000"
}
}
}
Payment-Method-Bank-Account
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The bank account name"
},
"uuid": {
"type": "string",
"description": "The bank account ID"
},
"priority": {
"type": "integer",
"description": "The order of priority for each payment split, with priority 1 being the first bank account paid. Priority must be unique and sequential."
},
"split_amount": {
"type": "integer",
"nullable": true,
"description": "The cents amount allocated for each payment split"
},
"hidden_account_number": {
"type": "string",
"description": "Masked bank account number"
}
},
"description": "Representation of a bank account item"
}
PaymentConfigsUpdateCompanyPaymentConfigsRequest
{
"type": "object",
"required": [
"fast_payment_limit",
"payment_speed"
],
"properties": {
"payment_speed": {
"enum": [
"1-day",
"2-day",
"4-day"
],
"type": "string",
"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."
},
"fast_payment_limit": {
"type": "string",
"description": "Fast payment limit. This limit is an aggregate of all fast payrolls amount."
}
},
"description": ""
}
Payroll
{
"type": "object",
"x-tags": [
"Payrolls"
],
"properties": {
"totals": {
"$ref": "#/components/schemas/Payroll-Totals-Type"
},
"external": {
"$ref": "#/components/schemas/Payroll-External-Type"
},
"off_cycle": {
"$ref": "#/components/schemas/Payroll-Off-Cycle-Type"
},
"processed": {
"$ref": "#/components/schemas/Payroll-Processed-Type"
},
"check_date": {
"$ref": "#/components/schemas/Payroll-Check-Date-Type"
},
"created_at": {
"$ref": "#/components/schemas/Created-At-Type"
},
"pay_period": {
"$ref": "#/components/schemas/Payroll-Pay-Period-Type"
},
"company_uuid": {
"$ref": "#/components/schemas/Payroll-Company-Uuid-Type"
},
"payroll_uuid": {
"$ref": "#/components/schemas/Payroll-Payroll-Uuid-Type"
},
"calculated_at": {
"$ref": "#/components/schemas/Payroll-Calculated-At-Type"
},
"company_taxes": {
"$ref": "#/components/schemas/Payroll-Company-Taxes-Type"
},
"processed_date": {
"$ref": "#/components/schemas/Payroll-Processed-Date-Type"
},
"off_cycle_reason": {
"$ref": "#/components/schemas/Off-Cycle-Reason-Type"
},
"payroll_deadline": {
"$ref": "#/components/schemas/Payroll-Deadline-Type"
},
"payroll_status_meta": {
"$ref": "#/components/schemas/Payroll-Payroll-Status-Meta-Type"
},
"payment_speed_changed": {
"$ref": "#/components/schemas/Payroll-Payment-Speed-Changed-Type"
},
"employee_compensations": {
"$ref": "#/components/schemas/Payroll-Employee-Compensations-Type"
},
"fixed_withholding_rate": {
"$ref": "#/components/schemas/Payroll-Fixed-Withholding-Rate-Type"
},
"withholding_pay_period": {
"$ref": "#/components/schemas/Payroll-Withholding-Pay-Period-Type"
},
"skip_regular_deductions": {
"$ref": "#/components/schemas/Payroll-Skip-Regular-Deductions-Type"
},
"final_termination_payroll": {
"$ref": "#/components/schemas/Payroll-Final-Termination-Payroll-Type"
}
},
"description": ""
}
Payroll-Blocker
{
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "The unique identifier of the reason"
},
"message": {
"type": "string",
"description": "User-friendly message describing the payroll blocker."
}
}
}
Payroll-Blockers-Error
{
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Human readable description of the payroll blocker"
},
"category": {
"type": "string",
"description": "The string \"payroll_blocker\""
},
"metadata": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "A categorization of the payroll blocker, e.g. \"geocode_error\""
}
}
},
"error_key": {
"type": "string",
"description": "The string \"base\""
}
}
}
}
},
"description": "Payroll Blockers Error\n\nFor detailed information, see the [Payroll Blockers guide](https://docs.gusto.com/embedded-payroll/docs/payroll-blockers)"
}
Payroll-Calculated-At-Type
{
"type": "string",
"readOnly": true,
"description": "A timestamp of the last valid payroll calculation. Null is there isn't a valid calculation."
}
Payroll-Check
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Current status of the Generated Document"
},
"payroll_uuid": {
"type": "string",
"description": "A unique identifier of the payroll."
},
"request_uuid": {
"type": "string",
"description": "A unique identifier of the Generated Document request"
},
"printing_format": {
"type": "string",
"description": "The format the checks will be printed."
},
"starting_check_number": {
"type": "string",
"description": "The starting check number for the checks being printed."
}
},
"x-examples": {
"example-1": {
"status": "pending",
"payroll_uuid": "a83d0bd8-7d20-43b9-834c-6d514ef6cb20",
"request_uuid": "p83d0ca8-7d41-42a9-834y-7d218ef6cb20",
"printing_format": "top",
"starting_check_number": "10"
}
}
}
Payroll-Check-Date-Type
{
"type": "string",
"readOnly": true,
"description": "The date on which employees will be paid for the payroll."
}
Payroll-Company-Taxes-Type
{
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The tax name"
},
"amount": {
"type": "string",
"description": "The amount of this tax for the payroll"
},
"employer": {
"type": "boolean",
"description": "Whether this tax is an employer or employee tax"
}
}
},
"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.",
"uniqueItems": false
}
Payroll-Company-Uuid-Type
{
"type": "string",
"readOnly": true,
"description": "The UUID of the company for the payroll."
}
Payroll-Deadline-Type
{
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "A timestamp that is the deadline for the payroll to be run in order for employees to be paid on time."
}
Payroll-Employee-Compensations-Type
{
"type": "array",
"items": {
"type": "object",
"properties": {
"memo": {
"type": "string",
"nullable": true,
"readOnly": true,
"description": "Custom text that will be printed as a personal note to the employee on a paystub."
},
"taxes": {
"type": "array",
"items": {
"type": "object",
"readOnly": true,
"required": [
"name",
"employer",
"amount"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"amount": {
"type": "string",
"minLength": 1
},
"employer": {
"type": "boolean"
}
}
},
"readOnly": true,
"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.",
"uniqueItems": false
},
"net_pay": {
"type": "string",
"nullable": true,
"readOnly": true,
"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."
},
"version": {
"type": "string",
"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."
},
"benefits": {
"type": "array",
"items": {
"type": "object",
"readOnly": true,
"properties": {
"name": {
"type": "string",
"readOnly": true
},
"imputed": {
"type": "boolean"
},
"employee_deduction": {
"type": "string",
"readOnly": true
},
"company_contribution": {
"type": "string",
"readOnly": true
}
}
},
"readOnly": true,
"description": "An array of employee benefits for the pay period. Benefits are only included for processed payroll when the include parameter is present.",
"uniqueItems": false
},
"excluded": {
"type": "boolean",
"readOnly": true,
"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."
},
"gross_pay": {
"type": "string",
"nullable": true,
"readOnly": true,
"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."
},
"deductions": {
"type": "array",
"items": {
"type": "object",
"readOnly": true,
"properties": {
"name": {
"type": "string",
"readOnly": true
},
"amount": {
"type": "string",
"readOnly": true
}
}
},
"readOnly": true,
"description": "An array of employee deductions for the pay period. Deductions are only included for processed payroll when the include parameter is present.",
"uniqueItems": false
},
"check_amount": {
"type": "string",
"nullable": true,
"readOnly": true,
"description": "The employee's check amount, equal to net_pay + reimbursements. This value is only available for processed payrolls."
},
"employee_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the employee."
},
"paid_time_off": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the PTO. This also serves as the unique, immutable identifier for the PTO."
},
"hours": {
"type": "string",
"description": "The hours of this PTO taken during the pay period."
},
"final_payout_unused_hours_input": {
"type": "string",
"description": "The outstanding hours paid upon termination. This field is only applicable for termination payrolls."
}
}
},
"description": "An array of all paid time off the employee is eligible for this pay period.",
"uniqueItems": false
},
"payment_method": {
"enum": [
"Check",
"Direct Deposit"
],
"type": "string",
"nullable": true,
"description": "The employee's compensation payment method."
},
"fixed_compensations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the compensation. This also serves as the unique, immutable identifier for this compensation."
},
"amount": {
"type": "string",
"description": "The amount of the compensation for the pay period."
},
"job_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the job for the compensation."
}
}
},
"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.",
"uniqueItems": false
},
"hourly_compensations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the compensation. This also serves as the unique, immutable identifier for this compensation."
},
"hours": {
"type": "string",
"description": "The number of hours to be compensated for this pay period."
},
"amount": {
"type": "string",
"description": "The amount of the compensation. This field is only available after the payroll is calculated and cannot be used for updating hourly compensations."
},
"job_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the job for the compensation."
},
"compensation_multiplier": {
"type": "number",
"readOnly": true,
"description": "The amount multiplied by the base rate to calculate total compensation per hour worked."
}
}
},
"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.",
"uniqueItems": false
}
}
},
"uniqueItems": false
}
Payroll-External-Type
{
"type": "boolean",
"readOnly": true,
"description": "Indicates whether the payroll is an external payroll"
}
Payroll-Final-Termination-Payroll-Type
{
"type": "boolean",
"readOnly": true,
"description": "Indicates whether the payroll is the final payroll for a terminated employee. Only included for off-cycle payrolls."
}
Payroll-Fixed-Compensation-Types-Type
{
"type": "array",
"items": {
"type": "object",
"readOnly": true,
"properties": {
"name": {
"type": "string",
"readOnly": true,
"description": "The name of an available type of fixed compensation."
}
}
}
}
Payroll-Fixed-Withholding-Rate-Type
{
"type": "boolean",
"nullable": false,
"readOnly": true,
"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."
}
Payroll-Minimal
{
"type": "object",
"x-tags": [
"Payrolls"
],
"properties": {
"totals": {
"$ref": "#/components/schemas/Payroll-Totals-Type"
},
"external": {
"$ref": "#/components/schemas/Payroll-External-Type"
},
"off_cycle": {
"$ref": "#/components/schemas/Payroll-Off-Cycle-Type"
},
"processed": {
"$ref": "#/components/schemas/Payroll-Processed-Type"
},
"check_date": {
"$ref": "#/components/schemas/Payroll-Check-Date-Type"
},
"created_at": {
"$ref": "#/components/schemas/Created-At-Type"
},
"pay_period": {
"$ref": "#/components/schemas/Payroll-Pay-Period-Type"
},
"company_uuid": {
"$ref": "#/components/schemas/Payroll-Company-Uuid-Type"
},
"payroll_uuid": {
"$ref": "#/components/schemas/Payroll-Payroll-Uuid-Type"
},
"calculated_at": {
"$ref": "#/components/schemas/Payroll-Calculated-At-Type"
},
"processed_date": {
"$ref": "#/components/schemas/Payroll-Processed-Date-Type"
},
"off_cycle_reason": {
"$ref": "#/components/schemas/Off-Cycle-Reason-Type"
},
"payroll_deadline": {
"$ref": "#/components/schemas/Payroll-Deadline-Type"
},
"payroll_status_meta": {
"$ref": "#/components/schemas/Payroll-Payroll-Status-Meta-Type"
},
"payment_speed_changed": {
"$ref": "#/components/schemas/Payroll-Payment-Speed-Changed-Type"
},
"fixed_withholding_rate": {
"$ref": "#/components/schemas/Payroll-Fixed-Withholding-Rate-Type"
},
"withholding_pay_period": {
"$ref": "#/components/schemas/Payroll-Withholding-Pay-Period-Type"
},
"skip_regular_deductions": {
"$ref": "#/components/schemas/Payroll-Skip-Regular-Deductions-Type"
},
"final_termination_payroll": {
"$ref": "#/components/schemas/Payroll-Final-Termination-Payroll-Type"
}
},
"description": ""
}
Payroll-Off-Cycle-Type
{
"type": "boolean",
"readOnly": true,
"description": "Indicates whether the payroll is an off-cycle payroll"
}
Payroll-Pay-Period-Type
{
"type": "object",
"readOnly": true,
"properties": {
"end_date": {
"type": "string",
"readOnly": true,
"description": "The start date, inclusive, of the pay period."
},
"start_date": {
"type": "string",
"readOnly": true,
"description": "The start date, inclusive, of the pay period."
},
"pay_schedule_uuid": {
"type": "string",
"nullable": true,
"readOnly": true,
"description": "The UUID of the pay schedule for the payroll."
}
}
}
Payroll-Payment-Speed-Changed-Type
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"readOnly": true,
"description": "The reason why the payroll is moved to four day."
},
"current_check_date": {
"type": "string",
"readOnly": true,
"description": "Current check date."
},
"current_debit_date": {
"type": "string",
"readOnly": true,
"description": "Current debit date."
},
"original_check_date": {
"type": "string",
"readOnly": true,
"description": "Original check date when fast ach applies."
},
"original_debit_date": {
"type": "number",
"readOnly": true,
"description": "Original debit date when fast ach applies."
}
},
"description": "Only applicable when a payroll is moved to four day processing instead of fast ach."
}
Payroll-Payroll-Status-Meta-Type
{
"type": "object",
"properties": {
"cancellable": {
"type": "boolean",
"readOnly": true,
"description": "true if the payroll may be cancelled"
},
"payroll_late": {
"type": "boolean",
"readOnly": true,
"description": "expected_check_date > initial_check_date"
},
"initial_check_date": {
"type": "string",
"readOnly": true,
"description": "The normal check date for the associated pay period"
},
"expected_check_date": {
"type": "string",
"readOnly": true,
"description": "The date an employee will be paid if the payroll is submitted now"
},
"expected_debit_time": {
"type": "string",
"readOnly": true,
"description": "The time the employer's account will be debited if the payroll is submitted now"
},
"initial_debit_cutoff_time": {
"type": "string",
"readOnly": true,
"description": "Payroll must be submitted at or before this time to avoid late payroll"
}
},
"description": "Information about the payroll's status and expected dates"
}
Payroll-Payroll-Uuid-Type
{
"type": "string",
"readOnly": true,
"description": "The UUID of the payroll."
}
Payroll-Prepared
{
"type": "object",
"x-tags": [
"Payrolls"
],
"properties": {
"external": {
"$ref": "#/components/schemas/Payroll-External-Type"
},
"off_cycle": {
"$ref": "#/components/schemas/Payroll-Off-Cycle-Type"
},
"processed": {
"$ref": "#/components/schemas/Payroll-Processed-Type"
},
"check_date": {
"$ref": "#/components/schemas/Payroll-Check-Date-Type"
},
"created_at": {
"$ref": "#/components/schemas/Created-At-Type"
},
"pay_period": {
"$ref": "#/components/schemas/Payroll-Pay-Period-Type"
},
"company_uuid": {
"$ref": "#/components/schemas/Payroll-Company-Uuid-Type"
},
"payroll_uuid": {
"$ref": "#/components/schemas/Payroll-Payroll-Uuid-Type"
},
"calculated_at": {
"$ref": "#/components/schemas/Payroll-Calculated-At-Type"
},
"processed_date": {
"$ref": "#/components/schemas/Payroll-Processed-Date-Type"
},
"off_cycle_reason": {
"$ref": "#/components/schemas/Off-Cycle-Reason-Type"
},
"payroll_deadline": {
"$ref": "#/components/schemas/Payroll-Deadline-Type"
},
"payroll_status_meta": {
"$ref": "#/components/schemas/Payroll-Payroll-Status-Meta-Type"
},
"payment_speed_changed": {
"$ref": "#/components/schemas/Payroll-Payment-Speed-Changed-Type"
},
"employee_compensations": {
"$ref": "#/components/schemas/Payroll-Employee-Compensations-Type"
},
"fixed_withholding_rate": {
"$ref": "#/components/schemas/Payroll-Fixed-Withholding-Rate-Type"
},
"withholding_pay_period": {
"$ref": "#/components/schemas/Payroll-Withholding-Pay-Period-Type"
},
"skip_regular_deductions": {
"$ref": "#/components/schemas/Payroll-Skip-Regular-Deductions-Type"
},
"fixed_compensation_types": {
"$ref": "#/components/schemas/Payroll-Fixed-Compensation-Types-Type"
},
"final_termination_payroll": {
"$ref": "#/components/schemas/Payroll-Final-Termination-Payroll-Type"
}
},
"description": ""
}
Payroll-Processed-Date-Type
{
"type": "string",
"readOnly": true,
"description": "The date at which the payroll was processed. Null if the payroll isn't processed yet."
}
Payroll-Processed-Type
{
"type": "boolean",
"readOnly": true,
"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."
}
Payroll-Receipt
{
"type": "object",
"properties": {
"taxes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The amount paid for this tax."
},
"amount": {
"type": "string",
"description": "The total amount paid by both employer and employee for this tax."
}
}
},
"description": "An array of totaled employer and employee taxes for the pay period."
},
"totals": {
"type": "object",
"properties": {
"tax_debit": {
"type": "string",
"description": "The total tax debit for the payroll."
},
"company_debit": {
"type": "string",
"description": "The total company debit for the payroll."
},
"net_pay_debit": {
"type": "string",
"description": "The total company net pay for the payroll."
},
"child_support_debit": {
"type": "string",
"description": "The total child support debit for the payroll."
},
"reimbursement_debit": {
"type": "string",
"description": "The total reimbursements for the payroll."
}
},
"description": "The subtotals for the payroll."
},
"license": {
"type": "string",
"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.\""
},
"licensee": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Always the fixed string \"San Francisco\""
},
"name": {
"type": "string",
"description": "Always the fixed string \"Gusto, Zenpayroll Inc.\""
},
"state": {
"type": "string",
"description": "Always the fixed string \"CA\""
},
"address": {
"type": "string",
"description": "Always the fixed string \"525 20th St\""
},
"postal_code": {
"type": "string",
"description": "Always the fixed string \"94107\""
},
"phone_number": {
"type": "string",
"description": "Always the fixed string \"4157778888\""
}
},
"description": "The licensed payroll processor"
},
"debit_date": {
"type": "string",
"description": "The debit or funding date for the payroll"
},
"license_uri": {
"type": "string",
"description": "URL for the license information for the licensed payroll processor. Always the fixed string \"https://gusto.com/about/licenses\""
},
"company_uuid": {
"type": "string",
"description": "A unique identifier of the company for the payroll."
},
"payroll_uuid": {
"type": "string",
"description": "A unique identifier of the payroll receipt."
},
"name_of_sender": {
"type": "string",
"description": "The name of the company by whom the payroll was paid"
},
"right_to_refund": {
"type": "string",
"description": ""
},
"recipient_notice": {
"type": "string",
"description": "Always the fixed string \"Payroll recipients include the employees listed below plus the tax agencies for the taxes listed below.\""
},
"name_of_recipient": {
"type": "string",
"description": "Always the fixed string \"Payroll Recipients\""
},
"liability_of_licensee": {
"type": "string",
"description": ""
},
"employee_compensations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"net_pay": {
"type": "string",
"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."
},
"total_tax": {
"type": "string",
"description": "The total of employer and employee taxes for the pay period."
},
"employee_uuid": {
"type": "string",
"description": "The UUID of the employee."
},
"payment_method": {
"type": "string",
"description": "The employee's compensation payment method.\\n\\n`Check` `Direct Deposit`"
},
"employee_last_name": {
"type": "string",
"description": "The last name of the employee."
},
"total_garnishments": {
"type": "string",
"description": "The total garnishments for the pay period."
},
"employee_first_name": {
"type": "string",
"description": "The first name of the employee."
},
"total_reimbursement": {
"type": "string",
"description": "The total reimbursement for the pay period."
},
"child_support_garnishment": {
"type": "string",
"description": "The total child support garnishment for the pay period."
}
}
},
"description": "An array of employee compensations and withholdings for this payroll"
}
},
"x-examples": {
"example-1": {
"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"
}
],
"totals": {
"tax": "182.13",
"company_debit": "1080.47",
"net_pay_debit": "748.34",
"child_support_debit": "100.0",
"reimbursement_debit": "50.0"
},
"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.",
"licensee": {
"city": "San Francisco",
"name": "Gusto, Zenpayroll Inc.",
"state": "CA",
"address": "525 20th St",
"postal_code": "94107",
"phone_number": "4157778888"
},
"debit_date": "2022-06-02",
"license_uri": "https://gusto.com/about/licenses",
"company_uuid": "c827aa0d-3928-4d5a-ab1f-400641a7d2b8",
"payroll_uuid": "afccb970-357e-4013-81f5-85dafc74f9b6",
"name_of_sender": "Torp and Sons and Sons",
"right_to_refund": "https://gusto.com/about/licenses",
"recipient_notice": "Payroll recipients include the employees listed below plus the tax agencies for the taxes listed below.",
"name_of_recipient": "Payroll Recipients",
"liability_of_licensee": "https://gusto.com/about/licenses",
"employee_compensations": [
{
"net_pay": "748.34",
"total_tax": "182.13",
"employee_uuid": "f83d0bd8-7e20-43b9-834c-6d514ef6cb47",
"payment_method": "Direct Deposit",
"employee_last_name": "Hamill",
"total_garnishments": "0.0",
"employee_first_name": "Patricia",
"total_reimbursement": "50.0",
"child_support_garnishment": "100.0"
}
]
}
}
}
Payroll-Reversal
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "A reason provided by the admin who created the reversal."
},
"category": {
"type": "string",
"items": {
"type": "integer"
},
"description": "Category chosen by the admin who requested the reversal."
},
"approved_at": {
"type": "string",
"nullable": true,
"description": "Timestamp of when the reversal was approved."
},
"reversal_payroll_uuid": {
"type": "string",
"description": "The UUID of the payroll where the reversal was applied."
},
"reversed_payroll_uuid": {
"type": "string",
"description": "The UUID for the payroll run being reversed."
},
"reversed_employee_uuids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of affected employee UUIDs."
}
}
}
Payroll-Skip-Regular-Deductions-Type
{
"type": "boolean",
"nullable": false,
"readOnly": true,
"description": "Block regular deductions and contributions for this payroll. Only included for off-cycle payrolls."
}
Payroll-Totals-Type
{
"type": "object",
"readOnly": true,
"properties": {
"net_pay": {
"type": "string",
"readOnly": true,
"description": "The net pay amount for the payroll."
},
"benefits": {
"type": "string",
"readOnly": true,
"description": "The total amount of company contributed benefits for the payroll."
},
"gross_pay": {
"type": "string",
"readOnly": true,
"description": "The gross pay amount for the payroll."
},
"tax_debit": {
"type": "string",
"readOnly": true,
"description": "The total tax debit for the payroll."
},
"owners_draw": {
"type": "string",
"readOnly": true,
"description": "The total owner's draw for the payroll."
},
"check_amount": {
"type": "string",
"readOnly": true,
"description": "The total check amount for the payroll."
},
"company_debit": {
"type": "string",
"readOnly": true,
"description": "The total company debit for the payroll."
},
"net_pay_debit": {
"type": "string",
"minLength": 1,
"description": "The total company net pay for the payroll."
},
"employee_taxes": {
"type": "string",
"readOnly": true,
"description": "The total amount of employee paid taxes for the payroll."
},
"employer_taxes": {
"type": "string",
"readOnly": true,
"description": "The total amount of employer paid taxes for the payroll."
},
"reimbursements": {
"type": "string",
"readOnly": true,
"description": "The total reimbursements for the payroll."
},
"employee_bonuses": {
"type": "string",
"readOnly": true,
"description": "The total employee bonuses amount for the payroll."
},
"other_deductions": {
"type": "string",
"description": "The total amount of deductions for the payroll."
},
"employee_cash_tips": {
"type": "string",
"readOnly": true,
"description": "The total employee cash tips amount for the payroll."
},
"additional_earnings": {
"type": "string",
"readOnly": true,
"description": "The total additional earnings amount for the payroll."
},
"child_support_debit": {
"type": "string",
"readOnly": true,
"description": "The total child support debit for the payroll."
},
"reimbursement_debit": {
"type": "string",
"readOnly": true,
"description": "The total reimbursement debit for the payroll."
},
"employee_commissions": {
"type": "string",
"readOnly": true,
"description": "The total employee commissions amount for the payroll."
},
"deferred_payroll_taxes": {
"type": "string",
"readOnly": true,
"description": "The total amount of payroll taxes deferred for the payroll, such as allowed by the CARES act."
},
"employee_paycheck_tips": {
"type": "string",
"readOnly": true,
"description": "The total employee paycheck tips amount for the payroll."
},
"employee_benefits_deductions": {
"type": "string",
"readOnly": true,
"description": "The total amount of employee deducted benefits for the payroll."
}
},
"description": "The subtotals for the payroll."
}
Payroll-Withholding-Pay-Period-Type
{
"enum": [
"Every week",
"Every other week",
"Twice per month",
"Monthly",
"Quarterly",
"Semiannually",
"Annually"
],
"type": "string",
"nullable": false,
"readOnly": true,
"description": "The payment schedule tax rate the payroll is based on. Only included for off-cycle payrolls."
}
PayrollsCalculateGrossUp422Response
{
"oneOf": [
{
"$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
},
{
"$ref": "#/components/schemas/Payroll-Blockers-Error"
}
]
}
PayrollsCalculateGrossUpRequest
{
"type": "object",
"required": [
"employee_uuid",
"net_pay"
],
"properties": {
"net_pay": {
"type": "string",
"description": "Employee net earnings"
},
"employee_uuid": {
"type": "string",
"description": "Employee UUID"
}
},
"description": ""
}
PayrollsCalculateGrossUpResponse
{
"oneOf": [
{
"$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
},
{
"$ref": "#/components/schemas/Payroll-Blockers-Error"
}
]
}
PayrollsCreateOffCyclePayrollRequest
{
"type": "object",
"required": [
"off_cycle",
"off_cycle_reason",
"start_date",
"end_date"
],
"properties": {
"end_date": {
"type": "string",
"description": "Pay period end date."
},
"off_cycle": {
"type": "boolean",
"description": "Whether it is an off cycle payroll."
},
"check_date": {
"type": "string",
"description": "Payment date."
},
"start_date": {
"type": "string",
"description": "Pay period start date."
},
"employee_uuids": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of employee uuids to include on the payroll."
},
"off_cycle_reason": {
"enum": [
"Bonus",
"Correction",
"Dismissed employee",
"Transition from old pay schedule"
],
"type": "string",
"description": "An off cycle payroll reason. Select one from the following list."
},
"pay_schedule_uuid": {
"type": "string",
"description": "A pay schedule is required for Transition from old pay schedule payroll to identify the matching transition pay period."
},
"fixed_withholding_rate": {
"type": "boolean",
"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."
},
"withholding_pay_period": {
"enum": [
"Every week",
"Every other week",
"Twice per month",
"Monthly",
"Quarterly",
"Semiannually",
"Annually"
],
"type": "string",
"description": "The payment schedule tax rate the payroll is based on"
},
"skip_regular_deductions": {
"type": "boolean",
"description": "Block regular deductions and contributions for this payroll."
}
}
}
PayrollsGeneratePrintableChecksRequest
{
"type": "object",
"required": [
"printing_format"
],
"properties": {
"printing_format": {
"type": "string",
"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"
},
"starting_check_number": {
"type": "integer",
"description": "The starting check number for the checks being generated"
}
}
}
PayrollsGetAllPayrollBlockersResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Payroll-Blocker"
}
}
PayrollsGetCompanyPayrollsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Payroll-Minimal"
}
}
PayrollsGetEmployeePayStubsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Employee-Pay-Stub"
}
}
PayrollsSkipPayrollRequest
{
"type": "object",
"required": [
"payroll_type"
],
"properties": {
"end_date": {
"type": "string",
"description": "Pay period end date"
},
"start_date": {
"type": "string",
"description": "Pay period start date"
},
"payroll_type": {
"enum": [
"Regular",
"Hired employee",
"Dismissed employee",
"Transition from old pay schedule"
],
"type": "string",
"description": "Payroll type"
},
"employee_uuids": {
"type": "array",
"items": {
"type": "string"
},
"description": "An array of employees. This field is only applicable to new hire payroll and termination payroll"
},
"pay_schedule_uuid": {
"type": "string",
"description": "The UUID of the pay schedule"
}
},
"description": ""
}
PayrollsSkipPayrollResponse
{
"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"
}
]
}
PayrollsUpdatePayrollByIdRequest
{
"type": "object",
"required": [
"employee_compensations"
],
"properties": {
"employee_compensations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"memo": {
"type": "string",
"description": "Custom text that will be printed as a personal note to the employee on a paystub."
},
"version": {
"type": "string",
"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."
},
"excluded": {
"type": "boolean",
"description": "This employee will be excluded from payroll calculation and will not be paid for the payroll."
},
"employee_uuid": {
"type": "string",
"description": "The UUID of the employee."
},
"paid_time_off": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"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."
},
"hours": {
"type": "string",
"description": "The hours of this PTO taken during the pay period."
},
"policy_uuid": {
"type": "string",
"description": "The uuid of the PTO policy. Must pass in name or policy_uuid but not both."
},
"final_payout_unused_hours_input": {
"type": "string",
"description": "The outstanding hours paid upon termination. This field is only applicable for termination payrolls."
}
}
},
"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."
},
"payment_method": {
"enum": [
"Direct Deposit",
"Check"
],
"type": "string",
"description": "The employee's compensation payment method. Invalid values will be ignored."
},
"fixed_compensations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the compensation. This also serves as the unique, immutable identifier for this compensation."
},
"amount": {
"type": "string",
"description": "The amount of the compensation for the pay period."
},
"job_uuid": {
"type": "integer",
"description": "The UUID of the job for the compensation."
}
},
"description": "An array of fixed compensations for the employee. Fixed compensations include tips, bonuses, and one time reimbursements."
}
},
"hourly_compensations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the compensation. This also serves as the unique, immutable identifier for this compensation."
},
"hours": {
"type": "string",
"description": "The number of hours to be compensated for this pay period."
},
"job_uuid": {
"type": "integer",
"description": "The UUIDs of the job for the compensation."
}
},
"description": "An array of hourly compensations for the employee. Hourly compensations include regular, overtime, and double overtime hours."
}
}
},
"description": ""
}
}
}
}
Recovery-Case
{
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "Unique identifier of an recovery case"
},
"status": {
"enum": [
"open",
"redebit_initiated",
"recovered",
"lost"
],
"type": "string",
"description": "Status of the recovery case"
},
"check_date": {
"type": "string",
"description": "Check date for the associated payroll or contractor payments"
},
"company_uuid": {
"type": "string",
"description": "Unique identifier of the company to which the recovery case belongs"
},
"payroll_uuid": {
"type": "string",
"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."
},
"latest_error_code": {
"type": "string",
"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."
},
"amount_outstanding": {
"type": "string",
"description": "Amount outstanding for the recovery case"
},
"event_total_amount": {
"type": "string",
"description": "Total amount to be debited from the payroll or contractor payments"
},
"original_debit_date": {
"type": "string",
"description": "Date when funds were originally debited from the company's bank account"
},
"contractor_payment_uuids": {
"type": "array",
"items": {
"type": "string"
},
"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."
}
},
"x-examples": {
"example": {
"uuid": "e83d273e-4ae9-4b61-9c71-4030c2f73093",
"status": "open",
"check_date": "2023-10-13",
"company_uuid": "c5e3e3e9-732f-4762-849e-20b5cec9036f",
"payroll_uuid": "210f2034-fb4a-4059-b109-6c3b5efe499d",
"latest_error_code": "R01",
"amount_outstanding": 10499.43,
"event_total_amount": 5912.07,
"original_debit_date": "2023-10-11",
"contractor_payment_uuids": null
}
},
"description": "Representation of a recovery case"
}
RecoveryCasesListForCompanyResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Recovery-Case"
}
}
Rehire
{
"type": "object",
"properties": {
"active": {
"type": "boolean",
"readOnly": true,
"description": "Whether the employee's rehire has gone into effect."
},
"version": {
"type": "string",
"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."
},
"employee_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the employee."
},
"effective_date": {
"type": "string",
"description": "The day when the employee returns to work."
},
"employment_status": {
"enum": [
"part_time",
"full_time",
"part_time_eligible",
"variable",
"seasonal",
"not_set"
],
"type": "string",
"description": "The employee's employment status. Supplying an invalid option will set the employment_status to *not_set*."
},
"work_location_uuid": {
"type": "string",
"description": "The uuid of the employee's work location."
},
"file_new_hire_report": {
"type": "boolean",
"description": "The boolean flag indicating whether Gusto will file a new hire report for the employee."
},
"two_percent_shareholder": {
"type": "boolean",
"description": "Whether the employee is a two percent shareholder of the company. This field only applies to companies with an S-Corp entity type."
}
},
"x-examples": {
"example-1": {
"active": false,
"version": "2e930d43acbdb241f8f14a2d531fa417",
"employee_uuid": "8c290660-b6c9-4ad7-9f6e-ea146aaf79e8",
"effective_date": "2024-06-30",
"employment_status": "seasonal",
"work_location_uuid": "8cb87e2e-5b30-4c13-a4f4-bfffcbed1188",
"file_new_hire_report": false,
"two_percent_shareholder": false
}
}
}
Rehire-Body
{
"type": "object",
"required": [
"effective_date",
"file_new_hire_report",
"work_location_uuid"
],
"properties": {
"effective_date": {
"type": "string",
"description": "The day when the employee returns to work."
},
"employment_status": {
"enum": [
"part_time",
"full_time",
"part_time_eligible",
"variable",
"seasonal",
"not_set"
],
"type": "string",
"description": "The employee's employment status. Supplying an invalid option will set the employment_status to *not_set*."
},
"work_location_uuid": {
"type": "string",
"description": "The uuid of the employee's work location."
},
"file_new_hire_report": {
"type": "boolean",
"description": "The boolean flag indicating whether Gusto will file a new hire report for the employee."
},
"two_percent_shareholder": {
"type": "boolean",
"description": "Whether the employee is a two percent shareholder of the company. This field only applies to companies with an S-Corp entity type."
}
}
}
SignatoriesCreateInviteRequest
{
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"type": "string"
},
"title": {
"type": "string"
},
"last_name": {
"type": "string"
},
"first_name": {
"type": "string"
}
}
}
SignatoriesCreateSignatoryWithCompleteInformationRequest
{
"type": "object",
"required": [
"ssn",
"first_name",
"last_name",
"email",
"title",
"birthday",
"home_address",
"phone"
],
"properties": {
"ssn": {
"type": "string"
},
"email": {
"type": "string"
},
"phone": {
"type": "string"
},
"title": {
"type": "string"
},
"birthday": {
"type": "string"
},
"last_name": {
"type": "string"
},
"first_name": {
"type": "string"
},
"home_address": {
"type": "object",
"required": [
"street_1",
"city",
"state",
"zip"
],
"properties": {
"zip": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"street_1": {
"type": "string"
},
"street_2": {
"type": "string"
}
},
"description": "The signatory's home address"
},
"middle_initial": {
"type": "string"
}
},
"description": ""
}
SignatoriesGetCompanySignatoriesResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Signatory"
}
}
SignatoriesUpdateRequest
{
"type": "object",
"properties": {
"ssn": {
"type": "string"
},
"phone": {
"type": "string"
},
"title": {
"type": "string"
},
"version": {
"type": "string",
"description": "The current version of the object. See the versioning guide for information on how to use this field."
},
"birthday": {
"type": "string"
},
"last_name": {
"type": "string"
},
"first_name": {
"type": "string"
},
"home_address": {
"type": "object",
"properties": {
"zip": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"street_1": {
"type": "string"
},
"street_2": {
"type": "string"
}
}
},
"middle_initial": {
"type": "string"
}
}
}
Signatory
{
"type": "object",
"title": "Signatory",
"x-tags": [
"Signatories"
],
"properties": {
"uuid": {
"type": "string"
},
"email": {
"type": "string"
},
"phone": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"has_ssn": {
"type": "boolean",
"description": "Indicates whether the signatory has an SSN in Gusto."
},
"version": {
"type": "string",
"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."
},
"birthday": {
"type": "string",
"nullable": true
},
"is_admin": {
"type": "boolean",
"description": "Whether or not the signatory is also the payroll admin of the company."
},
"last_name": {
"type": "string",
"nullable": true
},
"first_name": {
"type": "string",
"nullable": true
},
"home_address": {
"type": "object",
"nullable": true,
"properties": {
"zip": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"country": {
"type": "string",
"default": "USA"
},
"street_1": {
"type": "string"
},
"street_2": {
"type": "string"
}
}
},
"identity_verification_status": {
"enum": [
"Pass",
"Fail",
"Skipped"
],
"type": "string",
"nullable": true,
"description": "| | |\n|---|---|\n|__Status__| __Description__ |\n| Pass | Signatory can sign all forms |\n| Fail | Signatory cannot sign forms |\n| Skipped | Signatory cannot sign Form 8655 until the form is manually uploaded as wet-signed |\n| null | Identity verification process has not been completed |"
}
},
"description": "The representation of a company's signatory"
}
State
{
"type": "string",
"title": "State",
"description": "One of the two-letter state abbreviations for the fifty United States and the District of Columbia (DC)"
}
Supported-Benefit
{
"type": "object",
"properties": {
"name": {
"type": "string",
"readOnly": true,
"description": "The name of the benefit."
},
"pretax": {
"type": "boolean",
"readOnly": true,
"description": "Whether the benefit is deducted before tax calculations, thus reducing one’s taxable income"
},
"imputed": {
"type": "boolean",
"readOnly": true,
"description": "Whether the benefit is considered imputed income."
},
"posttax": {
"type": "boolean",
"readOnly": true,
"description": "Whether the benefit is deducted after tax calculations."
},
"category": {
"type": "string",
"readOnly": true,
"description": "Category where the benefit belongs to."
},
"healthcare": {
"type": "boolean",
"readOnly": true,
"description": "Whether the benefit is healthcare related."
},
"retirement": {
"type": "boolean",
"readOnly": true,
"description": "Whether the benefit is associated with retirement planning."
},
"description": {
"type": "string",
"readOnly": true,
"description": "The description of the benefit."
},
"benefit_type": {
"type": "number",
"readOnly": true,
"description": "The benefit type in Gusto."
},
"yearly_limit": {
"type": "boolean",
"readOnly": true,
"description": "Whether the benefit has a government mandated yearly limit."
}
},
"x-examples": {
"Example": {
"name": "Medical Insurance",
"pretax": true,
"imputed": false,
"posttax": false,
"category": "Health",
"healthcare": true,
"retirement": false,
"description": "Deductions and contributions for Medical Insurance",
"benefit_type": 1,
"yearly_limit": false
}
},
"description": ""
}
Tax-Liabilities-Selections
{
"type": "object",
"title": "",
"x-tags": [
"External Payrolls"
],
"properties": {
"tax_id": {
"type": "integer",
"readOnly": true,
"description": "The ID of the tax."
},
"tax_name": {
"type": "string",
"readOnly": true,
"description": "The name of the tax."
},
"possible_liabilities": {
"type": "object",
"readOnly": true,
"properties": {
"liability_amount": {
"type": "string",
"readOnly": true,
"description": "Liability amount."
},
"payroll_check_date": {
"type": "string",
"readOnly": true,
"description": "The external payroll check date."
},
"external_payroll_uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the external payroll."
}
},
"description": "Possible tax liabilities selections."
},
"last_unpaid_external_payroll_uuid": {
"type": "string",
"nullable": true,
"readOnly": true,
"description": "The UUID of last unpaid external payroll."
}
},
"x-examples": {
"Example": {
"tax_id": 1,
"tax_name": "Federal Income Tax",
"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"
}
],
"last_unpaid_external_payroll_uuid": null
}
},
"description": "The representation of tax liabilities selections."
}
Tax-Requirement
{
"type": "object",
"properties": {
"key": {
"$ref": "#/components/schemas/Tax-Requirement-Key"
},
"label": {
"type": "string",
"description": "A customer facing description of the requirement"
},
"value": {
"type": "string",
"description": "The \"answer\""
},
"metadata": {
"$ref": "#/components/schemas/Tax-Requirement-Metadata"
},
"description": {
"type": "string",
"description": "A more detailed customer facing description of the requirement"
},
"applicable_if": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"$ref": "#/components/schemas/Tax-Requirement-Key"
},
"value": {
"oneOf": [
{
"type": "boolean"
},
{
"type": "string"
},
{
"type": "number"
}
],
"description": "The required value of the requirement identified by `key`"
}
}
},
"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."
}
},
"x-examples": {
"ga-withholding-requirement-example": {
"key": "71653ec0-00b5-4c66-a58b-22ecf21704c5",
"label": "Withholding Number",
"value": "1233214-AB",
"metadata": {
"mask": "#######-^^",
"type": "account_number",
"prefix": null
},
"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 <a target='_blank' data-bypass href='https://gtc.dor.ga.gov/_/#1'>register the business online</a>. The last two characters of your ID must be upper case letters.",
"applicable_if": []
}
}
}
Tax-Requirement-Effective-From
{
"type": "string",
"title": "Tax-Requirement-Effective-From",
"nullable": true,
"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."
}
Tax-Requirement-Key
{
"type": "string",
"title": "Tax-Requirement-Key",
"description": "An identifier for an individual requirement. Uniqueness is guaranteed within a requirement set."
}
Tax-Requirement-Metadata
{
"type": "object",
"required": [
"type"
],
"properties": {
"mask": {
"type": "string",
"description": "[for `account_number`] A pattern describing the format of the account number\n\nThe 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:\n- `#`: a digit (`\\d`)\n- `@`: a upper or lower case letter (`[a-zA-Z]`)\n- `^`: an uppercase letter (`[A-Z]`)\n- `%`: a digit or uppercase letter (`[0-9A-Z]`)\n- any other character represents the literal character\n\nExamples:\n- mask: `WHT-######` represents `WHT-` followed by 5 digits, e.g. `WHT-33421`\n- mask: `%####-^^` supports values of `75544-AB` and `Z7654-HK`\n"
},
"type": {
"enum": [
"text",
"currency",
"radio",
"select",
"percent",
"account_number",
"tax_rate",
"workers_compensation_rate"
],
"type": "string",
"readOnly": true,
"description": "Describes the type of requirement - each type may have additional metadata properties to describe possible values, formats, etc.\n\n- `text`: free-text input, no additional requirements\n- `currency`: a value representing a dollar amount, e.g. `374.55` representing `$374.55`\n- `radio`: choose one of options provided, see `options`\n- `select`: choose one of options provided, see `options`\n- `percent`: A decimal value representing a percentage, e.g. `0.034` representing `3.4%`\n- `account_number`: An account number for a tax agency, more information provided by `mask` and `prefix`\n- `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\n- `workers_compensation_rate`: A decimal value representing a percentage, see `risk_class_code`, `risk_class_description`, and `rate_type`\n"
},
"prefix": {
"type": "string",
"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`."
},
"options": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"value"
],
"properties": {
"label": {
"type": "string",
"description": "A customer facing label for the answer"
},
"value": {
"type": "string",
"description": "The actual value to be submitted"
},
"short_label": {
"type": "string",
"description": "A less verbose label that may sometimes be available"
}
}
},
"description": "[for `select` or `radio`] An array of objects describing the possible values."
},
"rate_type": {
"enum": [
"percent",
"currency_per_hour"
],
"type": "string",
"description": "[for `workers_compensation_rate`] The type of rate being collected. Either:\n - `percent`: A percentage formatted as a decimal, e.g. `0.01` for 1%\n - `currency_per_hour`: A dollar amount per hour, e.g. `3.24` for $3.24/hr\n"
},
"validation": {
"type": "object",
"required": [
"type"
],
"properties": {
"max": {
"type": "string",
"description": "[for `min_max`] The inclusive upper bound of the tax rate"
},
"min": {
"type": "string",
"description": "[for `min_max`] The inclusive lower bound of the tax rate"
},
"type": {
"enum": [
"one_of",
"min_max"
],
"type": "string",
"description": "Describes the type of tax_rate validation rule"
},
"rates": {
"type": "array",
"items": {
"type": "string"
},
"description": "[for `one_of`] The possible, unformatted tax rates for selection.\n- e.g. [\"0.0\", \"0.001\"] representing 0% and 0.1%\n"
}
},
"description": "[for `tax_rate`] Describes the validation required for the tax rate"
},
"risk_class_code": {
"type": "string",
"description": "[for `workers_compensation_rate`] The industry risk class code for the rate being requested"
},
"risk_class_description": {
"type": "string",
"description": "[for `workers_compensation_rate`] A description of the industry risk class for the rate being requested"
}
},
"x-examples": {
"radio-example": {
"metadata": {
"type": "radio",
"options": [
{
"label": "No, we cannot reimburse the state—we have to pay SUI taxes quarterly",
"value": false,
"short_label": "Not Reimbursable"
},
{
"label": "Yes, we can reimburse the state if an employee collects SUI benefits—we don’t have to pay SUI taxes quarterly",
"value": true,
"short_label": "Reimbursable"
}
]
}
},
"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": {
"max": "0.081",
"min": "0.0004",
"type": "min_max"
}
}
},
"account_number-example": {
"metadata": {
"mask": "######-##",
"type": "account_number",
"prefix": null
}
}
},
"description": ""
}
Tax-Requirement-Set
{
"type": "object",
"properties": {
"key": {
"$ref": "#/components/schemas/Tax-Requirement-Set-Key"
},
"label": {
"type": "string",
"description": "Customer facing label for the requirement set, e.g. \"Registrations\""
},
"state": {
"$ref": "#/components/schemas/State"
},
"requirements": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Tax-Requirement"
}
},
"effective_from": {
"$ref": "#/components/schemas/Tax-Requirement-Effective-From"
}
},
"x-examples": {
"tax-requirements-set-ga-registrations-example": {
"key": "registrations",
"label": "Registrations",
"state": "GA",
"requirements": [
{
"key": "71653ec0-00b5-4c66-a58b-22ecf21704c5",
"label": "Withholding Number",
"value": "1233214-AB",
"metadata": {
"mask": "#######-^^",
"type": "account_number",
"prefix": null
},
"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 <a target='_blank' data-bypass href='https://gtc.dor.ga.gov/_/#1'>register the business online</a>. The last two characters of your ID must be upper case letters.",
"applicable_if": []
},
{
"key": "6c0911ab-5860-412e-bdef-6437cd881df5",
"label": "DOL Account Number",
"value": "474747-88",
"metadata": {
"mask": "######-##",
"type": "account_number",
"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 <a target='_blank' data-bypass href='https://support.gusto.com/hc/en-us/articles/210139038#registerdol'>follow the instructions here</a> to register your business with the Georgia Dept. of Labor.",
"applicable_if": []
}
],
"effective_from": null
}
},
"description": ""
}
Tax-Requirement-Set-Key
{
"type": "string",
"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."
}
Tax-Requirements-State
{
"type": "object",
"title": "Tax-Requirements-State",
"properties": {
"state": {
"$ref": "#/components/schemas/State"
},
"company_uuid": {
"type": "string"
},
"requirement_sets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Tax-Requirement-Set"
}
}
},
"x-examples": {
"tax-requirements-state-ga-example": {
"state": "GA",
"company_uuid": "6c14eac3-0da2-474d-bda1-786b3602d381",
"requirement_sets": [
{
"key": "registrations",
"label": "Registrations",
"state": "GA",
"requirements": [
{
"key": "71653ec0-00b5-4c66-a58b-22ecf21704c5",
"label": "Withholding Number",
"value": "1233214-AB",
"metadata": {
"mask": "#######-^^",
"type": "account_number",
"prefix": null
},
"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 <a target='_blank' data-bypass href='https://gtc.dor.ga.gov/_/#1'>register the business online</a>. The last two characters of your ID must be upper case letters.",
"applicable_if": []
},
{
"key": "6c0911ab-5860-412e-bdef-6437cd881df5",
"label": "DOL Account Number",
"value": "474747-88",
"metadata": {
"mask": "######-##",
"type": "account_number",
"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 <a target='_blank' data-bypass href='https://support.gusto.com/hc/en-us/articles/210139038#registerdol'>follow the instructions here</a> to register your business with the Georgia Dept. of Labor.",
"applicable_if": []
}
],
"effective_from": null
},
{
"key": "taxrates",
"label": "Tax Rates",
"state": "GA",
"requirements": [
{
"key": "suireimbursable",
"label": "SUI Reimburser",
"value": false,
"metadata": {
"type": "radio",
"options": [
{
"label": "No, we cannot reimburse the state—we have to pay SUI taxes quarterly",
"value": false,
"short_label": "Not Reimbursable"
},
{
"label": "Yes, we can reimburse the state if an employee collects SUI benefits—we don’t have to pay SUI taxes quarterly",
"value": true,
"short_label": "Reimbursable"
}
]
},
"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.",
"applicable_if": []
},
{
"key": "e0ac2284-8d30-4100-ae23-f85f9574868b",
"label": "Total Tax Rate",
"value": "0.05",
"metadata": {
"type": "tax_rate",
"validation": {
"max": "0.081",
"min": "0.0004",
"type": "min_max"
}
},
"description": "Haven't received your assigned rate yet? <a target='_blank' data-bypass href='https://support.gusto.com/article/106622236100000/State-unemployment-insurance-(SUI)-tax'>Find the new employer rate</a> and enter it here.",
"applicable_if": [
{
"key": "suireimbursable",
"value": false
}
]
}
],
"effective_from": "2022-01-01"
},
{
"key": "depositschedules",
"label": "Deposit Schedules",
"state": "GA",
"requirements": [
{
"key": "6ddfcbeb-94d3-4003-bfc2-8c6e1ca9f70c",
"label": "Deposit Schedule",
"value": "Monthly",
"metadata": {
"type": "select",
"options": [
{
"label": "Semiweekly",
"value": "Semi-weekly"
},
{
"label": "Monthly",
"value": "Monthly"
},
{
"label": "Quarterly",
"value": "Quarterly"
}
]
},
"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 <a target='_blank' data-bypass href='https://gtc.dor.ga.gov/_/#2'>register the business with the Georgia Dept. of Revenue</a>.",
"applicable_if": []
}
],
"effective_from": "2022-01-01"
},
{
"key": "depositschedules",
"label": "Deposit Schedules",
"state": "GA",
"requirements": [
{
"key": "6ddfcbeb-94d3-4003-bfc2-8c6e1ca9f70c",
"label": "Deposit Schedule",
"value": "Monthly",
"metadata": {
"type": "select",
"options": [
{
"label": "Semiweekly",
"value": "Semi-weekly"
},
{
"label": "Monthly",
"value": "Monthly"
},
{
"label": "Quarterly",
"value": "Quarterly"
}
]
},
"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 <a target='_blank' data-bypass href='https://gtc.dor.ga.gov/_/#2'>register the business with the Georgia Dept. of Revenue</a>.",
"applicable_if": []
}
],
"effective_from": "2022-07-01"
}
]
}
},
"description": ""
}
TaxRequirementsGetStatesResponse
{
"type": "array",
"items": {
"type": "object",
"properties": {
"state": {
"$ref": "#/components/schemas/State"
},
"setup_complete": {
"type": "boolean",
"description": "If all requirements for the state have been satisfied such that the company can complete\nonboarding, the company is `setup_complete` in the state. A company must be `setup_complete` in\nall relevant states to complete the `state_setup` company onboarding step."
}
}
},
"x-examples": {
"example-1": [
{
"state": "CA",
"setup_complete": true
},
{
"state": "GA",
"setup_complete": false
}
]
}
}
TaxRequirementsUpdateStateTaxesRequest
{
"type": "object",
"properties": {
"requirement_sets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"$ref": "#/components/schemas/Tax-Requirement-Set-Key"
},
"state": {
"$ref": "#/components/schemas/State"
},
"requirements": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"$ref": "#/components/schemas/Tax-Requirement-Key"
},
"value": {
"type": "string",
"nullable": true
}
}
}
},
"effective_from": {
"$ref": "#/components/schemas/Tax-Requirement-Effective-From"
}
}
}
}
},
"x-examples": {
"example-1": {
"requirement_sets": [
{
"key": "registrations",
"state": "GA",
"requirements": [
{
"key": "71653ec0-00b5-4c66-a58b-22ecf21704c5",
"value": "1233214-AB"
},
{
"key": "6c0911ab-5860-412e-bdef-6437cd881df5",
"value": "474747-22"
}
],
"effective_from": null
},
{
"key": "taxrates",
"state": "GA",
"requirements": [
{
"key": "e0ac2284-8d30-4100-ae23-f85f9574868b",
"value": "0.05"
}
],
"effective_from": "2022-01-01"
},
{
"key": "depositschedules",
"state": "GA",
"requirements": [
{
"key": "6ddfcbeb-94d3-4003-bfc2-8c6e1ca9f70c",
"value": "Semi-weekly"
}
],
"effective_from": "2022-01-01"
}
]
}
}
}
Termination
{
"type": "object",
"x-tags": [
"Terminations"
],
"properties": {
"uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the termination object."
},
"active": {
"type": "boolean",
"readOnly": true,
"description": "Whether the employee's termination has gone into effect."
},
"version": {
"type": "string",
"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."
},
"cancelable": {
"type": "boolean",
"readOnly": true,
"description": "Whether the employee's termination is cancelable. Cancelable is true if `run_termination_payroll` is false and `effective_date` is in the future."
},
"employee_uuid": {
"type": "integer",
"readOnly": true,
"description": "The UUID of the employee to which this termination is attached."
},
"effective_date": {
"type": "string",
"readOnly": false,
"description": "The employee's last day of work."
},
"run_termination_payroll": {
"type": "boolean",
"readOnly": false,
"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."
}
},
"x-examples": {
"example-1": {
"uuid": "da441196-43a9-4d23-ad5d-f37ce6bb99c0",
"active": true,
"version": "d487dd0b55dfcacdd920ccbdaeafa351",
"cancelable": true,
"employee_uuid": "da441196-43a9-4d23-ad5d-f37ce6bb99c0",
"effective_date": "2020-03-10",
"run_termination_payroll": false
}
},
"description": "The representation of a termination in Gusto."
}
Time-Off-Activity
{
"type": "object",
"properties": {
"balance": {
"type": "string",
"format": "float",
"description": "The time off balance at the time of the activity"
},
"event_type": {
"type": "string",
"description": "The type of the time off event/activity"
},
"policy_name": {
"type": "string",
"description": "The name of the time off policy for this activity"
},
"policy_uuid": {
"type": "string",
"description": "unique identifier of a time off policy"
},
"time_off_type": {
"enum": [
"vacation",
"sick"
],
"type": "string",
"description": "Type of the time off activity"
},
"balance_change": {
"type": "string",
"format": "float",
"description": "The amount the time off balance changed as a result of the activity"
},
"effective_time": {
"type": "string",
"description": "The datetime of the time off activity"
},
"event_description": {
"type": "string",
"description": "A description for the time off event/activity"
}
},
"x-examples": {
"example": {
"balance": "0.0",
"event_type": "TimeOffEvent::AddToPolicy",
"policy_name": "Paid Time Off",
"policy_uuid": "a7838f74-4c29-4b70-9bfb-02a4e3e60709",
"time_off_type": "vacation",
"balance_change": "0.0",
"effective_time": "2022-09-27T13:43:03.000-07:00",
"event_description": "Added to policy: Vacation Per Hour Worked"
}
},
"description": "Representation of a Time Off Activity"
}
Time-Off-Policy
{
"type": "object",
"required": [
"uuid",
"company_uuid",
"name",
"policy_type",
"accrual_method",
"is_active",
"employees"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the time off policy"
},
"uuid": {
"type": "string",
"description": "Unique identifier of a time off policy"
},
"version": {
"type": "string",
"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."
},
"complete": {
"type": "boolean",
"description": "boolean representing if a policy has completed configuration"
},
"employees": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uuid": {
"type": "string"
}
}
},
"description": "List of employee UUIDs under a time off policy"
},
"is_active": {
"type": "boolean",
"description": "boolean representing if a policy is active or not"
},
"max_hours": {
"type": "string",
"format": "float",
"description": "The max number of hours an employee can accrue"
},
"policy_type": {
"enum": [
"vacation",
"sick"
],
"type": "string",
"description": "Type of the time off policy"
},
"accrual_rate": {
"type": "string",
"format": "float",
"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\"."
},
"company_uuid": {
"type": "string",
"description": "Unique identifier for the company owning the time off policy"
},
"accrual_method": {
"type": "string",
"description": "Policy time off accrual method"
},
"accrual_rate_unit": {
"type": "string",
"format": "float",
"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\"."
},
"carryover_limit_hours": {
"type": "string",
"format": "float",
"description": "The max number of hours and employee can carryover from one year to the next"
},
"paid_out_on_termination": {
"type": "boolean",
"description": "Boolean representing if an employees accrued time off hours will be paid out on termination"
},
"max_accrual_hours_per_year": {
"type": "string",
"format": "float",
"description": "The max number of hours and employee can accrue in a year"
},
"accrual_waiting_period_days": {
"type": "integer",
"description": "Number of days before an employee on the policy will begin accruing time off hours"
}
},
"x-examples": {
"example": {
"name": "test policy",
"uuid": "3f746cd0-dd08-408f-b712-8180c7c621e9",
"employees": [
{
"uuid": "c61d1895-5cf8-4217-88c8-20d7c3132a04"
}
],
"is_active": true,
"policy_type": "vacation",
"company_uuid": "de83cff2-8e7a-448e-a28c-14258a9971c3",
"accrual_method": "unlimited"
}
},
"description": "Representation of a Time Off Policy"
}
Time-Off-Request
{
"type": "object",
"title": "Time-Off-Request",
"x-tags": [
"Time Off Requests"
],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "The ID of the time off request."
},
"days": {
"type": "object",
"readOnly": true,
"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."
},
"status": {
"enum": [
"pending",
"approved",
"denied"
],
"type": "string",
"readOnly": true,
"description": "The status of the time off request."
},
"approver": {
"type": "object",
"nullable": true,
"readOnly": true,
"properties": {
"id": {
"type": "string",
"readOnly": true,
"description": "The ID of the employee who approved the time off request."
},
"full_name": {
"type": "string",
"readOnly": true,
"description": "The full name of the employee who approved the time off request."
}
},
"description": "This value will be null if the request has not been approved."
},
"employee": {
"type": "object",
"readOnly": true,
"properties": {
"id": {
"type": "string",
"readOnly": true,
"description": "The ID of the employee the time off request is for."
},
"full_name": {
"type": "string",
"readOnly": true,
"description": "The full name of the employee the time off request is for."
}
},
"description": ""
},
"initiator": {
"type": "object",
"nullable": true,
"readOnly": true,
"properties": {
"id": {
"type": "string",
"readOnly": true,
"description": "The ID of the employee who initiated the time off request."
},
"full_name": {
"type": "string",
"readOnly": true,
"description": "The full name of the employee who initiated the time off request."
}
},
"description": ""
},
"request_type": {
"enum": [
"vacation",
"sick"
],
"type": "string",
"readOnly": true,
"description": "The type of time off request."
},
"employee_note": {
"type": "string",
"readOnly": true,
"description": "A note about the time off request, from the employee to the employer."
},
"employer_note": {
"type": "string",
"readOnly": true,
"description": "A note about the time off request, from the employer to the employee."
}
},
"x-examples": {
"Example": {
"id": "1",
"days": {
"2019-06-01": "4.000",
"2019-06-02": "8.000",
"2019-06-03": "2.000"
},
"status": "approved",
"approver": {
"id": "345678",
"full_name": "Karen Gusto"
},
"employee": {
"id": "234567",
"full_name": "Jessica Gusto"
},
"initiator": {
"id": "234567",
"full_name": "Jessica Gusto"
},
"request_type": "vacation",
"employee_note": "Vacation at Disney World!",
"employer_note": "But Universal has Harry Potter World..."
}
},
"description": "The representation of a time off request. "
}
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"
}
]
}
}
}
TimeOffPoliciesCalculateAccruingTimeOffHoursRequest
{
"type": "object",
"properties": {
"pto_hours_used": {
"type": "number",
"description": "paid time off hours used in this pay period"
},
"sick_hours_used": {
"type": "number",
"description": "sick hours used in this pay period"
},
"regular_hours_worked": {
"type": "number",
"description": "regular hours worked in this pay period"
},
"overtime_hours_worked": {
"type": "number",
"description": "overtime hours worked in this pay period"
},
"double_overtime_hours_worked": {
"type": "number",
"description": "double overtime hours worked in this pay period"
}
},
"description": ""
}
TimeOffPoliciesCalculateAccruingTimeOffHoursResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Accruing-Time-Off-Hour"
}
}
TimeOffPoliciesCreatePolicyRequest
{
"type": "object",
"required": [
"name",
"policy_type",
"accrual_method"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the time off policy"
},
"max_hours": {
"type": "string",
"format": "float",
"description": "The max number of hours an employee can accrue"
},
"policy_type": {
"type": "string",
"description": "Type of the time off policy. Currently only \"vacation\" and \"sick\" are supported"
},
"accrual_rate": {
"type": "string",
"format": "float",
"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\"."
},
"accrual_method": {
"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"
],
"type": "string",
"description": "Accrual method of the time off policy"
},
"accrual_rate_unit": {
"type": "string",
"format": "float",
"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\"."
},
"carryover_limit_hours": {
"type": "string",
"format": "float",
"description": "The max number of hours and employee can carryover from one year to the next"
},
"paid_out_on_termination": {
"type": "boolean",
"description": "Boolean representing if an employees accrued time off hours will be paid out on termination"
},
"max_accrual_hours_per_year": {
"type": "string",
"format": "float",
"description": "The max number of hours and employee can accrue in a year"
},
"accrual_waiting_period_days": {
"type": "integer",
"description": "Number of days before an employee on the policy will begin accruing time off hours"
}
},
"x-examples": {
"example-1": {
"name": "test policy3",
"policy_type": "sick"
}
}
}
TimeOffPoliciesGetAllPoliciesResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Time-Off-Policy"
}
}
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"
}
]
}
}
}
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"
}
]
}
}
}
TimeOffPoliciesUpdatePolicyRequest
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the time off policy"
},
"max_hours": {
"type": "string",
"format": "float",
"description": "The max number of hours an employee can accrue"
},
"accrual_rate": {
"type": "string",
"format": "float",
"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\"."
},
"accrual_method": {
"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"
],
"type": "string",
"description": "Accrual method of the time off policy"
},
"accrual_rate_unit": {
"type": "string",
"format": "float",
"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\"."
},
"carryover_limit_hours": {
"type": "string",
"format": "float",
"description": "The max number of hours and employee can carryover from one year to the next"
},
"paid_out_on_termination": {
"type": "boolean",
"description": "Boolean representing if an employees accrued time off hours will be paid out on termination"
},
"max_accrual_hours_per_year": {
"type": "string",
"format": "float",
"description": "The max number of hours and employee can accrue in a year"
},
"accrual_waiting_period_days": {
"type": "integer",
"description": "Number of days before an employee on the policy will begin accruing time off hours"
}
},
"x-examples": {
"example-1": {
"name": "test policy3",
"accrual_rate": "120.0",
"accrual_method": "per_calendar_year"
}
}
}
Unprocessable-Entity-Error-Object
{
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Provides details about the error - generally this message can be surfaced to an end user."
},
"category": {
"type": "string",
"description": "Specifies the type of error. The category provides error groupings and can be used to build custom error handling in your integration."
},
"metadata": {
"type": "object",
"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."
},
"error_key": {
"type": "string",
"description": "Specifies where the error occurs. Typically this key identifies the attribute/parameter related to the error."
}
}
}
}
},
"description": "Unprocessable Entity\n \nThis 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.\n"
}
Unprocessed-Termination-Pay-Period
{
"type": "object",
"x-tags": [
"Employee Employments"
],
"properties": {
"end_date": {
"type": "string",
"description": "The end date of the pay period."
},
"check_date": {
"type": "string",
"readOnly": true,
"description": "The check date of the pay period."
},
"debit_date": {
"type": "string",
"description": "The debit date of the pay period."
},
"start_date": {
"type": "string",
"readOnly": true,
"description": "The start date of the pay period."
},
"employee_name": {
"type": "string",
"description": "The full name of the employee."
},
"employee_uuid": {
"type": "string",
"description": "A unique identifier of the employee."
},
"pay_schedule_uuid": {
"type": "string",
"description": "A unique identifier of the pay schedule to which the pay period belongs."
}
},
"description": "The representation of an unprocessed termination pay period."
}
Versionable
{
"type": "object",
"properties": {
"version": {
"type": "string",
"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."
}
}
}
Versionable-Required
{
"type": "object",
"required": [
"version"
],
"properties": {
"version": {
"type": "string",
"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."
}
}
}
Webhook-Subscription
{
"type": "object",
"title": "",
"x-tags": [
"Webhooks"
],
"properties": {
"url": {
"type": "string",
"readOnly": true,
"description": "The webhook subscriber URL. Updates will be POSTed to this URL."
},
"uuid": {
"type": "string",
"readOnly": true,
"description": "The UUID of the webhook subscription."
},
"status": {
"enum": [
"pending",
"verified",
"removed"
],
"type": "string",
"readOnly": true,
"description": "The status of the webhook subscription."
},
"subscription_types": {
"type": "array",
"items": {
"enum": [
"BankAccount",
"Company",
"CompanyBenefit",
"Contractor",
"ContractorPayment",
"Employee",
"EmployeeBenefit",
"EmployeeJobCompensation",
"ExternalPayroll",
"Form",
"Location",
"Notification",
"Payroll",
"PaySchedule",
"Signatory"
],
"type": "string"
},
"readOnly": false,
"description": "Receive updates for these types."
}
},
"x-examples": {
"Example": {
"url": "https://partner-app.com/subscriber",
"uuid": "c5fdae57-5483-4529-9aae-f0edceed92d4",
"status": "verified",
"subscription_types": [
"BankAccount",
"Company",
"CompanyBenefit",
"Contractor",
"ContractorPayment",
"Employee",
"EmployeeBenefit",
"EmployeeJobCompensation",
"ExternalPayroll",
"Form",
"Location",
"Notification",
"Payroll",
"PaySchedule",
"Signatory"
]
}
},
"description": "The representation of webhook subscription."
}
WebhooksCreateSubscriptionRequest
{
"type": "object",
"required": [
"url",
"subscription_types"
],
"properties": {
"url": {
"type": "string"
},
"subscription_types": {
"type": "array",
"items": {
"enum": [
"BankAccount",
"Company",
"CompanyBenefit",
"Contractor",
"ContractorPayment",
"Employee",
"EmployeeBenefit",
"EmployeeJobCompensation",
"ExternalPayroll",
"Form",
"Location",
"Notification",
"Payroll",
"PaySchedule",
"Signatory"
],
"type": "string"
}
}
},
"description": ""
}
WebhooksListSubscriptionsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Webhook-Subscription"
}
}
WebhooksUpdateSubscriptionRequest
{
"type": "object",
"required": [
"subscription_types"
],
"properties": {
"subscription_types": {
"type": "array",
"items": {
"enum": [
"BankAccount",
"Company",
"CompanyBenefit",
"Contractor",
"ContractorPayment",
"Employee",
"EmployeeBenefit",
"EmployeeJobCompensation",
"ExternalPayroll",
"Form",
"Location",
"Notification",
"Payroll",
"PaySchedule",
"Signatory"
],
"type": "string"
}
}
},
"description": ""
}
WebhooksVerifySubscriptionTokenRequest
{
"type": "object",
"required": [
"verification_token"
],
"properties": {
"verification_token": {
"type": "string",
"description": "The token POSTed to the Subscription URL."
}
},
"description": ""
}