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."
}
}
}
| Version | Endpoints | Schemas | Ingested | Status |
|---|---|---|---|---|
| 2024-03-01 | 213 | 282 | 2026-05-11 | current |
| 2024-03-01 | 213 | 282 | 2026-04-16 |