{"openapi":"3.1.0","tags":[{"name":"Introspection"},{"name":"Companies"},{"name":"Flows"},{"name":"Locations"},{"name":"Bank Accounts"},{"name":"Payment Configs"},{"name":"Pay Schedules"},{"name":"Employees"},{"name":"Employee Tax Setup"},{"name":"Employee Payment Method"},{"name":"Employee Employments"},{"name":"Employee Addresses"},{"name":"Jobs and Compensations"},{"name":"Earning Types"},{"name":"I-9 Verification"},{"name":"Information Requests"},{"name":"Contractor Payment Groups"},{"name":"Contractor Payment Method"},{"name":"Contractor Payments"},{"name":"Contractors"},{"name":"Payrolls"},{"name":"Payroll Digests"},{"name":"Payroll Cancellations"},{"name":"People Batches"},{"name":"Company Forms"},{"name":"Contractor Documents"},{"name":"Employee Forms"},{"name":"Company Benefits"},{"name":"Employee Benefits"},{"name":"Garnishments"},{"name":"Federal Tax Details"},{"name":"Industry Selection"},{"name":"Signatories"},{"name":"External Payrolls"},{"name":"Tax Requirements"},{"name":"Contractor Forms"},{"name":"Time Off Policies"},{"name":"Time Off Requests"},{"name":"Time Tracking"},{"name":"Holiday Pay Policies"},{"name":"Departments"},{"name":"Reports"},{"name":"Generated Documents"},{"name":"Notifications"},{"name":"Webhooks"},{"name":"Events"},{"name":"Invoices"},{"name":"Recovery Cases"},{"name":"Company Attachment"},{"name":"Wire In Requests"},{"name":"ACH Transactions"},{"name":"Salary Estimates"},{"name":"Reimbursements"},{"name":"Member Portal Invitations"}],"info":{"title":"Gusto API","version":"2026-06-15","termsOfService":"https://gusto.com/about/terms/developer-terms-of-service","description":"Welcome to Gusto's Embedded Payroll API documentation!","contact":{"name":"Developer Relations","email":"developer@gusto.com"},"x-release-status":"stable"},"servers":[{"url":"https://api.gusto-demo.com","description":"Demo","x-speakeasy-server-id":"demo"}],"security":[{"CompanyAccessAuth":[]}],"components":{"schemas":{"Versionable-Required":{"type":"object","properties":{"version":{"type":"string","example":"56d00c178bc7393b2a206ed6a86afcb4","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."}},"required":["version"]},"Minimum-Wage-List":{"type":"array","x-examples":{"success_status":[{"uuid":"1b71bb5b-4811-46e9-8a8a-cf5521cbeda6","authority":"City","wage":"15.0","wage_type":"Regular","effective_date":"2017-01-01","notes":"large companies"},{"uuid":"87434623-b57d-4630-8da5-9dde599c7840","authority":"City","wage":"10.5","wage_type":"Regular","effective_date":"2017-01-01","notes":"large companies"},{"uuid":"fa055c11-bfe4-4ac3-84dd-8502cf046b20","authority":"State","wage":"10.5","wage_type":"Regular","effective_date":"2017-01-01","notes":"large companies"},{"uuid":"cdd9dfc2-6465-4693-ae60-0eecff35038c","authority":"Federal","wage":"10.5","wage_type":"Regular","effective_date":"2017-01-01","notes":"large companies"}]},"items":{"$ref":"#/components/schemas/Minimum-Wage"}},"Minimum-Wage":{"type":"object","description":"Representation of a Minimum Wage","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\"."},"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."},"authority":{"type":"string","description":"The governing authority that created the minimum wage, e.g. \"City\", \"State\", or \"Federal\"."},"notes":{"type":"string","description":"Description of parties the minimum wage applies to."}},"required":["uuid","wage","wage_type","effective_date","authority"]},"Location":{"description":"The representation of an address in Gusto.","type":"object","title":"","x-examples":{"success_status":{"created_at":"2025-06-09T13:43:49.000-07:00","updated_at":"2025-06-09T13:43:50.000-07:00","company_uuid":"10593a6a-505b-4aa6-bf31-15dcdceedbe3","version":"e1bdd845a493c74908f8e15d6114169b","uuid":"6b1351a2-de35-4499-b948-43abab274634","street_1":"300 3rd Street","street_2":"Apartment 318","city":"San Francisco","state":"CA","zip":"94107","country":"USA","active":true,"phone_number":"8009360383","filing_address":true,"mailing_address":true}},"properties":{"uuid":{"type":"string","description":"The UUID of the location object.","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."},"company_uuid":{"type":"string","description":"The UUID for the company to which the location belongs. Only included if the location belongs to a company.","readOnly":true},"phone_number":{"type":"string","readOnly":false,"description":"The phone number for the location. Required for company locations. Optional for employee locations."},"street_1":{"type":"string","readOnly":false},"street_2":{"type":["string","null"],"readOnly":false},"city":{"type":"string","readOnly":false},"state":{"type":"string","readOnly":false},"zip":{"type":"string","readOnly":false},"country":{"type":"string","readOnly":false,"default":"USA"},"mailing_address":{"type":"boolean","description":"Specifies if the location is the company's mailing address. Only included if the location belongs to a company."},"filing_address":{"description":"Specifies if the location is the company's filing address. Only included if the location belongs to a company.","type":"boolean"},"created_at":{"type":"string","description":"Datetime for when location is created"},"updated_at":{"type":"string","description":"Datetime for when location is updated"},"active":{"type":"boolean","description":"The status of the location. Inactive locations have been deleted, but may still have historical data associated with them.","readOnly":true},"inactive":{"type":"boolean","description":"The status of the location. Inactive locations have been deleted, but may still have historical data associated with them.","readOnly":true}},"required":["uuid"]},"Company-Location-Request":{"type":"object","description":"Request body for creating a company location (company address).","properties":{"street_1":{"type":"string","description":"Street address line 1.","example":"300 3rd Street"},"street_2":{"type":["string","null"],"description":"Street address line 2.","example":"Apartment 318"},"city":{"type":"string","description":"City.","example":"San Francisco"},"state":{"type":"string","description":"State code (e.g. CA). Must be a valid two-letter state code.","example":"CA"},"zip":{"type":"string","description":"ZIP code. Must be a valid US zip (e.g. 12345 or 12345-6789).","example":"94107"},"country":{"type":"string","description":"Country code. Defaults to USA.","default":"USA","example":"USA"},"phone_number":{"type":"string","description":"Phone number. Must be 10 digits.","pattern":"[0-9]{10}","example":"8009360383"},"mailing_address":{"type":"boolean","description":"Specify if this location is the company's mailing address."},"filing_address":{"type":"boolean","description":"Specify if this location is the company's filing address."}},"required":["phone_number","street_1","city","state","zip"],"x-examples":{"typical_location":{"street_1":"300 3rd Street","street_2":"Apartment 318","city":"San Francisco","state":"CA","zip":"94107","country":"USA","phone_number":"8009360383","mailing_address":false,"filing_address":false}}},"Company-Locations-List":{"type":"array","x-examples":{"success_status":[{"uuid":"04552eb9-7829-4b18-ae96-6983552948df","version":"7d9753112507b9dda4fb97910f39b06e","company_uuid":"6bf7807c-a5a0-4f4d-b2e7-3fbb4b2299fb","phone_number":"5825710808","street_1":"412 Kiera Stravenue","street_2":"Suite 391","city":"San Francisco","state":"CA","zip":"94107","country":"USA","mailing_address":false,"filing_address":false,"created_at":"2023-09-12T16:42:25.000-07:00","updated_at":"2023-09-12T16:42:25.000-07:00","active":true,"inactive":false},{"uuid":"fa94a2fd-11a8-4024-87ff-85c587d9d2b4","version":"15e6b9680e00f3122729e64e3cef3224","company_uuid":"6bf7807c-a5a0-4f4d-b2e7-3fbb4b2299fb","phone_number":"2866070827","street_1":"644 Fay Vista","street_2":"Suite 842","city":"Richmond","state":"VA","zip":"23218","country":"USA,","mailing_address":true,"filing_address":false,"created_at":"2023-09-12T16:42:25.000-07:00","updated_at":"2023-09-12T16:42:25.000-07:00","active":true,"inactive":false}]},"items":{"$ref":"#/components/schemas/Location"}},"Not-Found-Error-Object":{"description":"Not Found \n  \nThe requested resource does not exist. Make sure the provided ID/UUID is valid.","type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["error_key","category"],"properties":{"error_key":{"type":"string","description":"Specifies where the error occurs. Typically this key identifies the attribute/parameter related to the error."},"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."},"message":{"type":"string","description":"Provides details about the error - generally this message can be surfaced to an end user."}}}}},"x-examples":{"not_found":{"errors":[{"error_key":"request","category":"not_found","message":"The requested resource was not found."}]},"deprecated_accept_terms_of_service":{"errors":[{"error_key":"request","category":"deprecated_endpoint","message":"The requested endpoint is no longer supported in the requested API version. Use POST /v1/partner_managed_companies/:company_uuid/terms_of_service instead"}]},"deprecated_retrieve_terms_of_service":{"errors":[{"error_key":"request","category":"deprecated_endpoint","message":"The requested endpoint is no longer supported in the requested API version. Use PUT /v1/partner_managed_companies/:company_uuid/terms_of_service instead"}]}}},"Conflict-Error-Object":{"description":"Conflict\n  \nThis error occurs when the resource version provided does not match the current version. Retrieve the latest version and retry.","type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["error_key","category"],"properties":{"error_key":{"type":"string","description":"Specifies where the error occurs. Typically this key identifies the attribute/parameter related to the error."},"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."},"message":{"type":"string","description":"Provides details about the error - generally this message can be surfaced to an end user."}}}}},"x-examples":{"invalid_version":{"errors":[{"error_key":"base","category":"invalid_resource_version","message":"You are attempting to update a resource using an out-of-date version."}]}}},"Forbidden-Error-Object":{"description":"Forbidden\n  \nThe targeted company has been archived because its EIN was reassigned to a replacement company. Use the replacement company referenced in the error metadata.","type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Entity-Error-Object"}}},"x-examples":{"company_auto_archived":{"errors":[{"error_key":"base","category":"invalid_operation","message":"This company was archived because its EIN was reassigned to a replacement company. Use the replacement company referenced in the error metadata to proceed.","metadata":{"replacement_company_uuid":"2b9e7c14-6d3a-4f52-9e8b-1a7c4d05f6e0"}}]}}},"Unprocessable-Entity-Error-Object":{"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","type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Entity-Error-Object"}}},"x-examples":{"partner_managed_company_disassociate_not_associated":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Could not disassociate from embedded payroll: company not associated with partner."}]},"bulk_report_invalid_report_type":{"errors":[{"error_key":"batch","category":"nested_errors","errors":[{"idx":0,"category":"nested_errors","errors":[{"error_key":"report_type","category":"invalid_attribute_value","message":"Invalid report type: invalid_type"}]}]}]},"nested_disbursement_errors":{"errors":[{"error_key":"disbursements","category":"nested_errors","metadata":{"employee_uuid":"invalid-uuid-1"},"errors":[{"error_key":"employee_uuid","category":"not_found","message":"Disbursement not found."}]},{"error_key":"disbursements","category":"nested_errors","metadata":{"employee_uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"errors":[{"error_key":"payment_method","category":"invalid_attribute_value","message":"Payment method must be one of: Direct Deposit, Check."},{"error_key":"payment_status","category":"invalid_attribute_value","message":"Payment status is not valid for payment method 'InvalidMethod'."}]}]},"webhook_subscription_url_missing":{"errors":[{"error_key":"url","category":"invalid_attribute_value","message":"URL can't be blank"}]},"webhook_subscription_invalid_entity_type":{"errors":[{"error_key":"subscription_entities.entity_type","category":"invalid_attribute_value","message":"Entity type is not included in the list"}]},"invalid_token":{"errors":[{"error_key":"base","category":"invalid_attribute_value","message":"Invalid verification token"}]},"notification_supporting_data_invalid":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Invalid notification: supporting data is no longer valid."}]},"employee_payment_details_invalid_filter_combination":{"errors":[{"error_key":"base","category":"invalid_request_error","message":"Cannot filter by both employee_uuid and payroll_uuid simultaneously."}]},"contractor_document_sign_missing_agree":{"errors":[{"error_key":"agree","category":"invalid_attribute_value","message":"You must agree to sign the document electronically"}]},"contractor_document_sign_invalid_ip_address":{"errors":[{"error_key":"signed_by_ip_address","category":"invalid_attribute_value","message":"Signed by ip address is invalid"}]},"contractor_document_sign_missing_fields":{"errors":[{"error_key":"fields","category":"nested_errors","errors":[{"error_key":"dogs_name","category":"invalid_attribute_value","message":"Field is required."},{"error_key":"dogs_favorite_food","category":"invalid_attribute_value","message":"Field is required."},{"error_key":"dogs_signature","category":"invalid_attribute_value","message":"Field is required."}]}]},"contractor_document_sign_already_signed":{"errors":[{"error_key":"base","category":"invalid_operation","message":"This form has already been signed"}]},"contractor_document_unsupported_form_type":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Form type is not supported"}]},"bank_account_delete_unfunded_payments":{"errors":[{"error_key":"base","category":"invalid_operation","message":"FundingMethod has unfunded payments"}]},"bank_account_verify_incorrect_deposits":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Your bank account cannot be verified. Please check the test deposit amounts."}]},"bank_account_verify_already_verified":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Your bank account has already been verified."}]},"bank_account_missing_routing":{"errors":[{"error_key":"routing_number","category":"invalid_attribute_value","message":"Routing number is required."}]},"plaid_processor_token_missing":{"errors":[{"error_key":"processor_token","category":"invalid_attribute_value","message":"Processor token param is missing or the value is empty: processor_token"}]},"contractor_bank_account_invalid_account_number":{"errors":[{"error_key":"account_number","category":"invalid_attribute_value","message":"Invalid account number format"}]},"contractor_bank_account_invalid_account_type":{"errors":[{"error_key":"account_type","category":"invalid_attribute_value","message":"Account type's value is not included in the list"}]},"contractor_payment_method_invalid_type":{"errors":[{"error_key":"type","category":"invalid_attribute_value","message":"Payment method must be 'Check' or 'Direct Deposit'"}]},"company_attachment_missing_document":{"errors":[{"error_key":"base","category":"missing_parameter","message":"'document' is required"}]},"company_attachment_invalid_category":{"errors":[{"error_key":"base","category":"missing_parameter","message":"Attachment category is not supported"}]},"company_attachment_invalid_file_type":{"errors":[{"error_key":"file","category":"invalid_attribute_value","message":"file type is not allowed"}]},"provision_missing_user":{"errors":[{"error_key":"user","category":"missing_parameter","message":"user is required."}]},"provision_invalid_email":{"errors":[{"error_key":"base","category":"invalid_attribute_value","message":"Invalid email address."}]},"admin_missing_required_field":{"errors":[{"error_key":"last_name","category":"missing_parameter","message":"last_name is required."}]},"admin_duplicate_email":{"errors":[{"error_key":"email","category":"invalid_attribute_value","message":"User has already been taken"},{"error_key":"company","category":"invalid_attribute_value","message":"Company is invalid"}]},"sandbox_w2_already_generated":{"errors":[{"error_key":"base","category":"invalid_attribute_value","message":"W2 already generated for this year"}]},"sandbox_w2_invalid_year":{"errors":[{"error_key":"base","category":"invalid_attribute_value","message":"Cannot generate form for year 1800"}]},"sandbox_1099_invalid_year":{"errors":[{"error_key":"base","category":"invalid_attribute_value","message":"Please enter a year between 2015 and 2024"}]},"employee_bank_account_missing_name":{"errors":[{"error_key":"name","category":"invalid_attribute_value","message":"Name is required"}]},"employee_bank_account_invalid_account_number":{"errors":[{"error_key":"account_number","category":"invalid_attribute_value","message":"Invalid account number"}]},"employee_bank_account_duplicate":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Bank account with the same details already exists"}]},"employee_bank_account_invalid_routing_on_update":{"errors":[{"error_key":"routing_number","category":"invalid_attribute_value","message":"Invalid routing number"}]},"payment_configs_missing_parameter":{"errors":[{"error_key":"base","category":"missing_parameter","message":"At least one parameter must be provided"}]},"payment_configs_invalid_fast_payment_limit":{"errors":[{"error_key":"fast_payment_limit","category":"invalid_attribute_value","message":"Fast payment limit should be a number"}]},"pay_periods_invalid_end_date":{"errors":[{"error_key":"end_date","category":"invalid_parameter","message":"End date cannot be more than 3 months in future"}]},"company_industry_selection_naics_code_required":{"errors":[{"error_key":"naics_code","category":"invalid_attribute_value","message":"Naics code is required."}]},"company_industry_selection_naics_code_invalid":{"errors":[{"error_key":"naics_code","category":"invalid_attribute_value","message":"Naics code must be equal to 6 digits."}]},"company_industry_selection_sics_codes_invalid":{"errors":[{"error_key":"sic_codes","category":"invalid_attribute_value","message":"Sic codes must be equal to 4 digits"}]},"time_off_policy_name_required":{"errors":[{"error_key":"name","category":"invalid_attribute_value","message":"Name is required."}]},"time_off_policy_unlimited_invalid_accrual_rate":{"errors":[{"error_key":"accrual_rate","category":"invalid_operation","message":"Accrual rate must be blank for unlimited policies."}]},"time_off_policy_pending_requests":{"errors":[{"error_key":"time_off_policy","category":"invalid_operation","message":"Cannot deactivate policy with pending time off requests."}]},"time_off_policy_employees_required":{"errors":[{"error_key":"employees","category":"invalid_attribute_value","message":"Employees are required."}]},"time_off_policy_unlimited_balance_update":{"errors":[{"error_key":"base","category":"invalid_attribute_value","message":"Can not adjust balances for unlimited policies."}]},"payroll_sync_invalid_pay_schedule":{"errors":[{"error_key":"pay_schedule_uuid","category":"invalid_attribute_value","message":"Pay schedule uuid could not be found."}]},"payroll_sync_no_employees":{"errors":[{"error_key":"base","category":"invalid_operation","message":"There are no employees to run payroll for in the selected pay period."}]},"payroll_sync_empty_export":{"errors":[{"error_key":"base","category":"invalid_operation","message":"There are no hours to sync to payroll for the selected pay period."}]},"payroll_update_payroll_item_validation_error":{"errors":[{"error_key":"employee_compensations","category":"nested_errors","errors":[{"error_key":"payment_method","category":"invalid_attribute_value","message":"Payment method cannot be changed for check-only payrolls. All employees must be paid by check."}]}]},"payroll_update_recurring_reimbursement_error":{"errors":[{"error_key":"employee_compensations","category":"nested_errors","errors":[{"error_key":"reimbursements","category":"invalid_attribute_value","message":"Cannot update recurring reimbursements through payroll updates. Update the recurring reimbursement directly."}]}]},"migrate_company_terms_of_service":{"errors":[{"error_key":"base","category":"migration_blocker","message":"Terms of service must be accepted by a company payroll admin.","metadata":{"key":"terms_of_service"}}]},"migrate_company_already_migrated":{"errors":[{"error_key":"base","category":"invalid_attribute_value","message":"The operation was already performed for this company.","metadata":{"key":"migrated_company"}}]},"partner_managed_company_create_missing_company":{"errors":[{"error_key":"company","category":"missing_parameter","message":"company is required."}]},"partner_managed_company_create_invalid_name":{"errors":[{"error_key":"name","category":"invalid_attribute_value","message":"Company name must be at least 2 characters"}]},"partner_managed_company_tos_invalid_ip_address":{"errors":[{"error_key":"ip_address","category":"invalid_attribute_value","message":"A valid user's IP Address is required in order to accept terms of service."}]},"partner_managed_company_tos_missing_external_user_id":{"errors":[{"error_key":"external_user_id","category":"invalid_attribute_value","message":"Your platform's User ID is required in order to accept terms of service."}]},"partner_managed_company_tos_invalid_user_email":{"errors":[{"error_key":"email","category":"invalid_attribute_value","message":"Email does not belong to company user."}]},"holiday_pay_policy_already_exists":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Company already has a holiday pay policy."}]},"holiday_pay_policy_not_exists":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Company does not have a holiday pay policy, please create one"}]},"holiday_pay_policy_invalid_employees":{"errors":[{"error_key":"employees","category":"invalid_attribute_value","message":"Invalid employee uuids provided."}]},"onboarded_employee":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Cannot delete onboarded employee"}]},"garnishment_invalid_amount":{"errors":[{"error_key":"amount","category":"invalid_attribute_value","message":"Amount must be greater than or equal to 0"}]},"garnishment_pay_period_exceeds_annual":{"errors":[{"error_key":"pay_period_maximum","category":"invalid_attribute_value","message":"Pay period maximum must be less than annual maximum"}]},"garnishment_type_cannot_change":{"errors":[{"error_key":"garnishment_type","category":"invalid_attribute_value","message":"Garnishment type cannot change"}]},"garnishment_child_support_invalid_fips":{"errors":[{"error_key":"child_support","category":"nested_errors","errors":[{"error_key":"fips_code","category":"invalid_attribute_value","message":"FIPS code is not valid for CA"}]}]},"garnishment_child_support_missing_fields":{"errors":[{"error_key":"child_support","category":"nested_errors","errors":[{"error_key":"state","category":"invalid_attribute_value","message":"Select a valid state agency"},{"error_key":"payment_period","category":"invalid_attribute_value","message":"Select a valid payment period"},{"error_key":"case_number","category":"invalid_attribute_value","message":"Case number is required"}]}]},"invalid_attribute":{"errors":[{"error_key":"base","category":"invalid_operation","message":"There is an error in the request body."}]},"pay_schedule_missing_anchor_dates":{"errors":[{"error_key":"anchor_pay_date","category":"invalid_attribute_value","message":"can't be blank"},{"error_key":"anchor_end_of_pay_period","category":"invalid_attribute_value","message":"can't be blank"}]},"pay_schedule_invalid_frequency":{"errors":[{"error_key":"frequency","category":"invalid_attribute_value","message":"is not included in the list"}]},"pay_schedule_malformed_dates":{"errors":[{"error_key":"anchor_pay_date","category":"invalid_attribute_value","message":"is invalid"},{"error_key":"anchor_end_of_pay_period","category":"invalid_attribute_value","message":"is invalid"}]},"skip_payroll_invalid_payroll_type":{"errors":[{"error_key":"payroll_type","category":"invalid_attribute_value","message":"Payroll type is not valid."}]},"paid_holidays_invalid_year":{"errors":[{"error_key":"base","category":"invalid_attribute_value","message":"Invalid year provided."}]},"tax_requirements_invalid_requirement_key":{"errors":[{"error_key":"requirement_sets","category":"nested_errors","metadata":{"key":"misc","effective_from":null,"state":"NY"},"errors":[{"error_key":"requirements","category":"nested_errors","metadata":{"key":"1-2-3-4"},"errors":[{"error_key":"key","category":"invalid_attribute_value","message":"Key is required"}]}]}]},"tax_requirements_invalid_value_type":{"errors":[{"error_key":"requirement_sets","category":"nested_errors","metadata":{"key":"misc","effective_from":null,"state":"NY"},"errors":[{"error_key":"requirements","category":"nested_errors","metadata":{"key":"71653ec0-00b5-4c66-a58b-22ecf21704c5"},"errors":[{"error_key":"value","category":"invalid_attribute_value","message":"Expected a value of type boolean, but got string"}]}]}]},"tax_requirements_domain_validation_failure":{"errors":[{"error_key":"requirement_sets","category":"nested_errors","metadata":{"key":"taxrates","effective_from":"2026-01-01","state":"NY"},"errors":[{"error_key":"requirements","category":"nested_errors","metadata":{"key":"e0ac2284-8d30-4100-ae23-f85f9574868b"},"errors":[{"error_key":"value","category":"invalid_attribute_value","message":"SUI Tax Rate must be between 0.00% and 9.825%"}]}]}]},"company_cannot_enable_contractor_only":{"errors":[{"error_key":"contractor_only","category":"invalid_attribute_value","message":"Contractor only cannot be enabled for existing companies."}]},"company_missing_parameter":{"errors":[{"error_key":"base","category":"missing_parameter","message":"contractor_only is required."}]},"starting_after_uuid_invalid":{"errors":[{"error_key":"starting_after_uuid","category":"invalid_attribute_value","message":"Parameter 'starting_after_uuid' does not correspond to a valid event."}]},"resource_uuid_invalid":{"errors":[{"error_key":"resource_uuid","category":"invalid_attribute_value","message":"Parameter 'resource_uuid' does not correspond to a valid resource."}]},"payroll_gross_up_invalid_net_pay":{"errors":[{"error_key":"net_pay","category":"invalid_attribute_value","message":"Net pay must be a number."}]},"payroll_accruing_hours_invalid":{"errors":[{"error_key":"base","category":"invalid_attribute_value","message":"Hours cannot be negative."}]},"payroll_cannot_cancel":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Payroll cannot be canceled."}]},"frozen_payroll":{"errors":[{"error_key":"base","category":"invalid_operation","message":"This payroll has already been processed. Its data cannot be updated or altered."}]},"frozen_payroll_processing":{"errors":[{"error_key":"base","category":"invalid_operation","message":"This payroll is being processed and cannot be updated at this time."}]},"unmodifiable_payroll_type":{"errors":[{"error_key":"base","category":"invalid_operation","message":"This type of payroll cannot be modified or processed. It is reserved for system processes."}]},"employee_uuids_required":{"errors":[{"error_key":"employee_uuids","category":"invalid_attribute_value","message":"At least one employee_uuid is required to create an off-cycle payroll."}]},"invalid_employee_uuids_format":{"errors":[{"error_key":"employee_uuids","category":"invalid_attribute_value","message":"Parameter employee_uuids must be an array."}]},"maximum_employee_uuids_surpassed":{"errors":[{"error_key":"employee_uuids","category":"invalid_attribute_value","message":"Exceeded maximum of 100 for lookup."}]},"invalid_employee_uuid":{"errors":[{"error_key":"employee_uuids","category":"invalid_attribute_value","message":"Invalid Employee UUID(s).","metadata":{"entity_type":"Employee","entity_uuid":"invalid-uuid-123"}}]},"payroll_blocker_missing_bank_info":{"errors":[{"error_key":"base","category":"payroll_blocker","message":"Company must have a bank account in order to run payroll.","metadata":{"key":"missing_bank_info"}}]},"payroll_blocker_missing_employee_setup":{"errors":[{"error_key":"base","category":"payroll_blocker","message":"Company must add employees in order to run payroll.","metadata":{"key":"missing_employee_setup"}}]},"payroll_blocker_missing_federal_tax_setup":{"errors":[{"error_key":"base","category":"payroll_blocker","message":"Company must complete federal tax setup in order to run payroll.","metadata":{"key":"missing_federal_tax_setup"}}]},"payroll_blocker_missing_bank_verification":{"errors":[{"error_key":"base","category":"payroll_blocker","message":"Company bank account must be verified in order to run payroll.","metadata":{"key":"missing_bank_verification"}}]},"payroll_blocker_suspended":{"errors":[{"error_key":"base","category":"payroll_blocker","message":"Company is suspended and cannot run payroll.","metadata":{"key":"suspended"}}]},"submission_blocker_missing_selection":{"errors":[{"error_key":"submission_blockers","category":"invalid_attribute_value","message":"Submission blockers selections required"}]},"submission_blocker_invalid_option":{"errors":[{"error_key":"submission_blockers","category":"nested_errors","metadata":{"blocker_type":"fast_ach_threshold_exceeded"},"errors":[{"error_key":"selected_option","category":"invalid_attribute_value","message":"Selection is not available to resolve Fast ACH Threshold Exceeded. Please choose one of Wire In, Move To Four Day"}]}]},"invalid_version":{"errors":[{"error_key":"base","category":"invalid_resource_version","message":"You are attempting to update a resource using an out-of-date version."}]},"payroll_update_stale_employee_compensation_version":{"errors":[{"error_key":"base","category":"invalid_resource_version","message":"Supplied Version (stale-version) is invalid.","metadata":{"entity_type":"Employee","entity_uuid":"a8e9d2c6-1f3b-4d5a-9c8e-7f0b2d4c6e8a"}}]},"employee_create_self_onboarding_missing_email":{"errors":[{"error_key":"email","category":"invalid_attribute_value","message":"Email is required to invite the employee to self-onboard"}]},"employee_benefit_simple_ira_elective_mismatch":{"errors":[{"error_key":"elective","category":"invalid_attribute_value","message":"Elective must be true for matching Simple IRA benefits"}]},"signatory_email_required":{"errors":[{"error_key":"email","category":"invalid_attribute_value","message":"Email is required"}]},"signatory_company_already_has_signatory":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Cannot have more than one signatory in a company. Please remove the existing signatory before adding a new one."}]},"mixed_disbursement_errors":{"errors":[{"error_key":"disbursements","category":"nested_errors","metadata":{"contractor_payment_uuid":"invalid-uuid-1"},"errors":[{"error_key":"contractor_payment_uuid","category":"not_found","message":"Disbursement not found."}]},{"error_key":"disbursements","category":"nested_errors","metadata":{"contractor_payment_uuid":"d0dfa222-ad08-4ea7-a06a-717688c3b179"},"errors":[{"error_key":"payment_method","category":"invalid_attribute_value","message":"Payment method must be one of: Direct Deposit, Check."},{"error_key":"payment_status","category":"invalid_attribute_value","message":"Payment status is not valid for payment method 'InvalidMethod'."}]}]},"not_found":{"errors":[{"error_key":"request","category":"not_found","message":"The requested resource was not found."}]},"finish_onboarding_incomplete":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Company is not ready to exit onboarding."}]},"federal_tax_invalid_ein":{"errors":[{"error_key":"ein","category":"invalid_attribute_value","message":"EIN must be 9 digits"}]},"federal_tax_ein_cannot_change":{"errors":[{"error_key":"ein","category":"invalid_attribute_value","message":"EIN cannot be updated after company has been onboarded. Please contact support to update the EIN."}]},"federal_tax_legal_name_cannot_change":{"errors":[{"error_key":"legal_name","category":"invalid_attribute_value","message":"Legal name cannot be updated after company has been onboarded. Please contact support to update the legal name."}]},"ein_collision":{"errors":[{"error_key":"ein","category":"invalid_attribute_value","message":"EIN is already in use"}]},"company_location_validation":{"errors":[{"error_key":"street_1","category":"invalid_attribute_value","message":"Must include a street address"},{"error_key":"city","category":"invalid_attribute_value","message":"Must include a city"},{"error_key":"state","category":"invalid_attribute_value","message":"State is in the wrong format"},{"error_key":"zip","category":"invalid_attribute_value","message":"Please enter a valid zip code (e.g. 12345)."},{"error_key":"phone_number","category":"invalid_attribute_value","message":"Phone number must be 10 digits"}]},"conflict":{"errors":[{"error_key":"request","category":"duplicate_operation","message":"A resource with these attributes already exists."}]},"invalid_parameter":{"errors":[{"error_key":"request","category":"invalid_parameter","message":"The provided parameter is invalid or missing."}]},"invalid_sort_by":{"errors":[{"error_key":"sort_by","category":"invalid_parameter","message":"Invalid sort order or direction."}]},"flow_invalid_entity":{"errors":[{"error_key":"entity_type","category":"invalid_attribute_value","message":"Invalid flow entity"},{"error_key":"entity_uuid","category":"invalid_attribute_value","message":"Invalid flow entity"}]},"flow_nested_options_errors":{"errors":[{"error_key":"options","category":"nested_errors","metadata":{"flow_type":"company_forms"},"errors":[{"error_key":"form_types","category":"invalid_attribute_value","message":"Supplied value 'invalid' contains no permitted values"}]}]},"basic":{"errors":[{"error_key":"base","category":"payroll_blocker","message":"Company must complete all onboarding requirements in order to run payroll.","metadata":{"key":"needs_onboarding"}}]},"contractor_already_onboarded":{"errors":[{"error_key":"onboarding_status","category":"invalid_attribute_value","message":"Contractor is already fully onboarded"}]},"contractor_is_active_pending_dismissal":{"errors":[{"error_key":"is_active","category":"invalid_attribute_value","message":"Cannot deactivate while a dismissal is scheduled. Use the cancel termination endpoint to remove the pending dismissal first."}]},"contractor_is_active_pending_dismissal_uncancelable":{"errors":[{"error_key":"is_active","category":"invalid_attribute_value","message":"Cannot deactivate while a non-cancelable dismissal is in progress. The dismissal has already been processed."}]},"contractor_is_active_pending_rehire":{"errors":[{"error_key":"is_active","category":"invalid_attribute_value","message":"Cannot reactivate while a rehire is scheduled. Use the cancel rehire endpoint to remove the pending rehire first."}]},"contractor_rehire_start_date_required":{"errors":[{"error_key":"start_date","category":"invalid_attribute_value","message":"Start date is required"}]},"contractor_rehire_no_pending":{"errors":[{"error_key":"base","category":"invalid_operation","message":"No pending rehire to cancel"}]},"contractor_termination_end_date_required":{"errors":[{"error_key":"end_date","category":"invalid_attribute_value","message":"End date is required"}]},"contractor_termination_no_pending_dismissal":{"errors":[{"error_key":"base","category":"invalid_operation","message":"No pending dismissal to cancel"}]},"contractor_address_invalid_attribute":{"errors":[{"error_key":"street_1","category":"invalid_attribute_value","message":"Must include a street address"}]},"contractor_payment_invalid_wage":{"errors":[{"error_key":"wage","category":"invalid_attribute_value","message":"Wage must be greater than or equal to 0."}]},"contractor_payment_cannot_cancel":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Payment has already been processed and cannot be cancelled. Contact support directly."}]},"contractor_payment_should_not_be_funded":{"errors":[{"error_key":"base","category":"invalid_operation","message":"This payment should not be funded."}]},"contractor_payments_preview_no_payments":{"errors":[{"error_key":"contractor_payments","category":"invalid_attribute_value","message":"Please enter a contractor payment before continuing."}]},"ytd_benefit_amounts_invalid_tax_year":{"errors":[{"error_key":"tax_year","category":"invalid_attribute_value","message":"Tax year must be greater than or equal to 2000"}]},"printable_payroll_checks_invalid_printing_format":{"errors":[{"error_key":"base","category":"invalid_attribute_value","message":"Invalid printing_format 'bad_name', only 'top' and 'bottom' supported"}]},"recovery_case_not_redebitable":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Unable to initiate another redebit at this time. Please contact support."}]},"recovery_case_exceeded_retries":{"errors":[{"error_key":"base","category":"invalid_operation","message":"You exceeded the maximum redebit attempts. Please contact support."}]},"report_invalid_columns":{"errors":[{"error_key":"columns","category":"invalid_attribute_value","message":"Invalid column(s): unexpected_column"}]},"general_ledger_invalid_aggregation":{"errors":[{"error_key":"aggregation","category":"invalid_attribute_value","message":"Invalid aggregation option."}]},"report_template_invalid_report_type":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Invalid report type"}]},"time_sheet_invalid_entries":{"errors":[{"error_key":"entries","category":"invalid_attribute_value","message":"Entries are invalid"}]},"time_sheet_invalid_attribute":{"errors":[{"error_key":"time_zone","category":"invalid_attribute_value","message":"Time zone is invalid"}]},"time_sheet_version_invalid":{"errors":[{"error_key":"version","category":"invalid_attribute_value","message":"Version 'somefakeversion' does not match the latest version of this object"}]},"time_off_request_cannot_delete":{"errors":[{"error_key":"base","category":"invalid_operation","message":"This time off request cannot be deleted."}]},"time_off_request_cannot_approve":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Cannot approve this request."}]},"time_off_request_missing_employer_note":{"errors":[{"error_key":"employer_note","category":"missing_parameter","message":"'employer_note' is required"}]},"time_off_request_invalid_status_filter":{"errors":[{"error_key":"status","category":"invalid_parameter","message":"Parameter `status` contains invalid value(s): cancelled. Allowed values: pending, approved, declined, consumed."}]},"resource":{"errors":[{"error_key":"first_name","category":"invalid_attribute_value","message":"First name is required"},{"error_key":"date_of_birth","category":"invalid_attribute_value","message":"Date of birth is not a valid date"}]},"nested":{"errors":[{"error_key":"contractor_payments","category":"nested_errors","metadata":{"contractor_uuid":"72ae4617-daa9-4ed7-85e0-18ed5d0ee835"},"errors":[{"error_key":"hours","category":"invalid_attribute_value","message":"Ella Fitzgerald is paid fixed wage and hours cannot be set on a contractor payment"}]},{"error_key":"contractor_payments","category":"nested_errors","metadata":{"contractor_uuid":"2d7bf62c-babf-4a12-8292-340e2d9cab28"},"errors":[{"error_key":"wage","category":"invalid_attribute_value","message":"Isaiah Berlin is paid hourly and wage cannot be set on a contractor payment"}]}]},"compensation_invalid_rate":{"errors":[{"error_key":"rate","category":"invalid_attribute_value","message":"Rate is not a valid number"}]},"compensation_invalid_payment_unit":{"errors":[{"error_key":"payment_unit","category":"invalid_attribute_value","message":"Payment unit must be one of Hour, Week, Month, or Year"}]},"compensation_already_processed":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Compensation has already been processed on payroll."}]},"termination_already_terminated":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Employee may only have one termination"}]},"termination_invalid_effective_date":{"errors":[{"error_key":"effective_date","category":"invalid_attribute_value","message":"Effective date is not a valid date"}]},"termination_effective_date_required":{"errors":[{"error_key":"effective_date","category":"invalid_attribute_value","message":"Effective date is required"}]},"termination_already_in_effect":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Employee has already been terminated"}]},"termination_payroll_exists":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Cannot cancel a termination with a termination payroll"}]},"termination_rehired":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Unable to modify a termination with a future rehire."}]},"job_title_required":{"errors":[{"error_key":"title","category":"invalid_attribute_value","message":"Title is required"}]},"job_primary_cannot_delete":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Employee's primary job cannot be set to inactive."}]},"job_exempt_multiple_jobs":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Only hourly employees can have multiple jobs."}]},"job_invalid_hire_date":{"errors":[{"error_key":"hire_date","category":"invalid_attribute_value","message":"Hire date is invalid"}]},"job_duplicate_title":{"errors":[{"error_key":"title","category":"invalid_attribute_value","message":"Employee cannot have two jobs with the same title."}]},"i9_authorization_unneeded_document_params":{"errors":[{"error_key":"expiration_date","category":"invalid_attribute_value","message":"For the submitted authorization status, expiration date is not allowed"},{"error_key":"document_type","category":"invalid_attribute_value","message":"For the submitted authorization status, document type is not allowed"}]},"i9_authorization_not_self_onboarding":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Employee is not self-onboarding."}]},"i9_authorization_employee_already_signed":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Employee has already signed the form."}]},"i9_employer_sign_invalid_params":{"errors":[{"error_key":"signed_by_ip_address","category":"invalid_attribute_value","message":"Signed by IP address is invalid"},{"error_key":"signer_title","category":"invalid_attribute_value","message":"Signer title is required"},{"error_key":"agree","category":"invalid_attribute_value","message":"You must agree to sign electronically"},{"error_key":"signature_text","category":"invalid_attribute_value","message":"Signature text is required"}]},"i9_employer_sign_employee_not_signed":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Employee has not signed I-9"}]},"i9_employer_sign_already_signed":{"errors":[{"error_key":"base","category":"invalid_operation","message":"I-9 has already been signed by the employer"}]},"i9_documents_already_signed":{"errors":[{"error_key":"base","category":"invalid_operation","message":"I-9 cannot be updated as it has already been signed by the employer"}]},"i9_documents_invalid_params":{"errors":[{"error_key":"documents","category":"nested_errors","metadata":{"document_type":"invalid_type"},"errors":[{"error_key":"document_type","category":"invalid_attribute_value","message":"Document type's value is not included in the list"},{"error_key":"document_title","category":"invalid_attribute_value","message":"Document title's value is not included in the list"}]}]},"i9_documents_not_array":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Parameter `documents` must be an array"}]},"company_benefit_missing_benefit_type":{"errors":[{"error_key":"base","category":"missing_parameter","message":"benefit_type is required."}]},"company_benefit_invalid_benefit_type":{"errors":[{"error_key":"benefit_type","category":"invalid_attribute_value","message":"Benefit type does not correspond with a supported benefit"}]},"company_benefit_missing_description":{"errors":[{"error_key":"description","category":"invalid_attribute_value","message":"Description is required"}]},"company_benefit_cannot_disable":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Company benefit cannot be disabled while employees are still enrolled"}]},"company_benefit_cannot_change_type":{"errors":[{"error_key":"benefit_type","category":"invalid_attribute_value","message":"The associated benefit cannot be changed"}]},"company_benefit_invalid_contribution_exclusions":{"errors":[{"error_key":"contribution_exclusions","category":"invalid_attribute_value","message":"Expected contribution_exclusions array of hashes."}]},"employee_benefits_invalid_parameter":{"errors":[{"error_key":"employee_benefits","category":"invalid_parameter","message":"Missing or invalid parameter 'employee_benefits'."}]},"time_off_activity_invalid_type":{"errors":[{"error_key":"base","category":"invalid_parameter","message":"Expected one of: vacation, sick"}]},"employee_benefit_negative_company_contribution":{"errors":[{"error_key":"company_contribution","category":"invalid_attribute_value","message":"Company contribution must be greater than or equal to 0"}]},"employee_benefit_active_requires_contribution_or_deduction":{"errors":[{"error_key":"base","category":"invalid_operation","message":"An active employee benefit must have either a company contribution or an employee deduction"}]},"employee_benefit_invalid_effective_date":{"errors":[{"error_key":"effective_date","category":"invalid_attribute_value","message":"Effective date is not a valid date"}]},"employee_benefit_duplicate_type":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Employee cannot have more than one 401(k)"}]},"employee_benefit_invalid_limit_option":{"errors":[{"error_key":"limit_option","category":"invalid_attribute_value","message":"Limit option must be one of \"Family\", \"Individual\""}]},"employee_benefit_coverage_amount_only_for_gtl":{"errors":[{"error_key":"coverage_amount","category":"invalid_attribute_value","message":"Coverage amount is only applicable for group term life employee benefit."}]},"employee_benefit_destroy_invalid":{"errors":[{"error_key":"base","category":"invalid_attribute_value","message":"An active employee benefit must have either a company contribution or an employee deduction"}]},"company_benefit_has_employees":{"errors":[{"error_key":"base","category":"invalid_operation","message":"There are employees associated with this benefit, please remove these employees before deleting the benefit."}]},"company_benefit_partnered":{"errors":[{"error_key":"base","category":"invalid_operation","message":"This benefit is managed by the partner and cannot be deleted."}]},"rehire_delete_already_effective":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Unable to delete the rehire that is already effective, please terminate the employee instead."}]},"rehire_not_terminated":{"errors":[{"error_key":"effective_date","category":"invalid_attribute_value","message":"Cannot rehire if employee has not been terminated"}]},"rehire_missing_required_fields":{"errors":[{"error_key":"effective_date","category":"invalid_attribute_value","message":"Effective date is required"},{"error_key":"work_location_uuid","category":"invalid_attribute_value","message":"Work location not found"},{"error_key":"file_new_hire_report","category":"invalid_attribute_value","message":"File new hire report is required"}]},"rehire_invalid_work_location":{"errors":[{"error_key":"work_location_uuid","category":"invalid_attribute_value","message":"Work location not found"}]},"rehire_no_future_employment":{"errors":[{"error_key":"base","category":"invalid_operation","message":"The employee does not have any future employment, please rehire the employee first."}]},"earning_type_missing_name":{"errors":[{"error_key":"name","category":"invalid_attribute_value","message":"Name is required"}]},"earning_type_duplicate_name":{"errors":[{"error_key":"name","category":"invalid_attribute_value","message":"There is already an earning called Bonus"}]},"department_duplicate_title":{"errors":[{"error_key":"title","category":"invalid_attribute_value","message":"Department name has already been taken."}]},"department_has_active_members":{"errors":[{"error_key":"base","category":"invalid_operation","message":"You cannot delete a department that has active team members. Please remove them first."}]},"department_invalid_employees":{"errors":[{"error_key":"employees","category":"invalid_attribute_value","message":"Employees must be valid"},{"error_key":"contractors","category":"invalid_attribute_value","message":"Contractors must be valid"}]},"form_already_signed":{"errors":[{"error_key":"base","category":"invalid_operation","message":"This form has already been signed"}]},"form_no_signature_required":{"errors":[{"error_key":"base","category":"invalid_operation","message":"This form does not require a signature"}]},"form_invalid_ip_address":{"errors":[{"error_key":"signed_by_ip_address","category":"invalid_attribute_value","message":"Signed by ip address is invalid"}]},"form_preparer_not_supported":{"errors":[{"error_key":"base","category":"invalid_operation","message":"This form does not allow preparer information"}]},"invoice_period_invalid_format":{"errors":[{"error_key":"base","category":"invalid_parameter","message":"Invalid invoice_period param format, should be 'YYYY-MM'"}]},"invoice_period_future":{"errors":[{"error_key":"base","category":"invalid_parameter","message":"Invalid invoice_period param, cannot be a future invoice period"}]},"invoice_company_uuids_max_exceeded":{"errors":[{"error_key":"base","category":"invalid_parameter","message":"Invalid company_uuids passed, max of 50"}]},"wire_in_request_invalid_date_sent":{"errors":[{"error_key":"date_sent","category":"invalid_attribute_value","message":"Date sent must be a valid date"}]},"wire_in_request_missing_bank_name":{"errors":[{"error_key":"bank_name","category":"invalid_attribute_value","message":"Bank name must be present"}]},"wire_in_request_invalid_amount_sent":{"errors":[{"error_key":"amount_sent","category":"invalid_attribute_value","message":"Amount sent must be a number"}]},"wire_in_request_additional_notes_too_long":{"errors":[{"error_key":"additional_notes","category":"invalid_attribute_value","message":"Additional notes must be less than 255 characters"}]},"wire_in_request_not_awaiting_funds":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Wire in request status must be awaiting funds"}]},"external_payroll_missing_check_date":{"errors":[{"error_key":"check_date","category":"invalid_attribute_value","message":"Check date is required"}]},"external_payroll_missing_payment_period_dates":{"errors":[{"error_key":"payment_period_start_date","category":"invalid_attribute_value","message":"Payment period start date is required"},{"error_key":"payment_period_end_date","category":"invalid_attribute_value","message":"Payment period end date is required"}]},"external_payroll_net_pay_less_than_zero":{"errors":[{"error_key":"base","category":"invalid_attribute_value","message":"Net pay less than zero for one or more external payroll items"}]},"external_payroll_invalid_payroll_item":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Invalid payload or parameters"}]},"external_payrolls_locked":{"errors":[{"error_key":"base","category":"invalid_operation","message":"External Payrolls have already been finalized or a payroll has already been processed."}]},"employee_bank_account_destroy_invalid":{"errors":[{"error_key":"base","category":"invalid_attribute_value","message":"Cannot delete this bank account."}]},"external_payroll_invalid_liability_selection":{"errors":[{"error_key":"tax_id","category":"invalid_attribute_value","message":"Tax is required"}]},"invalid_tax_liability_selection":{"errors":[{"error_key":"tax_id","category":"invalid_attribute_value","message":"Tax is required"}]},"external_payroll_invalid_tax_liability_selections":{"errors":[{"error_key":"tax_id","category":"invalid_attribute_value","message":"Tax liability selections are not valid"}]},"member_portal_already_complete":{"errors":[{"error_key":"base","category":"invalid_operation","message":"Member has already complete member portal registration."}]},"member_portal_not_eligible":{"errors":[{"error_key":"base","category":"invalid_operation","message":"This member is not eligible for a member portal invitation in their current onboarding status (admin_onboarding_incomplete). Invite the member to self-onboard before sending a member portal invitation."}]},"member_portal_member_info_incomplete_missing_start_date":{"errors":[{"error_key":"base","category":"invalid_operation","message":"This member has not completed onboarding. Cannot proceed without member's job start date."}]},"member_portal_member_info_incomplete_missing_email":{"errors":[{"error_key":"base","category":"invalid_operation","message":"This member has not completed onboarding. Cannot proceed without an email."}]},"member_portal_already_cancelled":{"errors":[{"error_key":"base","category":"invalid_operation","message":"This invitation has already been cancelled."}]},"member_portal_not_cancellable":{"errors":[{"error_key":"base","category":"invalid_operation","message":"This invitation is no longer cancellable."}]}}},"Entity-Error-Object":{"type":"object","required":["error_key","category"],"properties":{"error_key":{"type":"string","description":"Specifies where the error occurs. Typically this key identifies the attribute/parameter related to the error."},"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. If category is `nested_errors`, the object will contain a nested `errors` property with entity errors."},"message":{"type":"string","description":"Provides details about the error - generally this message can be surfaced to an end user."},"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.","oneOf":[{"$ref":"#/components/schemas/Metadata-With-Multiple-Entities"},{"$ref":"#/components/schemas/Metadata-With-One-Entity"}]},"errors":{"type":"array","description":"Will only exist if category is `nested_errors`. It is possible to have multiple levels of nested errors.","items":{"type":"object","properties":{"error_key":{"type":"string","description":"Specifies where the error occurs. Typically this key identifies the attribute/parameter related to the error."},"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. If category is `nested_errors`, the object will contain a nested `errors` property with entity errors."},"message":{"type":"string","description":"Provides details about the error - generally this message can be surfaced to an end user."},"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."}}}}}},"Metadata-With-One-Entity":{"type":"object","description":"single entity","additionalProperties":true,"properties":{"entity_type":{"type":"string","description":"Name of the entity that the error corresponds to."},"entity_uuid":{"type":"string","description":"Unique identifier for the entity."},"valid_from":{"type":["string","null"]},"valid_up_to":{"type":["string","null"]},"key":{"type":["string","null"]},"state":{"type":["string","null"]}}},"Metadata-With-Multiple-Entities":{"type":"object","description":"multiple entities","required":["entities"],"properties":{"entities":{"type":"array","items":{"$ref":"#/components/schemas/Metadata-With-One-Entity"}}}},"Employee":{"title":"Employee","type":"object","description":"The representation of an employee in Gusto.","x-examples":{"success_status":{"uuid":"d7282d99-ab6b-42f5-ba45-f4a670e886a8","first_name":"Boaty","middle_initial":null,"last_name":"Koss","email":"keena.feest@kiehn.co.uk","company_uuid":"e904cc79-818a-4da8-9d37-0be0a86fdda8","manager_uuid":null,"version":"a5cec1f1c0135feb3e76ca6ea3c46176","current_employment_status":"full_time","onboarding_status":"onboarding_completed","preferred_first_name":null,"department_uuid":null,"employee_code":"46f036","payment_method":"Direct Deposit","department":null,"terminated":false,"two_percent_shareholder":false,"onboarded":true,"historical":false,"has_ssn":true,"onboarding_documents_config":{"uuid":null,"i9_document":false},"jobs":[{"uuid":"bc875f9d-adc5-40f6-99db-ed8470bda25f","version":"863bcd01c51fcfa2468d604cffec7413","employee_uuid":"d7282d99-ab6b-42f5-ba45-f4a670e886a8","current_compensation_uuid":"2ec164d0-808b-446c-8120-8cfb500945d0","payment_unit":"Year","primary":true,"two_percent_shareholder":false,"state_wc_covered":null,"state_wc_class_code":null,"title":"","compensations":[{"uuid":"2ec164d0-808b-446c-8120-8cfb500945d0","employee_uuid":"d7282d99-ab6b-42f5-ba45-f4a670e886a8","version":"db7bfb49a4f0893432cb562311bfcad9","payment_unit":"Year","flsa_status":"Exempt","adjust_for_minimum_wage":false,"minimum_wages":[],"job_uuid":"bc875f9d-adc5-40f6-99db-ed8470bda25f","effective_date":"2025-06-09","rate":"80000.00"}],"rate":"80000.00","hire_date":"2024-06-09"}],"eligible_paid_time_off":[],"terminations":[],"garnishments":[],"date_of_birth":"2005-06-09","ssn":"","phone":null,"work_email":null,"member_portal_invitation_status":{"status":"sent","token_expired":false,"welcome_email_sent_at":"2024-01-15T14:30:00Z","last_password_resent_at":null},"partner_portal_invitation_sent":true}},"properties":{"uuid":{"type":"string","description":"The UUID of the employee in Gusto.","readOnly":true},"first_name":{"type":"string"},"middle_initial":{"type":["string","null"]},"last_name":{"type":"string"},"email":{"type":["string","null"],"description":"The personal 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","description":"The UUID of the company the employee is employed by.","readOnly":true},"manager_uuid":{"type":["string","null"],"description":"The UUID of the employee's manager.","readOnly":true},"version":{"type":"string","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.","readOnly":true},"department":{"type":["string","null"],"description":"The employee's department in the company.","readOnly":true},"terminated":{"type":"boolean","description":"Whether the employee is terminated.","readOnly":true},"two_percent_shareholder":{"type":["boolean","null"],"description":"Whether the employee is a two percent shareholder of the company. This field only applies to companies with an S-Corp entity type."},"work_email":{"type":["string","null"],"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)."},"onboarded":{"type":"boolean","description":"Whether the employee has completed onboarding.","readOnly":true},"onboarding_status":{"description":"The current onboarding status of the employee","anyOf":[{"type":"string","enum":["onboarding_completed","admin_onboarding_incomplete","self_onboarding_pending_invite","self_onboarding_invited","self_onboarding_invited_started","self_onboarding_invited_overdue","self_onboarding_completed_by_employee","self_onboarding_awaiting_admin_review"]},{"type":"null"}],"readOnly":true},"onboarding_documents_config":{"type":"object","description":"Configuration for an employee onboarding documents during onboarding","properties":{"uuid":{"type":["string","null"],"description":"The UUID of the onboarding documents config","readOnly":true},"i9_document":{"type":"boolean","description":"Whether to include Form I-9 for an employee during onboarding","readOnly":true}}},"jobs":{"type":"array","items":{"$ref":"#/components/schemas/Job"}},"eligible_paid_time_off":{"type":"array","items":{"$ref":"#/components/schemas/Paid-Time-Off"}},"terminations":{"type":"array","items":{"$ref":"#/components/schemas/Termination"}},"garnishments":{"type":"array","items":{"$ref":"#/components/schemas/Garnishment"}},"custom_fields":{"type":"array","description":"Custom fields are only included for the employee if the include param has the custom_fields value set","items":{"$ref":"#/components/schemas/Employee-Custom-Field"}},"date_of_birth":{"type":["string","null"],"readOnly":true},"has_ssn":{"type":"boolean","description":"Indicates whether the employee has an SSN in Gusto."},"ssn":{"type":"string","description":"Deprecated. This field always returns an empty string."},"phone":{"type":["string","null"]},"preferred_first_name":{"type":["string","null"],"description":""},"payment_method":{"type":"string","description":"The employee's payment method","enum":["Direct Deposit","Check"],"default":"Check","nullable":false},"current_employment_status":{"anyOf":[{"type":"string","enum":["full_time","part_time_under_twenty_hours","part_time_twenty_plus_hours","variable","seasonal"]},{"type":"null"}],"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.","readOnly":true},"historical":{"type":"boolean","nullable":false},"employee_code":{"type":"string","description":"The short format code of the employee","nullable":false,"readOnly":true},"department_uuid":{"type":["string","null"],"description":"The UUID of the department the employee is under"},"title":{"type":"string","nullable":false},"hired_at":{"type":"string","nullable":false,"format":"date","description":"The date when the employee was hired to the company"},"hidden_ssn":{"type":"string","nullable":false},"flsa_status":{"$ref":"#/components/schemas/Flsa-Status-Type"},"applicable_tax_ids":{"type":"array","nullable":false,"items":{"type":"number"}},"member_portal_invitation_status":{"type":["object","null"],"description":"Member portal invitation status information. Only included when the include param has the portal_invitations value set.","properties":{"status":{"type":"string","description":"The current status of the member portal invitation.","enum":["pending","sent","verified","complete","cancelled"]},"token_expired":{"type":["boolean","null"],"description":"Whether the invitation token has expired."},"welcome_email_sent_at":{"type":["string","null"],"format":"date-time","description":"The date and time when the welcome email was sent."},"last_password_resent_at":{"type":["string","null"],"format":"date-time","description":"The date and time when the password reset was last resent."}}},"partner_portal_invitation_sent":{"type":["boolean","null"],"description":"Whether an external partner portal invitation webhook has been sent for this employee. Only included when the include param has the portal_invitations value set."}},"required":["uuid","first_name","last_name"],"readOnly":true},"Job":{"title":"Job","type":"object","properties":{"uuid":{"type":"string","description":"The UUID of the job.","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."},"employee_uuid":{"type":"string","description":"The UUID of the employee to which the job belongs.","readOnly":true},"hire_date":{"type":"string","readOnly":false,"description":"The date when the employee was hired or rehired for the job."},"title":{"type":["string","null"],"readOnly":false,"default":null,"description":"The title for the job."},"primary":{"type":"boolean","description":"Whether this is the employee's primary job. The value will be set to true unless an existing job exists for the employee.","readOnly":true},"rate":{"type":"string","description":"The employee's pay rate for this job (e.g., hourly wage or annual salary). This is sensitive compensation data and requires the `compensations:read` scope.","readOnly":true},"payment_unit":{"type":["string","null"],"description":"How the employee is paid for this job (e.g., Hour, Week, Month, Year, Paycheck). This is sensitive compensation data and requires the `compensations:read` scope.","readOnly":true},"current_compensation_uuid":{"type":"string","description":"The UUID of the current active compensation record for this job. Requires the `compensations:read` scope.","readOnly":true},"two_percent_shareholder":{"type":"boolean","description":"Whether the employee owns at least 2% of the company.","readOnly":false},"state_wc_covered":{"type":["boolean","null"],"description":"Whether this job is eligible for workers' compensation coverage in the state of Washington (WA).","readOnly":false},"state_wc_class_code":{"type":["string","null"],"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.","readOnly":false},"compensations":{"type":"array","description":"The compensation history for this job, including pay rate, payment unit, FLSA status, and effective dates. This is sensitive pay information and requires the `compensations:read` scope.","items":{"$ref":"#/components/schemas/Compensation"},"readOnly":true},"location_uuid":{"type":"string","nullable":false,"description":"The uuid of the employee's work location."},"location":{"$ref":"#/components/schemas/Location"}},"description":"The representation of a job in Gusto.","required":["uuid"],"x-examples":{"example":{"uuid":"d6d1035e-8a21-4e1d-89d5-fa894f9aff97","version":"gr78930htutrz444kuytr3s5hgxykuveb523fwl8sir","employee_uuid":"948daac8-4355-4ece-9e2a-229898accb22","hire_date":"2020-01-20","title":"Account Director","primary":true,"rate":"78000.00","payment_unit":"Year","current_compensation_uuid":"ea8b0b90-1112-4f9d-bb93-bf029bc8537a","two_percent_shareholder":false,"state_wc_covered":null,"state_wc_class_code":null,"compensations":[{"uuid":"ea8b0b90-1112-4f9d-bb93-bf029bc8537a","version":"98jr3289h3298hr9329gf9egskt3tjaj","job_uuid":"d6d1035e-8a21-4e1d-89d5-fa894f9aff97","employee_uuid":"948daac8-4355-4ece-9e2a-229898accb22","rate":"78000.00","payment_unit":"Year","flsa_status":"Exempt","effective_date":"2020-01-20","adjust_for_minimum_wage":false,"minimum_wages":[]}]},"secondary_job":{"uuid":"a1b2c3d4-5678-9012-abcd-ef1234567890","version":"hj29fh3298hf9832hf98h32f89h32f89h32f9832","employee_uuid":"948daac8-4355-4ece-9e2a-229898accb22","hire_date":"2020-01-20","title":"Senior Consultant","primary":false,"rate":"25.00","payment_unit":"Hour","current_compensation_uuid":"b2c3d4e5-6789-0123-bcde-f12345678901","two_percent_shareholder":false,"state_wc_covered":null,"state_wc_class_code":null,"compensations":[{"uuid":"b2c3d4e5-6789-0123-bcde-f12345678901","version":"93jr2398h23r9832rg9832rg98ewrg98e","job_uuid":"a1b2c3d4-5678-9012-abcd-ef1234567890","employee_uuid":"948daac8-4355-4ece-9e2a-229898accb22","rate":"25.00","payment_unit":"Hour","flsa_status":"Nonexempt","effective_date":"2020-01-20","adjust_for_minimum_wage":false,"minimum_wages":[]}]}}},"Jobs-Body":{"type":"object","properties":{"title":{"type":["string","null"],"description":"The job title.","example":"Regional Manager"},"hire_date":{"type":"string","description":"The date when the employee was hired or rehired for the job.","example":"2020-12-21"},"two_percent_shareholder":{"type":"boolean","description":"Whether the employee owns at least 2% of the company."},"state_wc_covered":{"type":["boolean","null"],"description":"Whether this job is eligible for workers' compensation coverage in the state of Washington (WA)."},"state_wc_class_code":{"type":["string","null"],"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."}}},"Jobs-Create-Request-Body":{"description":"Request body for creating a job.","type":"object","required":["title","hire_date"],"allOf":[{"$ref":"#/components/schemas/Jobs-Body"}],"x-examples":{"create_job":{"title":"Regional Manager","hire_date":"2020-12-21","two_percent_shareholder":false}}},"Jobs-Update-Request-Body":{"description":"Request body for updating a job.","type":"object","allOf":[{"$ref":"#/components/schemas/Versionable-Required"},{"$ref":"#/components/schemas/Jobs-Body"}],"x-examples":{"update_job":{"version":"gr78930htutrz444kuytr3s5hgxykuveb523fwl8sir","title":"Regional Manager","hire_date":"2020-12-21"}}},"Compensation":{"type":"object","description":"The representation of compensation in Gusto.","properties":{"uuid":{"type":"string","description":"The UUID of the compensation in Gusto.","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."},"job_uuid":{"type":"string","description":"The UUID of the job to which the compensation belongs.","readOnly":true},"employee_uuid":{"type":"string","description":"The UUID of the employee to which the compensation belongs.","readOnly":true},"rate":{"type":"string","readOnly":false,"description":"The dollar amount paid per payment unit."},"payment_unit":{"type":"string","readOnly":false,"description":"The unit accompanying the compensation rate. If the employee is an owner, rate should be 'Paycheck'.","enum":["Hour","Week","Month","Year","Paycheck"]},"flsa_status":{"$ref":"#/components/schemas/Flsa-Status-Type"},"title":{"type":"string","description":"The job title for this compensation."},"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","description":"Indicates if the compensation could be adjusted to minimum wage during payroll calculation.","readOnly":true},"minimum_wages":{"type":"array","readOnly":false,"description":"The minimum wages associated with the compensation.","items":{"type":"object","properties":{"uuid":{"type":"string","description":"The UUID of the minimum wage."},"wage":{"type":"string","description":"The wage amount."},"effective_date":{"type":"string","description":"The effective date of the minimum wage."}}}}},"required":["uuid"],"x-examples":{"success_status":{"uuid":"db4d41e5-813c-477e-bfae-38da2ae5e7a3","version":"56d00c178bc7393b2a206ed6a86afcb4","job_uuid":"c1fdb417-c34a-43a7-92f3-5e6c20c1d7a4","employee_uuid":"a7e8f9bc-0d12-4e56-b789-012345678901","rate":"70000.00","payment_unit":"Year","flsa_status":"Exempt","effective_date":"2023-01-01","adjust_for_minimum_wage":false,"minimum_wages":[],"title":"Software Engineer"},"hourly_compensation":{"uuid":"e5f6a7b8-c9d0-1234-e5f6-a7b8c9d01234","version":"98b7a6c5d4e3f2a1b0c9d8e7f6a5b4c3","job_uuid":"d2e5f8a1-b4c7-4d90-a3e6-f9b2c5d8e1a4","employee_uuid":"b8f9a0bc-1e23-4f67-c890-123456789012","rate":"25.00","payment_unit":"Hour","flsa_status":"Nonexempt","effective_date":"2023-01-01","adjust_for_minimum_wage":false,"minimum_wages":[],"title":"Associate"},"minimum_wage_adjusted":{"uuid":"a4d9ba9c-32cc-4cc1-a5bc-6ef4cd653e7a","version":"cc59bd3879d655fb940a1f6b675f2ad9","job_uuid":"d8f8fbe7-496d-4b69-86f0-1e2d1b73a086","rate":"5.00","payment_unit":"Hour","flsa_status":"Nonexempt","effective_date":"2018-12-11","adjust_for_minimum_wage":true,"minimum_wages":[{"uuid":"edeea5af-ecd6-4b1c-b5de-5cff2d302738","wage":"7.25","effective_date":"2018-12-11"}]}}},"Compensations-Body":{"type":"object","properties":{"rate":{"type":"string","description":"The dollar amount paid per payment unit.","example":"70000.00"},"payment_unit":{"type":"string","description":"The unit accompanying the compensation rate. If the employee is an owner, rate should be 'Paycheck'.","enum":["Hour","Week","Month","Year","Paycheck"],"example":"Year"},"flsa_status":{"$ref":"#/components/schemas/Flsa-Status-Type"},"effective_date":{"type":"string","description":"The effective date for this compensation.","example":"2023-01-01"},"title":{"type":"string","description":"The job title for this compensation.","example":"Software Engineer"},"adjust_for_minimum_wage":{"type":"boolean","description":"Whether the compensation should be adjusted to minimum wage during payroll calculation."},"minimum_wages":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","description":"The UUID of the minimum wage."}}}}}},"Compensations-Request-Body":{"description":"Request body for creating a compensation.","type":"object","required":["rate","payment_unit","flsa_status"],"allOf":[{"$ref":"#/components/schemas/Compensations-Body"}],"x-examples":{"create_compensation":{"rate":"70000.00","payment_unit":"Year","flsa_status":"Exempt","effective_date":"2023-01-01","title":"Software Engineer"}}},"Compensations-Update-Request-Body":{"description":"Request body for updating a compensation.","type":"object","allOf":[{"$ref":"#/components/schemas/Versionable-Required"},{"$ref":"#/components/schemas/Compensations-Body"}],"x-examples":{"update_compensation":{"version":"b48c46abfed1487b873b442334b3c4ff","rate":"75000.00","payment_unit":"Year","flsa_status":"Exempt","effective_date":"2023-01-01","title":"Senior Engineer"}}},"Paid-Time-Off":{"type":"object","description":"The representation of paid time off in Gusto.","properties":{"name":{"description":"The name of the paid time off type.","anyOf":[{"type":"string","enum":["Vacation Hours","Sick Hours","Holiday Hours"]},{"type":"null"}],"readOnly":true},"policy_name":{"type":["string","null"],"description":"The name of the time off policy.","readOnly":true},"policy_uuid":{"type":["string","null"],"description":"The UUID of the time off policy.","readOnly":true},"accrual_unit":{"type":["string","null"],"example":"Hour","description":"The unit the PTO type is accrued in.","readOnly":true},"accrual_rate":{"type":["string","null"],"description":"The number of accrual units accrued per accrual period.","readOnly":true},"accrual_method":{"type":["string","null"],"example":"unlimited","description":"The accrual method of the time off policy","readOnly":true},"accrual_period":{"type":["string","null"],"example":"Year","description":"The frequency at which the PTO type is accrued.","readOnly":true},"accrual_balance":{"type":["string","null"],"description":"The number of accrual units accrued.","readOnly":true},"maximum_accrual_balance":{"type":["string","null"],"description":"The maximum number of accrual units allowed. A null value signifies no maximum.","readOnly":true},"paid_at_termination":{"type":"boolean","description":"Whether the accrual balance is paid to the employee upon termination.","readOnly":true}}},"Termination":{"type":"object","description":"The representation of a termination in Gusto.","properties":{"uuid":{"type":"string","description":"The UUID of the termination object.","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."},"employee_uuid":{"type":"string","description":"The UUID of the employee to which this termination is attached.","readOnly":true},"active":{"type":"boolean","description":"Whether the employee's termination has gone into effect.","readOnly":true},"cancelable":{"type":"boolean","description":"Whether the employee's termination is cancelable. Cancelable is true if `run_termination_payroll` is false and `effective_date` is in the future.","readOnly":true},"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."}},"required":["uuid"],"x-examples":{"terminated_employee":{"uuid":"da441196-43a9-4d23-ad5d-f37ce6bb99c0","employee_uuid":"da441196-43a9-4d23-ad5d-f37ce6bb99c0","version":"d487dd0b55dfcacdd920ccbdaeafa351","active":true,"cancelable":false,"effective_date":"2024-01-15","run_termination_payroll":false},"cancelable_termination":{"uuid":"da441196-43a9-4d23-ad5d-f37ce6bb99c0","employee_uuid":"da441196-43a9-4d23-ad5d-f37ce6bb99c0","version":"d487dd0b55dfcacdd920ccbdaeafa351","active":false,"cancelable":true,"effective_date":"2024-06-15","run_termination_payroll":false}}},"Garnishment":{"description":"Garnishments, or employee deductions, are fixed amounts or percentages deducted from an employee’s pay. They can be deducted a specific number of times or on a recurring basis. Garnishments can also have maximum deductions on a yearly or per-pay-period bases. Common uses for garnishments are court-ordered payments for child support or back taxes. Some companies provide loans to their employees that are repaid via garnishments.","type":"object","properties":{"uuid":{"type":"string","description":"The UUID of the garnishment in Gusto.","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."},"employee_uuid":{"type":"string","description":"The UUID of the employee to which this garnishment belongs.","readOnly":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\"."},"description":{"type":"string","readOnly":false,"description":"The description of the garnishment."},"court_ordered":{"type":"boolean","readOnly":false,"description":"Whether the garnishment is court ordered."},"times":{"type":["integer","null"],"readOnly":false,"default":null,"description":"The number of times to apply the garnishment. Ignored if recurring is true."},"recurring":{"type":"boolean","readOnly":false,"default":false,"description":"Whether the garnishment should recur indefinitely."},"annual_maximum":{"format":"float","readOnly":false,"default":null,"description":"The maximum deduction per annum. A null value indicates no maximum. Represented as a float, e.g. \"200.00\".","type":["string","null"]},"total_amount":{"type":["string","null"],"format":"float","readOnly":false,"default":null,"description":"A maximum total deduction for the lifetime of this garnishment. A null value indicates no maximum."},"pay_period_maximum":{"type":["string","null"],"format":"float","default":null,"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","readOnly":false,"default":false,"description":"Whether the amount should be treated as a percentage to be deducted per pay period."},"garnishment_type":{"anyOf":[{"type":"string","enum":["child_support","federal_tax_lien","state_tax_lien","student_loan","creditor_garnishment","federal_loan","other_garnishment"]},{"type":"null"}],"description":"The specific type of garnishment for court ordered garnishments."},"child_support":{"$ref":"#/components/schemas/Garnishment-Child-Support"}},"required":["uuid"],"x-examples":{"Example":{"uuid":"4c7841a2-1363-497e-bc0f-664703c7484f","version":"52b7c567242cb7452e89ba2bc02cb476","employee_uuid":"a6b53294-f871-4db2-bbd4-8c3d1fe56440","active":true,"amount":"8.00","description":"Company loan to employee","court_ordered":false,"times":5,"recurring":false,"annual_maximum":null,"total_amount":null,"pay_period_maximum":"100.00","deduct_as_percentage":true,"garnishment_type":null,"child_support":null},"Create-Example":{"uuid":"4c7841a2-1363-497e-bc0f-664703c7484f","version":"52b7c567242cb7452e89ba2bc02cb476","employee_uuid":"a6b53294-f871-4db2-bbd4-8c3d1fe56440","active":true,"amount":"150.00","description":"Back taxes","court_ordered":true,"times":null,"recurring":true,"annual_maximum":null,"total_amount":null,"pay_period_maximum":null,"deduct_as_percentage":false,"garnishment_type":null,"child_support":null},"Child-Support-Example":{"uuid":"4c7841a2-1363-497e-bc0f-664703c7481a","version":"52b7c567242cb7452e89ba2bc02cb383","employee_uuid":"a6b53294-f871-4db2-bbd4-8c3d1fe56440","active":true,"amount":"40.00","description":"Child support - AZ28319","court_ordered":true,"times":null,"recurring":true,"annual_maximum":null,"total_amount":null,"pay_period_maximum":"400.00","deduct_as_percentage":true,"garnishment_type":"child_support","child_support":{"state":"AZ","payment_period":"Monthly","case_number":"AZ28319","order_number":null,"remittance_number":null,"fips_code":"04000"}},"Garnishment-List":[{"uuid":"4c7841a2-1363-497e-bc0f-664703c7484f","version":"52b7c567242cb7452e89ba2bc02cb476","employee_uuid":"a6b53294-f871-4db2-bbd4-8c3d1fe56440","active":true,"amount":"8.00","description":"Company loan to employee","court_ordered":false,"times":5,"recurring":false,"annual_maximum":null,"total_amount":null,"pay_period_maximum":"100.00","deduct_as_percentage":true,"garnishment_type":null,"child_support":null},{"uuid":"4c7841a2-1363-497e-bc0f-664703c7481a","version":"52b7c567242cb7452e89ba2bc02cb383","employee_uuid":"a6b53294-f871-4db2-bbd4-8c3d1fe56440","active":true,"amount":"40.00","description":"Child support - AZ28319","court_ordered":true,"times":null,"recurring":true,"annual_maximum":null,"total_amount":null,"pay_period_maximum":"400.00","deduct_as_percentage":true,"garnishment_type":"child_support","child_support":{"state":"AZ","payment_period":"Monthly","case_number":"AZ28319","order_number":null,"remittance_number":null,"fips_code":"04000"}}]}},"Garnishment-Request-Base":{"type":"object","description":"Shared request body properties for creating or updating a garnishment.","properties":{"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\"."},"description":{"type":"string","readOnly":false,"description":"The description of the garnishment."},"court_ordered":{"type":"boolean","readOnly":false,"description":"Whether the garnishment is court ordered."},"garnishment_type":{"description":"The specific type of garnishment for court ordered garnishments.","anyOf":[{"type":"string","enum":["child_support","federal_tax_lien","state_tax_lien","student_loan","creditor_garnishment","federal_loan","other_garnishment"]},{"type":"null"}],"readOnly":false},"times":{"type":["integer","null"],"readOnly":false,"default":null,"description":"The number of times to apply the garnishment. Ignored if recurring is true."},"recurring":{"type":"boolean","readOnly":false,"default":false,"description":"Whether the garnishment should recur indefinitely."},"annual_maximum":{"format":"float","readOnly":false,"default":null,"type":["string","null"],"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","null"],"format":"float","default":null,"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","readOnly":false,"default":false,"description":"Whether the amount should be treated as a percentage to be deducted per pay period."},"total_amount":{"type":["string","null"],"format":"float","readOnly":false,"description":"A maximum total deduction for the lifetime of this garnishment. A null value indicates no maximum."},"child_support":{"$ref":"#/components/schemas/Garnishment-Child-Support"}},"x-examples":{"Example":{"amount":"50.00","annual_maximum":"2500.09","recurring":true},"Deactivate-Example":{"active":false},"Child-Support-Example":{"amount":"40","child_support":{"case_number":"ZZZ999"}}}},"Garnishment-Request":{"description":"Request body for creating a garnishment.","allOf":[{"$ref":"#/components/schemas/Garnishment-Request-Base"},{"type":"object","required":["amount","court_ordered"]}],"x-examples":{"Example":{"amount":"150.00","description":"Back taxes","court_ordered":true,"recurring":true,"deduct_as_percentage":false},"Child-Support-Example":{"court_ordered":true,"garnishment_type":"child_support","amount":"40","recurring":true,"deduct_as_percentage":true,"pay_period_maximum":"500.00","child_support":{"state":"FL","fips_code":"12011","payment_period":"Monthly","case_number":"CS1234"}}}},"Update-Garnishment-Request":{"description":"Request body for updating a garnishment.","allOf":[{"$ref":"#/components/schemas/Garnishment-Request-Base"},{"$ref":"#/components/schemas/Versionable-Required"}]},"Garnishment-Child-Support":{"description":"Additional child support order details","type":["object","null"],"properties":{"state":{"type":"string","readOnly":false,"description":"The two letter state abbreviation for the state issuing the child support order. Agency data is available in the `GET /v1/garnishments/child_support` API."},"payment_period":{"type":"string","readOnly":false,"enum":["Every week","Every other week","Twice per month","Monthly"],"description":"How often the agency collects the withholding amount. e.g. $500 monthly -> `Monthly`."},"fips_code":{"type":"string","description":"The FIPS code associated with the state or county agency issuing the child support order. Agency data is available in the `GET /v1/garnishments/child_support` API.","nullable":false,"readOnly":false},"case_number":{"type":["string","null"],"readOnly":false,"description":"Child Support Enforcement Case Number associated with this child support obligation - required for most states. Agency specific requirements are available in the `GET /v1/garnishments/child_support` API."},"order_number":{"type":["string","null"],"readOnly":false,"description":"Order Identifier or Order ID associated with this child support obligation - required for some states. Agency specific requirements are available in the `GET /v1/garnishments/child_support` API."},"remittance_number":{"type":["string","null"],"readOnly":false,"description":"Child Support Enforcement Remittance ID associated with this child support obligation - required for some states. Agency specific requirements are available in the `GET /v1/garnishments/child_support` API."}}},"Employee-Custom-Field":{"type":"object","description":"A custom field of an employee","properties":{"id":{"type":"string"},"company_custom_field_id":{"type":"string","description":"This is the id of the response object from when you get the company custom fields"},"name":{"type":"string"},"type":{"$ref":"#/components/schemas/Custom-Field-Type"},"description":{"type":["string","null"]},"value":{"type":"string"},"selection_options":{"type":["array","null"],"description":"An array of options for fields of type radio. Otherwise, null.","items":{"type":"string"}}},"required":["id","company_custom_field_id","name","type","value"],"x-examples":{"example_text_field":{"id":"ee515986-f3ca-49da-b576-2691b95262f9","company_custom_field_id":"ea7e5d57-6abb-47d7-b654-347c142886c0","name":"employee_level","description":"Employee Level","type":"text","value":"2","selection_options":null},"example_radio_field":{"id":"3796e08d-c2e3-434c-b4de-4ce1893e7b59","company_custom_field_id":"024ec137-6c92-43a3-b061-14a9720531d6","name":"favorite fruit","description":"Which is your favorite fruit?","type":"radio","value":"apple","selection_options":["apple","banana","orange"]}}},"Employee-Custom-Field-List":{"type":"object","description":"A list of an employee's custom fields","properties":{"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/Employee-Custom-Field"}}},"x-examples":{"example":{"custom_fields":[{"id":"ee515986-f3ca-49da-b576-2691b95262f9","company_custom_field_id":"ea7e5d57-6abb-47d7-b654-347c142886c0","name":"employee_level","description":"Employee Level","type":"text","value":"2","selection_options":null},{"id":"3796e08d-c2e3-434c-b4de-4ce1893e7b59","company_custom_field_id":"024ec137-6c92-43a3-b061-14a9720531d6","name":"favorite fruit","description":"Which is your favorite fruit?","type":"radio","value":"apple","selection_options":["apple","banana","orange"]}]}}},"Custom-Field-Type":{"type":"string","description":"Input type for the custom field.","enum":["text","currency","number","date","radio"]},"Employment-History-List":{"type":"array","x-examples":{"success_status":[{"hire_date":"2015-06-09","termination_date":"2025-05-09","file_new_hire_report":false,"two_percent_shareholder":false,"employment_status":"full_time"}]},"items":{"description":"The representation of an employee's individual employements.","type":"object","properties":{"hire_date":{"type":"string","description":"The employee's start day of work for an employment."},"termination_date":{"type":["string","null"],"description":"The employee's last day of work for an employment."},"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."},"employment_status":{"type":"string","description":"The employee's employment status. Supplying an invalid option will set the employment_status to *not_set*.","enum":["part_time","full_time","part_time_eligible","variable","seasonal - not_set"]}}}},"Employee-Onboarding-Status":{"description":"The representation of an employee's onboarding status.","type":"object","title":"Employee-Onboarding-Status","x-examples":{"success_status":{"uuid":"8351cf2a-17cb-49e3-94a7-9986dcb11e84","onboarding_status":"onboarding_completed","onboarding_steps":[{"title":"Personal details","id":"personal_details","required":true,"completed":true,"requirements":[]},{"title":"Enter compensation details","id":"compensation_details","required":true,"completed":true,"requirements":[]},{"title":"Add work address","id":"add_work_address","required":true,"completed":true,"requirements":[]},{"title":"Add home address","id":"add_home_address","required":true,"completed":true,"requirements":[]},{"title":"Enter federal tax withholdings","id":"federal_tax_setup","required":true,"completed":true,"requirements":[]},{"title":"Enter state tax information","id":"state_tax_setup","required":true,"completed":false,"requirements":["add_work_address","add_home_address"]},{"title":"Direct deposit setup","id":"direct_deposit_setup","required":false,"completed":true,"requirements":[]},{"title":"Employee form signing","id":"employee_form_signing","required":true,"completed":false,"requirements":["federal_tax_setup","state_tax_setup"]},{"title":"File new hire report","id":"file_new_hire_report","required":true,"completed":false,"requirements":["add_work_address"]}],"blockers":[]}},"properties":{"uuid":{"type":"string","description":"Unique identifier for this employee."},"onboarding_status":{"type":"string","description":"One of the \"onboarding_status\" enum values."},"onboarding_steps":{"type":"array","description":"List of steps required to onboard an employee.","items":{"title":"Onboarding step","type":"object","properties":{"title":{"type":"string","description":"User-friendly description of the onboarding step."},"id":{"type":"string","description":"String identifier for 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","description":"A list of onboarding steps required to begin this step.","items":{"type":"string"}}}}},"blockers":{"type":"array","description":"Validation issues that should be resolved before this employee's onboarding is complete. Each entry identifies an affected field, a category describing the type of problem, and a human-readable message.\n\nSupported categories:\n\n- `duplicate_value`: Another employee in the same company already has this value. To resolve, cancel this onboarding and initiate a rehire if it's a returning employee, or contact support to investigate the conflict.\n\nThis list may grow over time as new validation rules are added.\n","items":{"type":"object","properties":{"field":{"type":"string","enum":["ssn"],"description":"The employee field affected."},"category":{"type":"string","enum":["duplicate_value"],"description":"Category of the blocker. See the array-level description for resolution guidance."},"message":{"type":"string","description":"Human-readable description of the blocker."}}}}},"required":["uuid"]},"Flsa-Status-Type":{"type":"string","enum":["Exempt","Salaried Nonexempt","Nonexempt","Owner","Commission Only Exempt","Commission Only Nonexempt"],"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. "},"Employee-Pay-Stubs-List":{"type":"array","x-examples":{"success_status":[{"uuid":"d2cec746-caee-464a-bcaf-00d93f7049c9","check_date":"2023-11-24","gross_pay":"880.0","net_pay":"541.02","payroll_uuid":"a039cafb-745e-4af4-bf1e-935a86fc18e0","check_amount":"500.2","payment_method":"Direct Deposit"}]},"items":{"description":"The representation of an employee pay stub information.","type":"object","properties":{"uuid":{"type":"string","description":"The UUID of the employee pay stub.","readOnly":true},"check_date":{"type":"string","description":"The check date of the pay stub.","readOnly":true},"gross_pay":{"type":"string","description":"The gross pay amount for the pay stub.","readOnly":true},"net_pay":{"type":"string","description":"The net pay amount for the pay stub.","readOnly":true},"payroll_uuid":{"type":"string","description":"A unique identifier of the payroll to which the pay stub belongs.","readOnly":true},"check_amount":{"type":"string","description":"The check amount for the pay stub.","readOnly":true},"payment_method":{"type":"string","description":"The payment method for the pay stub.","enum":["Direct Deposit","Check"],"readOnly":true}},"x-tags":["Payrolls"],"required":["uuid"]}},"Company-Address":{"description":"The representation of a company's address in Gusto.","type":"object","properties":{"street_1":{"type":"string","readOnly":false},"street_2":{"type":["string","null"],"readOnly":false},"city":{"type":"string","readOnly":false},"state":{"type":"string","readOnly":false},"zip":{"type":"string","readOnly":false},"country":{"type":"string","readOnly":false,"default":"USA"},"inactive":{"type":"boolean","description":"The status of the location. Inactive locations have been deleted, but may still have historical data associated with them.","readOnly":true},"active":{"type":"boolean","description":"The status of the location. Inactive locations have been deleted, but may still have historical data associated with them.","readOnly":true}}},"Employee-Work-Addresses-List":{"type":"array","x-examples":{"success_status":[{"uuid":"080b6254-ce7c-411f-9f7d-5a3ce3c51154","employee_uuid":"6747692e-d2c8-4472-9c5e-183c65404fbf","location_uuid":"9ccfade8-82ee-490c-8711-5c0787bccde8","effective_date":"2021-01-01","active":false,"version":"3097e9d0efb09ba2e00a8988a93b3091","street_1":"91678 Farrell Meadow","street_2":"Apt. 835","city":"Phoenix","state":"AZ","zip":"85016","country":"USA"},{"uuid":"35d62f15-75da-45aa-9c97-adc57342b925","employee_uuid":"6747692e-d2c8-4472-9c5e-183c65404fbf","location_uuid":"10330fe8-36ef-4713-aa59-9f8a432abd13","effective_date":"2022-01-01","active":false,"version":"5f48ce54afed81bb11dd89461bd0e214","street_1":"800 Adolfo Gardens","street_2":"Suite 419","city":"Bremen","state":"AL","zip":"35033","country":"USA"},{"uuid":"3f3ceaba-6b57-4039-a31a-0004bef83c6f","employee_uuid":"6747692e-d2c8-4472-9c5e-183c65404fbf","location_uuid":"98383e91-c67d-4b69-a617-5a57f91da48c","effective_date":"2023-01-01","active":true,"version":"a8a78c851337676137e22caf56ffe5b5","street_1":"2216 Icie Villages","street_2":"Apt. 798","city":"Big Delta","state":"AK","zip":"99737","country":"USA"}]},"items":{"$ref":"#/components/schemas/Employee-Work-Address"}},"Employee-Work-Address":{"type":"object","x-examples":{"success_status":{"uuid":"64ee5fd7-3eb2-4083-883c-95e93e181cc8","employee_uuid":"d773461f-848a-40a1-8f09-b2ee4249d5c7","location_uuid":"733ab2af-9510-408f-8d20-09196967174f","effective_date":"2020-01-31","active":true,"version":"3879823d440f3a3215d129ac73c58966","street_1":"977 Marks Viaduct","street_2":"Apt. 958","city":"Pink Hill","state":"NC","zip":"28572","country":"USA"}},"properties":{"uuid":{"type":"string","readOnly":true,"description":"The unique identifier of this work address."},"effective_date":{"type":"string","description":"The date the employee began working at this location."},"active":{"type":"boolean","readOnly":true,"description":"Signifies if this address is the active work address for the current date"},"location_uuid":{"type":"string","description":"UUID reference to the company location for this work address."},"employee_uuid":{"type":"string","description":"UUID reference to the employee for this work address."},"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","null"],"readOnly":true},"city":{"type":"string","readOnly":true},"state":{"type":"string","readOnly":true},"zip":{"type":"string","readOnly":true},"country":{"type":"string","readOnly":true,"default":"USA"}},"required":["uuid","version"]},"Employee-Address-List":{"type":"array","x-examples":{"success_status":[{"uuid":"d6b7472f-bb55-41ca-a55c-9adbd3c64e09","version":"7eee445be93fc50fd3cbb55b8d943fb3","employee_uuid":"d1a166b4-79b4-413f-b067-27534ec59ecd","street_1":"3121 Milky Way","street_2":"","city":"San Francisco","state":"CA","zip":"94107","country":"USA","active":false,"effective_date":"2024-06-09","courtesy_withholding":false},{"uuid":"1b59a593-d324-4d97-9296-99ecc95f81d1","version":"5147ad755821c4ba3dbc3afa1055ff4d","employee_uuid":"d1a166b4-79b4-413f-b067-27534ec59ecd","street_1":"3624 Victoria Ln","street_2":"","city":"Cincinnati","state":"OH","zip":"45208","country":"USA","active":true,"effective_date":"2025-05-26","courtesy_withholding":false},{"uuid":"69489b54-976d-4027-8b51-702e5c8c62d3","version":"f0765fa5a85f62723320763494a481a6","employee_uuid":"d1a166b4-79b4-413f-b067-27534ec59ecd","street_1":"Main st.","street_2":"","city":"New York","state":"NY","zip":"10011","country":"USA","active":false,"effective_date":"2025-07-09","courtesy_withholding":false}]},"items":{"$ref":"#/components/schemas/Employee-Address"}},"Employee-Address":{"type":"object","x-examples":{"success_status":{"uuid":"700af712-62ba-4dff-824f-97a3c6fda416","version":"6c3c23e4cc840bd3f1416f72b5380eff","employee_uuid":"78d20691-f1b4-4f74-bc4c-1d4db0099b00","street_1":"3121 Milky Way","street_2":"","city":"San Francisco","state":"CA","zip":"94107","country":"USA","active":true,"effective_date":"1970-01-01","courtesy_withholding":false}},"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."},"street_1":{"type":"string","readOnly":false},"street_2":{"type":["string","null"],"readOnly":false},"city":{"type":"string","readOnly":false},"state":{"type":"string","readOnly":false},"zip":{"type":"string","readOnly":false},"country":{"type":"string","readOnly":false,"default":"USA"},"active":{"type":"boolean","description":"The status of the location. Inactive locations have been deleted, but may still have historical data associated with them.","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."}},"required":["uuid","version"]},"Employee-Section603-High-Earner-Status-List":{"type":"array","x-examples":{"success_status":[{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","effective_year":2026,"is_high_earner":false},{"id":"550e8400-e29b-41d4-a716-446655440000","effective_year":2027,"is_high_earner":true}]},"items":{"$ref":"#/components/schemas/Employee-Section603-High-Earner-Status"}},"Employee-Section603-High-Earner-Status":{"type":"object","description":"The representation of an employee's Section 603 high earner status for a specific year. Section 603 of the SECURE 2.0 Act requires employees aged 50 or older whose prior-year FICA wages exceed the IRS threshold to have their catch-up contributions to pre-tax retirement benefits designated as post-tax contributions.","x-examples":{"success_status":{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","effective_year":2026,"is_high_earner":false}},"properties":{"id":{"type":"string","description":"The unique identifier of the Section 603 high earner status record","readOnly":true},"effective_year":{"type":"integer","description":"The year for which this high earner status applies","readOnly":true},"is_high_earner":{"type":["boolean","null"],"description":"Whether the employee is classified as a high earner for Section 603 purposes. Can be null if the status has not yet been determined.","readOnly":true}},"required":["id","effective_year","is_high_earner"]},"Employee-Section603-High-Earner-Status-Create-Request":{"type":"object","description":"Request body for creating an employee's Section 603 high earner status","properties":{"effective_year":{"type":"integer","description":"The year for which this high earner status applies","example":2026},"is_high_earner":{"type":"boolean","description":"Whether the employee is classified as a high earner for Section 603 purposes","example":true}},"required":["effective_year","is_high_earner"]},"Employee-Section603-High-Earner-Status-Update-Request":{"type":"object","description":"Request body for updating an employee's Section 603 high earner status","properties":{"is_high_earner":{"type":"boolean","description":"Whether the employee is classified as a high earner for Section 603 purposes","example":true}},"required":["is_high_earner"]},"Employee-State-Taxes-List":{"type":"array","x-examples":{"success_status":[{"uuid":"287d2c61-1d18-4126-8a4a-9cb29bbb6dac","employee_uuid":"c963cb99-fe1c-4aa8-9d48-1ad211ad396f","state":"CA","file_new_hire_report":false,"is_work_state":true,"questions":[{"is_question_for_admin_only":false,"label":"Filing Status","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='0' href='https://www.ftb.ca.gov/file/personal/filing-status/index.html'>CA Filing Status explanation</a>.\n","key":"filing_status","input_question_format":{"type":"Select","options":[{"value":"S","label":"Single"},{"value":"M","label":"Married one income"},{"value":"MD","label":"Married dual income"},{"value":"H","label":"Head of Household"},{"value":"E","label":"Do Not Withhold"}]},"answers":[{"value":"M","valid_from":"2010-01-01","valid_up_to":null}]},{"is_question_for_admin_only":false,"label":"Withholding Allowance","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='0' href='https://www.edd.ca.gov/pdf_pub_ctr/de4.pdf'>CA DE-4 form</a> to calculate the value manually.\n","key":"withholding_allowance","input_question_format":{"type":"Number"},"answers":[{"value":1,"valid_from":"2010-01-01","valid_up_to":null}]},{"is_question_for_admin_only":false,"label":"Additional Withholding","description":"You can withhold an additional amount of California income taxes here.","key":"additional_withholding","input_question_format":{"type":"Currency"},"answers":[{"value":"0.0","valid_from":"2010-01-01","valid_up_to":null}]},{"is_question_for_admin_only":true,"label":"File a New Hire Report?","description":"State law requires you to file a new hire report within 20 days of hiring or re-hiring an employee.","key":"file_new_hire_report","input_question_format":{"type":"Select","options":[{"value":true,"label":"Yes, file the state new hire report for me."},{"value":false,"label":"No, I have already filed."}]},"answers":[{"value":false,"valid_from":"2010-01-01","valid_up_to":null}]}]}]},"items":{"type":"object","properties":{"uuid":{"type":"string","description":"The uuid of the employee state field."},"employee_uuid":{"type":"string","description":"The employee's uuid"},"state":{"type":"string","description":"Two letter US state abbreviation"},"file_new_hire_report":{"type":["boolean","null"]},"is_work_state":{"type":"boolean"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/Employee-State-Tax-Question"}}}},"required":["uuid","employee_uuid","state","questions"]},"Employee-State-Tax-Question":{"type":"object","properties":{"label":{"type":"string","description":"A short title for the question"},"description":{"type":["string","null"],"description":"An explaination of the question - this may contain inline html formatted links."},"key":{"type":"string","description":"A unique identifier of the question (for the given state) - used for updating the answer."},"is_question_for_admin_only":{"type":"boolean"},"input_question_format":{"$ref":"#/components/schemas/Employee-State-Tax-Input-Question-Format"},"answers":{"type":"array","items":{"$ref":"#/components/schemas/Employee-State-Tax-Answer"}}},"required":["label","description","key","input_question_format","answers","is_question_for_admin_only"]},"Employee-State-Tax-Input-Question-Format":{"type":"object","properties":{"type":{"type":"string","description":"Describes the type of question - Text, Number, Select, Currency, Date"},"options":{"type":"array","uniqueItems":true,"description":"For \"Select\" type questions, the allowed values and display labels.","items":{"type":"object","properties":{"value":{"description":"An allowed value to answer the question","oneOf":[{"type":"string"},{"type":"boolean"},{"type":"number"}]},"label":{"type":"string","description":"A display label that corresponds to the answer value"}},"required":["label"]}}},"required":["type"]},"Employee-State-Tax-Answer":{"type":"object","properties":{"value":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"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":{"type":["string","null"],"description":"The effective end date of the answer - currently always null."}}},"Employee-State-Taxes-Request":{"type":"object","properties":{"states":{"type":"array","uniqueItems":true,"items":{"type":"object","properties":{"state":{"type":"string"},"questions":{"type":"array","uniqueItems":true,"items":{"type":"object","properties":{"key":{"type":"string"},"answers":{"type":"array","uniqueItems":true,"items":{"type":"object","properties":{"value":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"valid_from":{"type":"string"},"valid_up_to":{"type":["string","null"]}},"required":["value","valid_from"]}}},"required":["key"]}}},"required":["state"]}}},"required":["states"]},"Employee-Payment-Details-List":{"type":"array","description":"A list of employee payment details.","x-examples":{"success_status":[{"employee_uuid":"e2c4c0ce-2986-48b9-86cf-ec27f6ed9a36","first_name":"Soren","last_name":"Kierkegaard","payment_method":"Direct Deposit","split_by":"Percentage","splits":[{"bank_account_uuid":"1531e824-8d9e-4bd8-9f90-0d04608125d7","name":"Primary Checking","hidden_account_number":"XXXX1207","encrypted_account_number":"mbNLVOm7psP16ocqXso5ZtzOXBrA-5Q-.zarrdLBmyYDDK4kCkF2reKtzx8udK8iDabtW","routing_number":"055003201","account_type":"Checking","priority":1,"split_amount":100}]},{"employee_uuid":"6b7e4b51-2e2d-4b54-9f37-7b9d0e9fa5d2","first_name":"Autumn","last_name":"Connelly","payment_method":"Check","split_by":null,"splits":null}]},"items":{"type":"object","properties":{"employee_uuid":{"type":"string","description":"The UUID of the employee.","readOnly":true},"first_name":{"type":"string","description":"The legal first name of the employee.","readOnly":true},"last_name":{"type":"string","description":"The last name of the employee.","readOnly":true},"payment_method":{"type":"string","enum":["Direct Deposit","Check"],"description":"The type of payment method.","readOnly":true},"split_by":{"anyOf":[{"type":"string","enum":["Amount","Percentage"]},{"type":"null"}],"description":"How the payment is split. This field is applicable when `payment_method` is \"Direct Deposit\". If `split_by` is Percentage, then the split amounts must add up to exactly 100. If `split_by` is Amount, the last split amount must be `null` to capture the remainder.","readOnly":true},"splits":{"type":["array","null"],"description":"An array of payment splits. This field is applicable when `payment_method` is \"Direct Deposit\".","items":{"type":"object","properties":{"bank_account_uuid":{"type":"string","description":"The UUID of the bank account."},"name":{"type":"string","description":"The name of the bank account."},"hidden_account_number":{"type":"string","description":"An obfuscated version of the account number which can be used for display purposes."},"encrypted_account_number":{"type":["string","null"],"description":"Ciphertext containing the full bank account number, which must be decrypted using a key provided by Gusto. Only visible with the `employee_payment_methods:read:account_number` scope."},"routing_number":{"type":"string","description":"The routing number of the bank account."},"account_type":{"type":"string","description":"The bank account type (e.g., \"Checking\" or \"Savings\")."},"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":["number","null"],"description":"If `split_by` is 'Amount', this is in cents (e.g., 500 for $5.00) and exactly one account must have a `split_amount` of `null` to capture the remainder. If `split_by` is 'Percentage', this is the percentage value (e.g., 60 for 60%)."}}},"readOnly":true}}}},"Contractor-Payment-Details-List":{"type":"array","x-examples":{"success_status":[{"contractor_uuid":"e3d9487a-4ecb-49a3-b6ff-cf03ba7278b6","first_name":"Yael","last_name":"Kuvalis","payment_method":"Check","split_by":null,"splits":null},{"contractor_uuid":"577b6307-66e9-4926-a769-91f5c8b578aa","first_name":"Autumn","last_name":"Connelly","payment_method":"Direct Deposit","split_by":"Percentage","splits":[{"bank_account_uuid":"0aca4500-8ba4-48fc-adce-677fe7926b7b","name":"Cayman Island Checking","hidden_account_number":"XXXX1545","account_number":null,"encrypted_account_number":null,"routing_number":"055003201","priority":1,"split_amount":100,"account_type":"Checking"}]}]},"items":{"type":"object","properties":{"contractor_uuid":{"type":"string"},"payment_method":{"type":"string","enum":["Direct Deposit","Check"]},"first_name":{"type":"string"},"last_name":{"type":"string"},"split_by":{"anyOf":[{"type":"string","enum":["Amount","Percentage"]},{"type":"null"}],"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 amount represents cents and the last split amount must be `null` to capture the remainder."},"splits":{"type":["array","null"],"items":{"type":"object","properties":{"bank_account_uuid":{"type":"string"},"name":{"type":"string"},"hidden_account_number":{"type":"string","description":"An obfuscated version of the account number which can be used for display purposes."},"encrypted_account_number":{"type":["string","null"],"description":"Ciphertext containing the full bank account number, which must be decrypted using a key provided by Gusto. Only visible with the `contractor_payment_methods:read:account_number` scope."},"routing_number":{"type":"string"},"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":["number","null"],"description":"If `split_by` is 'Amount', this is in cents (e.g., 500 for $5.00) and exactly one account must have a `split_amount` of `null` to capture the remainder. If `split_by` is 'Percentage', this is the percentage value (e.g., 60 for 60%)."},"account_type":{"type":"string"}}}}}}},"Notifications-List":{"type":"array","x-examples":{"success_status":[{"uuid":"d053ee2a-a80f-4a61-8bf8-6122c1f954dd","company_uuid":"46c8329d-ebd1-49ba-878c-810b481a34c9","category":"company_setup.missing_mandatory_sick_time_policy","title":"Set up a sick time off policy","message":"At least one company work location requires businesses to provide a sick time off policy.","actionable":true,"can_block_payroll":false,"published_at":"2025-06-09T13:42:59.000-07:00","due_at":null,"status":"open","resources":[],"template_variables":{}},{"uuid":"2edd148b-c4c3-4cda-b3e1-72b87399e6c8","company_uuid":"46c8329d-ebd1-49ba-878c-810b481a34c9","category":"bank_error.compensation_credit_failure","title":"Unable to deposit funds to Donn Cormier","message":"We were unable to deposit a recent paycheck to Donn’s bank account, so these funds of $100.00 will be returned to Luettgen-Gusikowski’s bank account. Once the funds are received, the payment should be made directly to Donn.","actionable":true,"can_block_payroll":false,"published_at":"2025-06-09T13:43:00.000-07:00","due_at":null,"status":"open","resources":[{"entity_type":"Employee","entity_uuid":"66a27bb8-be5b-42e5-82b8-b2d0044a7f9e"}],"template_variables":{"beneficiary_name":"Donn Cormier","amount":"$100.00","company_name":"Luettgen-Gusikowski"}}],"with_transactional_mailer_notification":[{"uuid":"d053ee2a-a80f-4a61-8bf8-6122c1f954dd","company_uuid":"46c8329d-ebd1-49ba-878c-810b481a34c9","category":"company_setup.missing_mandatory_sick_time_policy","title":"Set up a sick time off policy","message":"At least one company work location requires businesses to provide a sick time off policy.","actionable":true,"can_block_payroll":false,"published_at":"2025-06-09T13:42:59.000-07:00","due_at":null,"status":"open","resources":[],"template_variables":{}},{"uuid":"3f16b3e4-3c0e-4f92-9c1d-9e9dc9d1f7a2","company_uuid":"46c8329d-ebd1-49ba-878c-810b481a34c9","category":"notification.taxops.created","title":"Confirm or amend the tax filing that was filed outside of payroll","message":"We recently attempted to file Acme Consulting's Q2 2025 tax returns. However, California EDD rejected the filing because it has already been completed by someone else. Please confirm that the already-filed return matches the records on file. If the return is incorrect, you will need to amend it directly with the agency. We cannot amend returns we did not originally file. In the future, ensure this return is not filed outside of payroll.","actionable":true,"can_block_payroll":false,"published_at":"2025-06-09T13:44:00.000-07:00","due_at":null,"status":"open","resources":[{"entity_type":"Employee","entity_uuid":"66a27bb8-be5b-42e5-82b8-b2d0044a7f9e"}],"template_variables":{"company_name":"Acme Consulting","quarter":"Q2 2025","agency_list":"California EDD"}}]},"items":{"$ref":"#/components/schemas/Notification"}},"Notification":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier of a notification."},"company_uuid":{"type":"string","description":"Unique identifier of the company to which the notification belongs."},"title":{"type":"string","description":"The title of the notification. This highlights the actionable component of the notification."},"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."},"status":{"type":"string","description":"Represents the notification's status as managed by our system. It is updated based on observable system events and internal business logic, and does not reflect resolution steps taken outside our system. This field is read-only and cannot be modified via the API.","enum":["open","resolved","expired"]},"category":{"type":"string","description":"The notification's category."},"actionable":{"type":"boolean","description":"Indicates whether a notification requires action or not. If false, the notification provides critical information only."},"can_block_payroll":{"type":"boolean","description":"Indicates whether a notification may block ability to run payroll. If true, we suggest that these notifications are prioritized to your end users."},"published_at":{"type":"string","description":"Timestamp of when the notification was published."},"due_at":{"type":["string","null"],"description":"Timestamp of when the notification is due. If the notification has no due date, this field will be null."},"template_variables":{"type":"object","description":"An object containing template variables used to render the notification. The structure of this object depends on the notification category. Each category defines a fixed set of variable names (keys), which are always present. The values of these variables can vary depending on the specific notification instance.","additionalProperties":{"type":"string"}},"resources":{"type":"array","description":"An array of entities relevant to the notification","items":{"type":"object","properties":{"entity_type":{"type":"string","description":"The type of entity being described.","enum":["BankAccount","Contractor","ContractorPayment","Employee","Payroll","PaySchedule","RecoveryCase","Signatory","Wire In Request"]},"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."}},"required":["entity_type","entity_uuid"]}}},"required":["uuid","company_uuid","title","message","category","actionable","status","published_at","due_at","resources","can_block_payroll"],"x-examples":{"notification_show":{"uuid":"7b1d0df1-6403-4a06-8768-c1dd7d24d27a","company_uuid":"88f7cca1-dcad-4d20-84db-7fb80303d69f","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.","status":"open","category":"information_request","actionable":true,"can_block_payroll":true,"published_at":"2022-01-01T00:00:00.000Z","due_at":"2022-02-01T00:00:00.000Z","template_variables":{"blocked_task":"Payroll"},"resources":[{"entity_type":"Employee","entity_uuid":"21b6f9ce-0ac4-4745-8d8a-127f8c0f00f2"}]},"transactional_mailer_notification_show":{"uuid":"3f16b3e4-3c0e-4f92-9c1d-9e9dc9d1f7a2","company_uuid":"88f7cca1-dcad-4d20-84db-7fb80303d69f","title":"Confirm or amend the tax filing that was filed outside of payroll","message":"We recently attempted to file Acme Consulting's Q2 2025 tax returns. However, California EDD rejected the filing because it has already been completed by someone else. Please confirm that the already-filed return matches the records on file. If the return is incorrect, you will need to amend it directly with the agency. We cannot amend returns we did not originally file. In the future, ensure this return is not filed outside of payroll.","status":"open","category":"notification.taxops.created","actionable":true,"can_block_payroll":false,"published_at":"2025-06-09T13:44:00.000-07:00","due_at":null,"template_variables":{"company_name":"Acme Consulting","quarter":"Q2 2025","agency_list":"California EDD"},"resources":[{"entity_type":"Employee","entity_uuid":"21b6f9ce-0ac4-4745-8d8a-127f8c0f00f2"}]}}},"Payroll-List":{"description":"A list of payrolls for a company.","type":"array","x-examples":{"success_status":[{"uuid":"3601a7a2-0562-4e4c-9559-20886658daac","payroll_uuid":"3601a7a2-0562-4e4c-9559-20886658daac","company_uuid":"b43e6012-bf6c-4752-b67b-5c8000595e0e","payroll_status_meta":{"cancellable":false,"expected_check_date":"2025-06-08","initial_check_date":"2025-06-27","expected_debit_time":"2025-06-12T23:00:00Z","payroll_late":false,"initial_debit_cutoff_time":"2025-06-12T23:00:00Z"},"off_cycle":false,"auto_payroll":false,"processed":true,"processed_date":"2025-06-11","calculated_at":"2025-06-11T19:40:51Z","pay_period":{"start_date":"2025-05-20","end_date":"2025-06-04","pay_schedule_uuid":"ded21d08-02d6-41cb-b211-8d8ca02f1c6a"},"check_date":"2025-06-08","external":false,"payroll_deadline":"2025-06-12T23:00:00Z","company_taxes":[],"created_at":"2025-06-11T19:40:51Z","partner_owned_disbursement":null}]},"items":{"$ref":"#/components/schemas/Payroll"}},"Payroll-Update":{"type":"object","properties":{"employee_compensations":{"type":"array","items":{"type":"object","description":"","properties":{"employee_uuid":{"type":"string","description":"The UUID of the employee."},"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."},"payment_method":{"type":"string","description":"The employee's compensation payment method. Invalid values will be ignored.","enum":["Direct Deposit","Check"]},"memo":{"type":"string","description":"Custom text that will be printed as a personal note to the employee on a paystub."},"fixed_compensations":{"type":"array","items":{"type":"object","description":"An array of fixed compensations for the employee. Fixed compensations include tips, bonuses, and one time reimbursements.","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","description":"The UUID of the job for the compensation."}}}},"hourly_compensations":{"type":"array","items":{"type":"object","description":"An array of hourly compensations for the employee. Hourly compensations include regular, overtime, and double overtime hours.","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":"string","description":"The UUIDs of the job for the compensation."}}}},"deductions":{"type":"array","items":{"type":"object","description":"An array of deductions for the employee.","properties":{"name":{"type":"string","description":"The name of the deduction."},"amount":{"type":"number","description":"The amount of the deduction for the pay period."},"amount_type":{"type":"string","description":"The amount type of the deduction for the pay period.","enum":["fixed","percent"]},"uuid":{"type":"string","description":"The UUID of the deduction. This parameter is optional and can be provided in order to update an existing deduction."}}}},"custom_withholdings":{"type":"object","description":"Optional per-payroll one-time custom withholdings for federal and/or state income tax.\nWhen provided, the supplied override takes precedence over any persistent withholding schedule for this run.\nThis field is in limited release; if your application does not have access, requests including it are silently ignored.\n","properties":{"federal":{"type":"object","description":"Federal one-time custom withholding override.","properties":{"override_type":{"type":"string","enum":["one_time"],"description":"Override mode. Only `one_time` is currently supported."},"amount":{"type":"string","description":"The amount to be withheld for this payroll."},"amount_type":{"type":"string","enum":["fixed","percent"],"description":"How to interpret the amount."}}},"state":{"type":"array","description":"State one-time custom withholding overrides, one entry per state field.","items":{"type":"object","properties":{"employee_state_field_uuid":{"type":"string","description":"The UUID of the EmployeeStateField this withholding applies to."},"override_type":{"type":"string","enum":["one_time"],"description":"Override mode. Only `one_time` is currently supported."},"amount":{"type":"string","description":"The amount to be withheld for this payroll."},"amount_type":{"type":"string","enum":["fixed","percent"],"description":"How to interpret the amount."}}}}}},"paid_time_off":{"type":"array","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.","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","null"],"description":"The outstanding hours paid upon termination. This field is only applicable for termination payrolls."}}}},"reimbursements":{"type":"array","description":"An array of reimbursements for the employee.","items":{"type":"object","properties":{"amount":{"type":"string","description":"The dollar amount of the reimbursement for the pay period."},"description":{"type":"string","description":"The description of the reimbursement. If not provided, the reimbursement will be unnamed."},"uuid":{"type":"string","description":"The UUID of an existing reimbursement. This parameter is optional and can be provided in order to update an existing reimbursement."}}}}}}},"withholding_pay_period":{"description":"The payment schedule tax rate the payroll is based on. Only relevant for off-cycle payrolls.","type":"string","enum":["Every week","Every other week","Twice per month","Monthly","Quarterly","Semiannually","Annually"]},"skip_regular_deductions":{"description":"Block regular deductions and contributions for this payroll. Only relevant for off-cycle payrolls.","type":"boolean"},"fixed_withholding_rate":{"description":"Enable taxes to be withheld at the IRS's required rate of 22% for federal income taxes. State income taxes will be taxed at the state's supplemental tax rate. Otherwise, we'll sum the entirety of the employee's wages and withhold taxes on the entire amount at the rate for regular wages. Only relevant for off-cycle payrolls.","type":"boolean"}},"required":["employee_compensations"]},"Payroll-Gross-Up-Request":{"type":"object","description":"Request body for calculating gross up amount","properties":{"employee_uuid":{"type":"string","description":"The UUID of the employee"},"net_pay":{"type":"string","format":"float","description":"Employee net earnings"}},"required":["employee_uuid","net_pay"]},"Payroll-Gross-Up-Response":{"type":"object","description":"Response containing the calculated gross up amount","x-examples":{"success_status":{"gross_up":"1234.56"}},"properties":{"gross_up":{"type":"string","format":"float","description":"Gross up earnings."}}},"Payroll-Calculate-Accruing-Time-Off-Hours-Request":{"type":"object","description":"Request body for calculating accruing time off hours","properties":{"regular_hours_worked":{"type":["string","null"],"format":"float","description":"Regular hours worked in this pay period"},"overtime_hours_worked":{"type":["string","null"],"format":"float","description":"Overtime hours worked in this pay period"},"double_overtime_hours_worked":{"type":["string","null"],"format":"float","description":"Double overtime hours worked in this pay period"},"pto_hours_used":{"type":["string","null"],"format":"float","description":"Paid time off hours used in this pay period"},"sick_hours_used":{"type":["string","null"],"format":"float","description":"Sick hours used in this pay period"}}},"Payroll-Calculate-Accruing-Time-Off-Hours-Response":{"type":"object","description":"Response containing the calculated accruing time off hours","x-examples":{"success_status":{"hours_earned":[{"time_off_policy_uuid":"7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f","hours":"3.0"},{"time_off_policy_uuid":"1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d","hours":"20.0"}]}},"properties":{"hours_earned":{"type":"array","description":"Accruing time off hours earned for each time off policy","items":{"type":"object","properties":{"time_off_policy_uuid":{"type":"string","description":"The UUID of the time off policy"},"hours":{"type":"string","format":"float","description":"Hours accrued during this pay period."}}}}},"required":["hours_earned"]},"Payroll":{"type":"object","x-examples":{"success_status":{"uuid":"b441a30b-2adb-489e-b7b7-9d094011a3f8","employee_compensations":[],"submission_blockers":[],"credit_blockers":[],"payroll_uuid":"b441a30b-2adb-489e-b7b7-9d094011a3f8","company_uuid":"9aa93530-43d5-484e-b608-33214109420d","off_cycle":false,"auto_payroll":false,"processed":true,"processed_date":"2025-06-16","calculated_at":"2025-06-16T16:58:03Z","pay_period":{"start_date":"2025-05-25","end_date":"2025-06-09","pay_schedule_uuid":"40ff5990-0191-4796-9717-32f7dd3e94d5"},"check_date":"2025-06-13","external":false,"payroll_deadline":"2025-06-17T23:00:00Z","totals":{"employee_bonuses":"0.00","employee_commissions":"0.00","employee_cash_tips":"0.00","employee_paycheck_tips":"0.00","additional_earnings":"0.00","owners_draw":"0.00","benefits":"0.00","check_amount":"0.00","child_support_debit":"0.00","company_debit":"0.00","deferred_payroll_taxes":"0.00","employee_benefits_deductions":"0.00","employee_taxes":"0.00","employer_taxes":"0.00","gross_pay":"0.00","imputed_pay":"0.00","net_pay":"0.00","net_pay_debit":"0.00","other_deductions":"0.00","reimbursement_debit":"0.00","reimbursements":"0.00","tax_debit":"0.00"},"payroll_status_meta":{"cancellable":false,"expected_check_date":"2025-06-13","initial_check_date":"2025-06-13","expected_debit_time":"2025-06-17T23:00:00Z","payroll_late":false,"initial_debit_cutoff_time":"2025-06-17T23:00:00Z"},"processing_request":{"status":"submit_success","errors":[]},"created_at":"2025-06-16T16:58:03Z","partner_owned_disbursement":null}},"properties":{"payroll_deadline":{"$ref":"#/components/schemas/Payroll-Deadline-Type"},"check_date":{"$ref":"#/components/schemas/Payroll-Check-Date-Type"},"processed":{"$ref":"#/components/schemas/Payroll-Processed-Type"},"processed_date":{"$ref":"#/components/schemas/Payroll-Processed-Date-Type"},"calculated_at":{"$ref":"#/components/schemas/Payroll-Calculated-At-Type"},"uuid":{"$ref":"#/components/schemas/Payroll-Payroll-Uuid-Type"},"payroll_uuid":{"$ref":"#/components/schemas/Payroll-Payroll-Uuid-Type"},"company_uuid":{"$ref":"#/components/schemas/Payroll-Company-Uuid-Type"},"off_cycle":{"$ref":"#/components/schemas/Payroll-Off-Cycle-Type"},"off_cycle_reason":{"$ref":"#/components/schemas/Off-Cycle-Reason-Type"},"auto_payroll":{"$ref":"#/components/schemas/Auto-Pilot-Type"},"external":{"$ref":"#/components/schemas/Payroll-External-Type"},"final_termination_payroll":{"$ref":"#/components/schemas/Payroll-Final-Termination-Payroll-Type"},"withholding_pay_period":{"$ref":"#/components/schemas/Payroll-Withholding-Pay-Period-Type"},"skip_regular_deductions":{"$ref":"#/components/schemas/Payroll-Skip-Regular-Deductions-Type"},"fixed_withholding_rate":{"$ref":"#/components/schemas/Payroll-Fixed-Withholding-Rate-Type"},"pay_period":{"$ref":"#/components/schemas/Payroll-Pay-Period-Type"},"payroll_status_meta":{"$ref":"#/components/schemas/Payroll-Payroll-Status-Meta-Type"},"totals":{"$ref":"#/components/schemas/Payroll-Totals-Type"},"company_taxes":{"$ref":"#/components/schemas/Payroll-Company-Taxes-Type"},"payroll_taxes":{"$ref":"#/components/schemas/Payroll-Taxes-Type"},"payment_speed_changed":{"$ref":"#/components/schemas/Payroll-Payment-Speed-Changed-Type"},"created_at":{"$ref":"#/components/schemas/Created-At-Type"},"submission_blockers":{"$ref":"#/components/schemas/Payroll-Submission-Blockers-Type"},"credit_blockers":{"$ref":"#/components/schemas/Payroll-Credit-Blockers-Type"},"processing_request":{"$ref":"#/components/schemas/Payroll-Processing-Request"},"partner_owned_disbursement":{"$ref":"#/components/schemas/Payroll-Partner-Owned-Disbursement-Type"}}},"Unprocessed-Payroll":{"type":"object","description":"A payroll that has been transitioned back to unprocessed state after cancellation.","x-examples":{"success_status":{"uuid":"b50e611d-8f3d-4f24-b001-46675f7b5777","employee_compensations":[],"payroll_uuid":"b50e611d-8f3d-4f24-b001-46675f7b5777","company_uuid":"6bf7807c-a5a0-4f4d-b2e7-3fbb4b2299fb","off_cycle":false,"auto_payroll":false,"processed":false,"processed_date":null,"calculated_at":null,"pay_period":{"start_date":"2021-02-01","end_date":"2021-02-15","pay_schedule_uuid":"00ebc4a4-ec88-4435-8f45-c505bb63e501"},"check_date":"2021-02-22","external":false,"payroll_deadline":"2021-02-18T22:00:00Z","created_at":"2022-02-01T22:00:00Z","partner_owned_disbursement":null}},"properties":{"payroll_deadline":{"$ref":"#/components/schemas/Payroll-Deadline-Type"},"check_date":{"$ref":"#/components/schemas/Payroll-Check-Date-Type"},"processed":{"$ref":"#/components/schemas/Payroll-Processed-Type"},"processed_date":{"$ref":"#/components/schemas/Payroll-Processed-Date-Type"},"calculated_at":{"$ref":"#/components/schemas/Payroll-Calculated-At-Type"},"uuid":{"$ref":"#/components/schemas/Payroll-Payroll-Uuid-Type"},"payroll_uuid":{"$ref":"#/components/schemas/Payroll-Payroll-Uuid-Type"},"company_uuid":{"$ref":"#/components/schemas/Payroll-Company-Uuid-Type"},"off_cycle":{"$ref":"#/components/schemas/Payroll-Off-Cycle-Type"},"off_cycle_reason":{"$ref":"#/components/schemas/Off-Cycle-Reason-Type"},"auto_payroll":{"$ref":"#/components/schemas/Auto-Pilot-Type"},"external":{"$ref":"#/components/schemas/Payroll-External-Type"},"pay_period":{"$ref":"#/components/schemas/Payroll-Pay-Period-Type"},"created_at":{"$ref":"#/components/schemas/Created-At-Type"},"partner_owned_disbursement":{"$ref":"#/components/schemas/Payroll-Partner-Owned-Disbursement-Type"}}},"Payroll-Partner-Owned-Disbursement-Type":{"type":["boolean","null"],"description":"Will money movement for the payroll be performed by the partner rather than by Gusto?"},"Payroll-Deadline-Type":{"type":"string","format":"date-time","description":"A timestamp that is the deadline for the payroll to be run in order for employees to be paid on time.  If payroll has not been run by the deadline, a prepare request will update both the check date and deadline to reflect the soonest employees can be paid and the deadline by which the payroll must be run in order for said check date to be met.","readOnly":true},"Payroll-Check-Date-Type":{"type":"string","description":"The date on which employees will be paid for the payroll.","readOnly":true},"Payroll-Processed-Type":{"type":"boolean","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.","readOnly":true},"Payroll-Processed-Date-Type":{"type":["string","null"],"description":"The date at which the payroll was processed. Null if the payroll isn't processed yet.","readOnly":true},"Payroll-Calculated-At-Type":{"type":["string","null"],"format":"date-time","description":"A timestamp of the last valid payroll calculation. Null if there isn't a valid calculation.","readOnly":true},"Payroll-Payroll-Uuid-Type":{"type":"string","description":"The UUID of the payroll.","readOnly":true},"Payroll-Company-Uuid-Type":{"type":"string","description":"The UUID of the company for the payroll.","readOnly":true},"Payroll-Off-Cycle-Type":{"type":"boolean","description":"Indicates whether the payroll is an off-cycle payroll","readOnly":true},"Off-Cycle-Reason-Type":{"anyOf":[{"type":"string","enum":["Adhoc","Benefit reversal","Bonus","Correction","Dismissed employee","Hired employee","Wage correction","Tax reconciliation","Reversal","Disability insurance distribution","Transition from old pay schedule"]},{"type":"null"}],"description":"The off-cycle reason. Only included for off-cycle payrolls.","readOnly":true},"Auto-Pilot-Type":{"type":"boolean","description":"Indicates whether the payroll has automatic payroll enabled","readOnly":true},"Payroll-External-Type":{"type":"boolean","description":"Indicates whether the payroll is an external payroll","readOnly":true},"Payroll-Final-Termination-Payroll-Type":{"type":"boolean","description":"Indicates whether the payroll is the final payroll for a terminated employee. Only included for off-cycle payrolls.","readOnly":true},"Payroll-Skip-Regular-Deductions-Type":{"type":["boolean","null"],"description":"Block regular deductions and contributions for this payroll.  Only included for off-cycle payrolls.","readOnly":true},"Payroll-Withholding-Pay-Period-Type":{"description":"The payment schedule tax rate the payroll is based on. Only included for off-cycle payrolls.","readOnly":true,"anyOf":[{"type":"string","enum":["Every week","Every other week","Twice per month","Monthly","Quarterly","Semiannually","Annually"]},{"type":"null"}]},"Payroll-Fixed-Withholding-Rate-Type":{"type":["boolean","null"],"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.","readOnly":true},"Payroll-Pay-Period-Type":{"type":"object","readOnly":true,"properties":{"start_date":{"type":"string","description":"The start date, inclusive, of the pay period.","readOnly":true},"end_date":{"type":"string","description":"The start date, inclusive, of the pay period.","readOnly":true},"pay_schedule_uuid":{"type":["string","null"],"description":"The UUID of the pay schedule for the payroll.","readOnly":true}}},"Payroll-Payroll-Status-Meta-Type":{"type":"object","description":"Information about the payroll's status and expected dates","properties":{"cancellable":{"type":"boolean","description":"true if the payroll may be cancelled.","readOnly":true},"expected_check_date":{"type":"string","description":"The date an employee will be paid if the payroll is submitted now.","readOnly":true},"initial_check_date":{"type":["string","null"],"description":"The normal check date for the associated pay period. Returns `null` for off-cycle payrolls (not meaningful for off-cycle).","readOnly":true},"expected_debit_time":{"type":"string","description":"The time the employer's account will be debited if the payroll is submitted now.","readOnly":true},"payroll_late":{"type":["boolean","null"],"description":"expected_check_date > initial_check_date. Returns `null` for off-cycle payrolls (not meaningful for off-cycle).","readOnly":true},"initial_debit_cutoff_time":{"type":"string","description":"Payroll must be submitted at or before this time to avoid late payroll.","readOnly":true}}},"Payroll-Totals-Type":{"type":"object","description":"The subtotals for the payroll.","properties":{"company_debit":{"type":"string","description":"The total company debit for the payroll.","readOnly":true},"net_pay_debit":{"type":"string","minLength":1,"description":"The total company net pay for the payroll."},"tax_debit":{"type":"string","description":"The total tax debit for the payroll.","readOnly":true},"reimbursement_debit":{"type":"string","description":"The total reimbursement debit for the payroll.","readOnly":true},"child_support_debit":{"type":"string","description":"The total child support debit for the payroll.","readOnly":true},"reimbursements":{"type":"string","description":"The total reimbursements for the payroll.","readOnly":true},"net_pay":{"type":"string","description":"The net pay amount for the payroll.","readOnly":true},"gross_pay":{"type":"string","description":"The gross pay amount for the payroll.","readOnly":true},"employee_bonuses":{"type":"string","description":"The total employee bonuses amount for the payroll.","readOnly":true},"employee_commissions":{"type":"string","description":"The total employee commissions amount for the payroll.","readOnly":true},"employee_cash_tips":{"type":"string","description":"The total employee cash tips amount for the payroll.","readOnly":true},"employee_paycheck_tips":{"type":"string","description":"The total employee paycheck tips amount for the payroll.","readOnly":true},"additional_earnings":{"type":"string","description":"The total additional earnings amount for the payroll.","readOnly":true},"owners_draw":{"type":"string","description":"The total owner's draw for the payroll.","readOnly":true},"check_amount":{"type":"string","description":"The total check amount for the payroll.","readOnly":true},"employer_taxes":{"type":"string","description":"The total amount of employer paid taxes for the payroll.","readOnly":true},"employee_taxes":{"type":"string","description":"The total amount of employee paid taxes for the payroll.","readOnly":true},"benefits":{"type":"string","description":"The total amount of company contributed benefits for the payroll.","readOnly":true},"employee_benefits_deductions":{"type":"string","description":"The total amount of employee deducted benefits for the payroll.","readOnly":true},"imputed_pay":{"type":"string","description":"The total amount of imputed pay for the payroll.","readOnly":true},"deferred_payroll_taxes":{"type":"string","description":"The total amount of payroll taxes deferred for the payroll, such as allowed by the CARES act.","readOnly":true},"other_deductions":{"type":"string","description":"The total amount of deductions for the payroll."}},"readOnly":true},"Payroll-Employee-Compensations-Included":{"type":"object","additionalProperties":true,"properties":{"taxes":{"type":"array","uniqueItems":false,"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.","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"employer":{"type":"boolean"},"amount":{"type":"string","format":"float"}},"required":["name","employer","amount"],"readOnly":true},"readOnly":true},"benefits":{"type":"array","uniqueItems":false,"description":"An array of employee benefits for the pay period. Benefits are only included for processed payroll when the include parameter is present.","items":{"type":"object","properties":{"name":{"type":"string","readOnly":true},"employee_deduction":{"type":"string","format":"float","readOnly":true},"company_contribution":{"type":"string","format":"float","readOnly":true},"imputed":{"type":"boolean"}},"readOnly":true},"readOnly":true},"deductions":{"type":"array","uniqueItems":false,"description":"An array of employee deductions for the pay period. Only included when `deductions` is present in the `include` parameter.","items":{"type":"object","properties":{"name":{"type":"string","description":"The name of the deduction."},"amount":{"type":"string","format":"float","description":"The amount of the deduction for the pay period."},"amount_type":{"type":"string","description":"The amount type of the deduction for the pay period. Only present for unprocessed payrolls.","enum":["fixed","percent"]},"uuid":{"type":"string","description":"The UUID of the deduction. Only present for unprocessed payrolls.","readOnly":true},"updatable_via_payroll":{"type":"boolean","description":"Whether the deduction can be updated via the payroll update endpoint. Only present for unprocessed payrolls.","readOnly":true}}}}}},"Payroll-Employee-Compensations-Base-Type":{"type":"object","properties":{"employee_uuid":{"type":"string","description":"The UUID of the employee.","readOnly":true},"excluded":{"type":"boolean","description":"This employee will be excluded (skipped) from payroll calculation and will not be paid for the payroll. Cancelling a payroll would reset all employees' excluded back to false.","readOnly":true},"first_name":{"type":["string","null"],"description":"The first name of the employee. Requires `employees:read` scope.","readOnly":true},"preferred_first_name":{"type":["string","null"],"description":"The preferred first name of the employee. Requires `employees:read` scope.","readOnly":true},"last_name":{"type":["string","null"],"description":"The last name of the employee. Requires `employees:read` scope.","readOnly":true},"gross_pay":{"type":["string","null"],"description":"The employee's gross pay (as a string-formatted decimal, e.g. \"1234.56\"), equal to regular wages + cash tips + payroll tips + any other additional earnings, excluding imputed income. This value is only available for processed payrolls.","readOnly":true},"net_pay":{"type":["string","null"],"description":"The employee's net pay (as a string-formatted decimal, e.g. \"1234.56\"), equal to gross_pay - employee taxes - employee deductions or garnishments - cash tips. This value is only available for processed payrolls.","readOnly":true},"check_amount":{"type":["string","null"],"description":"The employee's check amount (as a string-formatted decimal, e.g. \"1234.56\"), equal to net_pay + reimbursements. This value is only available for processed payrolls.","readOnly":true},"payment_method":{"description":"The employee's compensation payment method. Is *only* `Historical` when retrieving external payrolls initially run outside of Gusto, then put into Gusto.","anyOf":[{"type":"string","enum":["Direct Deposit","Check","Historical"]},{"type":"null"}]},"memo":{"type":["string","null"],"description":"Custom text that will be printed as a personal note to the employee on a paystub.","readOnly":true},"fixed_compensations":{"type":"array","uniqueItems":false,"description":"An array of fixed compensations for the employee. Fixed compensations include tips and bonuses. On regular payrolls, reimbursements are sent via the dedicated `reimbursements` array instead. Off-cycle payrolls continue to include reimbursements in `fixed_compensations`. 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.","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","description":"The UUID of the job for the compensation.","readOnly":true}}}},"hourly_compensations":{"type":"array","uniqueItems":false,"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.","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","description":"The UUID of the job for the compensation.","readOnly":true},"compensation_multiplier":{"type":"number","description":"The amount multiplied by the base rate to calculate total compensation per hour worked.","readOnly":true},"flsa_status":{"type":"string","description":"The FLSA Status of the employee's primary job compensation","readOnly":true}}}},"paid_time_off":{"type":"array","uniqueItems":false,"description":"An array of all paid time off the employee is eligible for this pay period.","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."},"amount":{"type":["string","null"],"description":"The dollar amount paid for this PTO entry during the pay period (as a string-formatted decimal, e.g. \"1234.56\"). Only available for processed payrolls.","readOnly":true},"final_payout_unused_hours_input":{"type":["string","null"],"description":"The outstanding hours paid upon termination. This field is only applicable for termination payrolls."}}}},"reimbursements":{"type":"array","uniqueItems":false,"description":"An array of reimbursements for the employee.","items":{"type":"object","properties":{"amount":{"type":"string","description":"The dollar amount of the reimbursement for the pay period."},"description":{"type":["string","null"],"description":"The description of the reimbursement. Null for unnamed reimbursements."},"uuid":{"type":["string","null"],"description":"The UUID of the reimbursement. Null for unnamed reimbursements. This field is only available for unprocessed payrolls.","readOnly":true},"recurring":{"type":"boolean","description":"Whether the reimbursement is recurring. This field is only available for unprocessed payrolls.","readOnly":true}},"required":["amount","description"]}},"custom_withholdings":{"type":"object","description":"The one-time custom withholding overrides applied to this payroll for this employee.\n`federal` is null when no federal one-time override is set; `state` is an empty\narray when no state one-time overrides are set.\n","properties":{"federal":{"type":["object","null"],"description":"Federal one-time custom withholding override applied to this payroll.","properties":{"override_type":{"type":"string","enum":["one_time"],"description":"Override mode. Only `one_time` is currently exposed."},"amount":{"type":"string","description":"The amount that was withheld for this payroll."},"amount_type":{"type":"string","enum":["fixed","percent"],"description":"How to interpret the amount."}}},"state":{"type":"array","description":"State one-time custom withholding overrides applied to this payroll, one entry per state field.","items":{"type":"object","properties":{"employee_state_field_uuid":{"type":"string","description":"The UUID of the EmployeeStateField this withholding applies to."},"override_type":{"type":"string","enum":["one_time"],"description":"Override mode. Only `one_time` is currently exposed."},"amount":{"type":"string","description":"The amount that was withheld for this payroll."},"amount_type":{"type":"string","enum":["fixed","percent"],"description":"How to interpret the amount."}}}}}}}},"Payroll-Employee-Compensations-Type":{"allOf":[{"$ref":"#/components/schemas/Payroll-Employee-Compensations-Base-Type"},{"$ref":"#/components/schemas/Versionable"},{"type":"object","properties":{"version":{"description":"The current version of this employee compensation. This field is only available for prepared payrolls. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for information on how to use this field."},"deductions":{"type":"array","uniqueItems":false,"description":"An array of deductions for the employee. This field is included by default for regular payrolls in version `v2025-06-15` and later.","items":{"type":"object","properties":{"name":{"type":"string","description":"The name of the deduction."},"amount":{"type":"number","description":"The amount of the deduction for the pay period."},"amount_type":{"type":"string","description":"The amount type of the deduction for the pay period. Only present for unprocessed payrolls.","enum":["fixed","percent"]},"uuid":{"type":"string","description":"The UUID of the deduction. Only present for unprocessed payrolls."},"updatable_via_payroll":{"type":"boolean","description":"Whether the deduction can be updated via the payroll update endpoint. Only present for unprocessed payrolls.","readOnly":true}}}}}}]},"Payroll-Unprocessed-Employee-Compensations-Type":{"allOf":[{"$ref":"#/components/schemas/Payroll-Employee-Compensations-Base-Type"},{"$ref":"#/components/schemas/Versionable"},{"type":"object","properties":{"version":{"description":"The current version of this employee compensation. This field is only available for prepared payrolls. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/api-fundamentals#optimistic-version-control) for information on how to use this field."}}}]},"Payroll-Company-Taxes-Type":{"type":"array","uniqueItems":false,"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.","items":{"type":"object","properties":{"name":{"type":"string","description":"The tax name"},"employer":{"type":"boolean","description":"Whether this tax is an employer or employee tax"},"amount":{"type":"string","description":"The amount of this tax for the payroll"}}}},"Payroll-Taxes-Type":{"type":"array","uniqueItems":false,"description":"An array of tax totals applicable to this payroll. Only included for processed or calculated payrolls when `payroll_taxes` is present in the `include` parameter.","items":{"type":"object","properties":{"name":{"type":"string","description":"The tax name"},"employer":{"type":"boolean","description":"Whether this tax is an employer or employee tax"},"amount":{"type":"number","description":"The total tax for the payroll"}}}},"Payroll-Payment-Speed-Changed-Type":{"type":"object","description":"Only applicable when a payroll is moved to four day processing instead of fast ach.","properties":{"original_check_date":{"type":"string","description":"Original check date when fast ach applies.","readOnly":true},"current_check_date":{"type":"string","description":"Current check date.","readOnly":true},"original_debit_date":{"type":"string","description":"Original debit date when fast ach applies.","readOnly":true},"current_debit_date":{"type":"string","description":"Current debit date.","readOnly":true},"reason":{"type":"string","description":"The reason why the payroll is moved to four day.","readOnly":true}}},"Created-At-Type":{"type":"string","format":"date-time","description":"Datetime for when the resource was created.","readOnly":true},"Payroll-Submission-Blocker-Type":{"type":"object","description":"A blocker that prevents payment submission.","properties":{"blocker_type":{"type":"string","description":"The type of blocker that's blocking the payment submission.","readOnly":true},"blocker_name":{"type":"string","description":"The name of the submission blocker.","readOnly":true},"unblock_options":{"type":"array","uniqueItems":true,"items":{"type":"object","properties":{"unblock_type":{"type":"string","description":"The type of unblock option for the submission blocker.","readOnly":true},"check_date":{"type":"string","description":"The payment check date associated with the unblock option.","readOnly":true},"metadata":{"type":"object","additionalProperties":true,"description":"Additional data associated with the unblock option.","readOnly":true}}},"description":"The available options to unblock a submission blocker.","readOnly":true},"selected_option":{"type":["string","null"],"description":"The unblock option that's been selected to resolve the submission blocker.","readOnly":false},"status":{"type":"string","description":"The status of the submission blocker.","enum":["unresolved","resolved"],"readOnly":true}}},"Payroll-Submission-Blocker-Request-Type":{"type":"object","description":"Request object for resolving a submission blocker. Each submission_blocker should include a selected unblock option.","required":["blocker_type","selected_option"],"properties":{"blocker_type":{"type":"string","description":"The type of submission_blocker that is blocking the payment."},"selected_option":{"type":"string","description":"The selected option to unblock the payment's submission_blocker."}}},"Payroll-Submission-Blockers-Type":{"type":"array","description":"Only included for processed or calculated payrolls","uniqueItems":true,"items":{"$ref":"#/components/schemas/Payroll-Submission-Blocker-Type"}},"Payroll-Credit-Blocker-Unblock-Option-Submit-Wire":{"type":"object","description":"Unblock option to resolve a credit blocker by submitting a wire transfer","required":["unblock_type","check_date","metadata"],"properties":{"unblock_type":{"type":"string","enum":["submit_wire"],"description":"The type of unblock option for the credit blocker","readOnly":true},"check_date":{"type":"string","description":"The payment check date associated with the unblock option","readOnly":true},"metadata":{"type":"object","required":["wire_in_amount","wire_in_deadline","wire_in_request_uuid"],"properties":{"wire_in_amount":{"type":"string","description":"The amount to be wired in (decimal string)","readOnly":true},"wire_in_deadline":{"type":"string","format":"date-time","description":"Deadline for the wire transfer to be received","readOnly":true},"wire_in_request_uuid":{"type":"string","description":"UUID of the wire in request","readOnly":true}},"readOnly":true}}},"Payroll-Credit-Blocker-Unblock-Option-Submit-Bank-Screenshot":{"type":"object","description":"Unblock option to resolve a credit blocker by submitting a bank screenshot","required":["unblock_type","check_date","metadata"],"properties":{"unblock_type":{"type":"string","enum":["submit_bank_screenshot"],"description":"The type of unblock option for the credit blocker","readOnly":true},"check_date":{"type":"string","description":"The payment check date associated with the unblock option","readOnly":true},"metadata":{"type":"object","required":["information_request_uuid"],"properties":{"information_request_uuid":{"type":"string","description":"UUID of the information request","readOnly":true},"bank_account_last_four_digits":{"type":["string","null"],"description":"Last 4 digits of the bank account number for the bank screenshot RFI","readOnly":true}},"readOnly":true}}},"Payroll-Credit-Blocker-Unblock-Option-Respond-To-High-Risk-Fraud-Rfi":{"type":"object","description":"Unblock option to resolve a credit blocker by responding to high risk fraud RFI","required":["unblock_type","check_date","metadata"],"properties":{"unblock_type":{"type":"string","enum":["respond_to_high_risk_fraud_rfi"],"description":"The type of unblock option for the credit blocker","readOnly":true},"check_date":{"type":"string","description":"The payment check date associated with the unblock option","readOnly":true},"metadata":{"type":"object","required":["information_request_uuid"],"properties":{"information_request_uuid":{"type":"string","description":"UUID of the information request","readOnly":true}},"readOnly":true}}},"Payroll-Credit-Blocker-Unblock-Option-Wait-For-Reverse-Wire":{"type":"object","description":"Unblock option to resolve a credit blocker by waiting for reverse wire","required":["unblock_type","check_date","metadata"],"properties":{"unblock_type":{"type":"string","enum":["wait_for_reverse_wire"],"description":"The type of unblock option for the credit blocker","readOnly":true},"check_date":{"type":"string","description":"The payment check date associated with the unblock option","readOnly":true},"metadata":{"type":"object","additionalProperties":false,"readOnly":true}}},"Payroll-Credit-Blocker-Type":{"type":"object","description":"A blocker that prevents payment crediting.","properties":{"blocker_type":{"type":"string","description":"The type of blocker that's blocking the payment from being credited.","readOnly":true},"blocker_name":{"type":"string","description":"The name of the credit blocker.","readOnly":true},"unblock_options":{"type":"array","uniqueItems":true,"items":{"oneOf":[{"$ref":"#/components/schemas/Payroll-Credit-Blocker-Unblock-Option-Submit-Wire"},{"$ref":"#/components/schemas/Payroll-Credit-Blocker-Unblock-Option-Submit-Bank-Screenshot"},{"$ref":"#/components/schemas/Payroll-Credit-Blocker-Unblock-Option-Respond-To-High-Risk-Fraud-Rfi"},{"$ref":"#/components/schemas/Payroll-Credit-Blocker-Unblock-Option-Wait-For-Reverse-Wire"}],"discriminator":{"propertyName":"unblock_type","mapping":{"submit_wire":"#/components/schemas/Payroll-Credit-Blocker-Unblock-Option-Submit-Wire","submit_bank_screenshot":"#/components/schemas/Payroll-Credit-Blocker-Unblock-Option-Submit-Bank-Screenshot","respond_to_high_risk_fraud_rfi":"#/components/schemas/Payroll-Credit-Blocker-Unblock-Option-Respond-To-High-Risk-Fraud-Rfi","wait_for_reverse_wire":"#/components/schemas/Payroll-Credit-Blocker-Unblock-Option-Wait-For-Reverse-Wire"}}},"description":"The available options to unblock a credit blocker.","readOnly":true},"selected_option":{"type":["string","null"],"description":"The unblock option that's been selected to resolve the credit blocker.","readOnly":false},"status":{"type":"string","description":"The status of the credit blocker","enum":["unresolved","pending_review","resolved","failed"]}}},"Payroll-Credit-Blockers-Type":{"type":"array","description":"Only included for processed payrolls","uniqueItems":true,"items":{"$ref":"#/components/schemas/Payroll-Credit-Blocker-Type"}},"Payroll-Processing-Request":{"type":["object","null"],"properties":{"status":{"type":"string","description":"The status of the payroll processing request","readOnly":true,"enum":["calculating","calculate_success","submitting","submit_success","processing_failed"]},"errors":{"description":"Errors that occurred during async payroll processing","readOnly":true,"type":"array","items":{"$ref":"#/components/schemas/Entity-Error-Object"}}}},"Payroll-Fixed-Compensation-Types-Type":{"type":"array","items":{"type":"object","readOnly":true,"properties":{"name":{"description":"The name of an available type of fixed compensation.","type":"string","readOnly":true}}}},"Payroll-Show":{"type":"object","x-examples":{"success_status":{"uuid":"b441a30b-2adb-489e-b7b7-9d094011a3f8","employee_compensations":[],"submission_blockers":[],"credit_blockers":[],"payroll_uuid":"b441a30b-2adb-489e-b7b7-9d094011a3f8","company_uuid":"9aa93530-43d5-484e-b608-33214109420d","off_cycle":false,"auto_payroll":false,"processed":true,"processed_date":"2025-06-16","calculated_at":"2025-06-16T16:58:03Z","pay_period":{"start_date":"2025-05-25","end_date":"2025-06-09","pay_schedule_uuid":"40ff5990-0191-4796-9717-32f7dd3e94d5"},"check_date":"2025-06-13","external":false,"payroll_deadline":"2025-06-17T23:00:00Z","totals":{"employee_bonuses":"0.00","employee_commissions":"0.00","employee_cash_tips":"0.00","employee_paycheck_tips":"0.00","additional_earnings":"0.00","owners_draw":"0.00","benefits":"0.00","check_amount":"0.00","child_support_debit":"0.00","company_debit":"0.00","deferred_payroll_taxes":"0.00","employee_benefits_deductions":"0.00","employee_taxes":"0.00","employer_taxes":"0.00","gross_pay":"0.00","imputed_pay":"0.00","net_pay":"0.00","net_pay_debit":"0.00","other_deductions":"0.00","reimbursement_debit":"0.00","reimbursements":"0.00","tax_debit":"0.00"},"processing_request":{"status":"submit_success","errors":[]},"created_at":"2025-06-16T16:58:03Z","partner_owned_disbursement":null},"with_submit_wire_credit_blocker":{"uuid":"b441a30b-2adb-489e-b7b7-9d094011a3f8","employee_compensations":[],"submission_blockers":[],"credit_blockers":[{"blocker_type":"waiting_for_wire_in","blocker_name":"Waiting for Wire In","unblock_options":[{"unblock_type":"submit_wire","check_date":"2025-06-13","metadata":{"wire_in_amount":"15000.00","wire_in_deadline":"2025-06-12T18:00:00Z","wire_in_request_uuid":"c1234567-89ab-cdef-0123-456789abcdef"}}],"selected_option":null,"status":"unresolved"}],"payroll_uuid":"b441a30b-2adb-489e-b7b7-9d094011a3f8","company_uuid":"9aa93530-43d5-484e-b608-33214109420d","off_cycle":false,"auto_payroll":false,"processed":true,"processed_date":"2025-06-16","calculated_at":"2025-06-16T16:58:03Z","pay_period":{"start_date":"2025-05-25","end_date":"2025-06-09","pay_schedule_uuid":"40ff5990-0191-4796-9717-32f7dd3e94d5"},"check_date":"2025-06-13","external":false,"payroll_deadline":"2025-06-17T23:00:00Z","totals":{"employee_bonuses":"0.00","employee_commissions":"0.00","employee_cash_tips":"0.00","employee_paycheck_tips":"0.00","additional_earnings":"0.00","owners_draw":"0.00","benefits":"0.00","check_amount":"0.00","child_support_debit":"0.00","company_debit":"0.00","deferred_payroll_taxes":"0.00","employee_benefits_deductions":"0.00","employee_taxes":"0.00","employer_taxes":"0.00","gross_pay":"0.00","imputed_pay":"0.00","net_pay":"0.00","net_pay_debit":"0.00","other_deductions":"0.00","reimbursement_debit":"0.00","reimbursements":"0.00","tax_debit":"0.00"},"processing_request":{"status":"submit_success","errors":[]},"created_at":"2025-06-16T16:58:03Z","partner_owned_disbursement":null},"with_submit_bank_screenshot_credit_blocker":{"uuid":"b441a30b-2adb-489e-b7b7-9d094011a3f8","employee_compensations":[],"submission_blockers":[],"credit_blockers":[{"blocker_type":"waiting_for_bank_screenshot","blocker_name":"Waiting for Bank Screenshot","unblock_options":[{"unblock_type":"submit_bank_screenshot","check_date":"2025-06-13","metadata":{"information_request_uuid":"d2234567-89ab-cdef-0123-456789abcdef"}}],"selected_option":null,"status":"unresolved"}],"payroll_uuid":"b441a30b-2adb-489e-b7b7-9d094011a3f8","company_uuid":"9aa93530-43d5-484e-b608-33214109420d","off_cycle":false,"auto_payroll":false,"processed":true,"processed_date":"2025-06-16","calculated_at":"2025-06-16T16:58:03Z","pay_period":{"start_date":"2025-05-25","end_date":"2025-06-09","pay_schedule_uuid":"40ff5990-0191-4796-9717-32f7dd3e94d5"},"check_date":"2025-06-13","external":false,"payroll_deadline":"2025-06-17T23:00:00Z","totals":{"employee_bonuses":"0.00","employee_commissions":"0.00","employee_cash_tips":"0.00","employee_paycheck_tips":"0.00","additional_earnings":"0.00","owners_draw":"0.00","benefits":"0.00","check_amount":"0.00","child_support_debit":"0.00","company_debit":"0.00","deferred_payroll_taxes":"0.00","employee_benefits_deductions":"0.00","employee_taxes":"0.00","employer_taxes":"0.00","gross_pay":"0.00","imputed_pay":"0.00","net_pay":"0.00","net_pay_debit":"0.00","other_deductions":"0.00","reimbursement_debit":"0.00","reimbursements":"0.00","tax_debit":"0.00"},"processing_request":{"status":"submit_success","errors":[]},"created_at":"2025-06-16T16:58:03Z","partner_owned_disbursement":null},"with_respond_to_high_risk_fraud_rfi_credit_blocker":{"uuid":"b441a30b-2adb-489e-b7b7-9d094011a3f8","employee_compensations":[],"submission_blockers":[],"credit_blockers":[{"blocker_type":"waiting_for_high_risk_fraud_rfi","blocker_name":"Waiting for High Risk Fraud RFI","unblock_options":[{"unblock_type":"respond_to_high_risk_fraud_rfi","check_date":"2025-06-13","metadata":{"information_request_uuid":"e3234567-89ab-cdef-0123-456789abcdef"}}],"selected_option":null,"status":"pending_review"}],"payroll_uuid":"b441a30b-2adb-489e-b7b7-9d094011a3f8","company_uuid":"9aa93530-43d5-484e-b608-33214109420d","off_cycle":false,"auto_payroll":false,"processed":true,"processed_date":"2025-06-16","calculated_at":"2025-06-16T16:58:03Z","pay_period":{"start_date":"2025-05-25","end_date":"2025-06-09","pay_schedule_uuid":"40ff5990-0191-4796-9717-32f7dd3e94d5"},"check_date":"2025-06-13","external":false,"payroll_deadline":"2025-06-17T23:00:00Z","totals":{"employee_bonuses":"0.00","employee_commissions":"0.00","employee_cash_tips":"0.00","employee_paycheck_tips":"0.00","additional_earnings":"0.00","owners_draw":"0.00","benefits":"0.00","check_amount":"0.00","child_support_debit":"0.00","company_debit":"0.00","deferred_payroll_taxes":"0.00","employee_benefits_deductions":"0.00","employee_taxes":"0.00","employer_taxes":"0.00","gross_pay":"0.00","imputed_pay":"0.00","net_pay":"0.00","net_pay_debit":"0.00","other_deductions":"0.00","reimbursement_debit":"0.00","reimbursements":"0.00","tax_debit":"0.00"},"processing_request":{"status":"submit_success","errors":[]},"created_at":"2025-06-16T16:58:03Z","partner_owned_disbursement":null},"with_wait_for_reverse_wire_credit_blocker":{"uuid":"b441a30b-2adb-489e-b7b7-9d094011a3f8","employee_compensations":[],"submission_blockers":[],"credit_blockers":[{"blocker_type":"waiting_for_reverse_wire","blocker_name":"Waiting for Reverse Wire","unblock_options":[{"unblock_type":"wait_for_reverse_wire","check_date":"2025-06-13","metadata":{}}],"selected_option":null,"status":"resolved"}],"payroll_uuid":"b441a30b-2adb-489e-b7b7-9d094011a3f8","company_uuid":"9aa93530-43d5-484e-b608-33214109420d","off_cycle":false,"auto_payroll":false,"processed":true,"processed_date":"2025-06-16","calculated_at":"2025-06-16T16:58:03Z","pay_period":{"start_date":"2025-05-25","end_date":"2025-06-09","pay_schedule_uuid":"40ff5990-0191-4796-9717-32f7dd3e94d5"},"check_date":"2025-06-13","external":false,"payroll_deadline":"2025-06-17T23:00:00Z","totals":{"employee_bonuses":"0.00","employee_commissions":"0.00","employee_cash_tips":"0.00","employee_paycheck_tips":"0.00","additional_earnings":"0.00","owners_draw":"0.00","benefits":"0.00","check_amount":"0.00","child_support_debit":"0.00","company_debit":"0.00","deferred_payroll_taxes":"0.00","employee_benefits_deductions":"0.00","employee_taxes":"0.00","employer_taxes":"0.00","gross_pay":"0.00","imputed_pay":"0.00","net_pay":"0.00","net_pay_debit":"0.00","other_deductions":"0.00","reimbursement_debit":"0.00","reimbursements":"0.00","tax_debit":"0.00"},"processing_request":{"status":"submit_success","errors":[]},"created_at":"2025-06-16T16:58:03Z","partner_owned_disbursement":null}},"properties":{"payroll_deadline":{"$ref":"#/components/schemas/Payroll-Deadline-Type"},"check_date":{"$ref":"#/components/schemas/Payroll-Check-Date-Type"},"processed":{"$ref":"#/components/schemas/Payroll-Processed-Type"},"processed_date":{"$ref":"#/components/schemas/Payroll-Processed-Date-Type"},"calculated_at":{"$ref":"#/components/schemas/Payroll-Calculated-At-Type"},"uuid":{"$ref":"#/components/schemas/Payroll-Payroll-Uuid-Type"},"payroll_uuid":{"$ref":"#/components/schemas/Payroll-Payroll-Uuid-Type"},"company_uuid":{"$ref":"#/components/schemas/Payroll-Company-Uuid-Type"},"off_cycle":{"$ref":"#/components/schemas/Payroll-Off-Cycle-Type"},"off_cycle_reason":{"$ref":"#/components/schemas/Off-Cycle-Reason-Type"},"auto_payroll":{"$ref":"#/components/schemas/Auto-Pilot-Type"},"external":{"$ref":"#/components/schemas/Payroll-External-Type"},"final_termination_payroll":{"$ref":"#/components/schemas/Payroll-Final-Termination-Payroll-Type"},"withholding_pay_period":{"$ref":"#/components/schemas/Payroll-Withholding-Pay-Period-Type"},"skip_regular_deductions":{"$ref":"#/components/schemas/Payroll-Skip-Regular-Deductions-Type"},"fixed_withholding_rate":{"$ref":"#/components/schemas/Payroll-Fixed-Withholding-Rate-Type"},"pay_period":{"$ref":"#/components/schemas/Payroll-Pay-Period-Type"},"payroll_status_meta":{"$ref":"#/components/schemas/Payroll-Payroll-Status-Meta-Type"},"totals":{"$ref":"#/components/schemas/Payroll-Totals-Type"},"company_taxes":{"$ref":"#/components/schemas/Payroll-Company-Taxes-Type"},"payroll_taxes":{"$ref":"#/components/schemas/Payroll-Taxes-Type"},"payment_speed_changed":{"$ref":"#/components/schemas/Payroll-Payment-Speed-Changed-Type"},"created_at":{"$ref":"#/components/schemas/Created-At-Type"},"submission_blockers":{"$ref":"#/components/schemas/Payroll-Submission-Blockers-Type"},"credit_blockers":{"$ref":"#/components/schemas/Payroll-Credit-Blockers-Type"},"processing_request":{"$ref":"#/components/schemas/Payroll-Processing-Request"},"partner_owned_disbursement":{"$ref":"#/components/schemas/Payroll-Partner-Owned-Disbursement-Type"},"employee_compensations":{"type":"array","uniqueItems":false,"items":{"type":"object","allOf":[{"$ref":"#/components/schemas/Payroll-Employee-Compensations-Type"},{"$ref":"#/components/schemas/Payroll-Employee-Compensations-Included"}]}}}},"Payroll-Unprocessed":{"description":"An unprocessed payroll with employee compensations.","x-examples":{"success_status":{"uuid":"4428f108-e46e-4ab6-ba20-03cea031cfc0","employee_compensations":[],"payroll_uuid":"4428f108-e46e-4ab6-ba20-03cea031cfc0","company_uuid":"42b5333b-ee39-493a-bf7e-f41f2bd67848","payroll_status_meta":{"cancellable":false,"expected_check_date":"2025-06-17","initial_check_date":"2025-06-17","expected_debit_time":"2025-06-11T23:00:00Z","payroll_late":false,"initial_debit_cutoff_time":"2025-06-11T23:00:00Z"},"off_cycle":true,"auto_payroll":false,"off_cycle_reason":"Bonus","withholding_pay_period":"Twice per month","skip_regular_deductions":true,"fixed_withholding_rate":true,"final_termination_payroll":false,"processed":false,"processed_date":null,"calculated_at":null,"pay_period":{"start_date":"2025-06-10","end_date":"2025-06-16","pay_schedule_uuid":null},"check_date":"2025-06-17","external":false,"payroll_deadline":"2025-06-11T23:00:00Z","fixed_compensation_types":[{"name":"Bonus"},{"name":"Commission"},{"name":"Paycheck Tips"},{"name":"Cash Tips"},{"name":"Correction Payment"},{"name":"Reimbursement"}],"created_at":"2025-06-11T19:40:52Z","partner_owned_disbursement":null}},"type":"object","properties":{"payroll_deadline":{"$ref":"#/components/schemas/Payroll-Deadline-Type"},"check_date":{"$ref":"#/components/schemas/Payroll-Check-Date-Type"},"processed":{"$ref":"#/components/schemas/Payroll-Processed-Type"},"processed_date":{"$ref":"#/components/schemas/Payroll-Processed-Date-Type"},"calculated_at":{"$ref":"#/components/schemas/Payroll-Calculated-At-Type"},"uuid":{"$ref":"#/components/schemas/Payroll-Payroll-Uuid-Type"},"payroll_uuid":{"$ref":"#/components/schemas/Payroll-Payroll-Uuid-Type"},"company_uuid":{"$ref":"#/components/schemas/Payroll-Company-Uuid-Type"},"off_cycle":{"$ref":"#/components/schemas/Payroll-Off-Cycle-Type"},"off_cycle_reason":{"$ref":"#/components/schemas/Off-Cycle-Reason-Type"},"auto_payroll":{"$ref":"#/components/schemas/Auto-Pilot-Type"},"external":{"$ref":"#/components/schemas/Payroll-External-Type"},"final_termination_payroll":{"$ref":"#/components/schemas/Payroll-Final-Termination-Payroll-Type"},"withholding_pay_period":{"$ref":"#/components/schemas/Payroll-Withholding-Pay-Period-Type"},"skip_regular_deductions":{"$ref":"#/components/schemas/Payroll-Skip-Regular-Deductions-Type"},"fixed_withholding_rate":{"$ref":"#/components/schemas/Payroll-Fixed-Withholding-Rate-Type"},"pay_period":{"$ref":"#/components/schemas/Payroll-Pay-Period-Type"},"payroll_status_meta":{"$ref":"#/components/schemas/Payroll-Payroll-Status-Meta-Type"},"employee_compensations":{"type":"array","uniqueItems":false,"items":{"$ref":"#/components/schemas/Payroll-Unprocessed-Employee-Compensations-Type"}},"payment_speed_changed":{"$ref":"#/components/schemas/Payroll-Payment-Speed-Changed-Type"},"created_at":{"$ref":"#/components/schemas/Created-At-Type"},"fixed_compensation_types":{"$ref":"#/components/schemas/Payroll-Fixed-Compensation-Types-Type"},"processing_request":{"$ref":"#/components/schemas/Payroll-Processing-Request"},"partner_owned_disbursement":{"$ref":"#/components/schemas/Payroll-Partner-Owned-Disbursement-Type"}}},"Payroll-Prepared":{"description":"The response from preparing a payroll for update. Contains refreshed employee compensations, updated payroll dates, and version information needed for subsequent payroll updates.","x-examples":{"success_status":{"uuid":"4428f108-e46e-4ab6-ba20-03cea031cfc0","employee_compensations":[],"payroll_uuid":"4428f108-e46e-4ab6-ba20-03cea031cfc0","company_uuid":"42b5333b-ee39-493a-bf7e-f41f2bd67848","payroll_status_meta":{"cancellable":false,"expected_check_date":"2025-06-17","initial_check_date":"2025-06-17","expected_debit_time":"2025-06-11T23:00:00Z","payroll_late":false,"initial_debit_cutoff_time":"2025-06-11T23:00:00Z"},"off_cycle":true,"auto_payroll":false,"off_cycle_reason":"Bonus","withholding_pay_period":"Twice per month","skip_regular_deductions":true,"fixed_withholding_rate":true,"final_termination_payroll":false,"processed":false,"processed_date":null,"calculated_at":null,"pay_period":{"start_date":"2025-06-10","end_date":"2025-06-16","pay_schedule_uuid":null},"check_date":"2025-06-17","external":false,"payroll_deadline":"2025-06-11T23:00:00Z","fixed_compensation_types":[{"name":"Bonus"},{"name":"Commission"},{"name":"Paycheck Tips"},{"name":"Cash Tips"},{"name":"Correction Payment"},{"name":"Reimbursement"}],"created_at":"2025-06-11T19:40:52Z","partner_owned_disbursement":null}},"type":"object","properties":{"payroll_deadline":{"$ref":"#/components/schemas/Payroll-Deadline-Type"},"check_date":{"$ref":"#/components/schemas/Payroll-Check-Date-Type"},"processed":{"$ref":"#/components/schemas/Payroll-Processed-Type"},"processed_date":{"$ref":"#/components/schemas/Payroll-Processed-Date-Type"},"calculated_at":{"$ref":"#/components/schemas/Payroll-Calculated-At-Type"},"uuid":{"$ref":"#/components/schemas/Payroll-Payroll-Uuid-Type"},"payroll_uuid":{"$ref":"#/components/schemas/Payroll-Payroll-Uuid-Type"},"company_uuid":{"$ref":"#/components/schemas/Payroll-Company-Uuid-Type"},"off_cycle":{"$ref":"#/components/schemas/Payroll-Off-Cycle-Type"},"off_cycle_reason":{"$ref":"#/components/schemas/Off-Cycle-Reason-Type"},"auto_payroll":{"$ref":"#/components/schemas/Auto-Pilot-Type"},"external":{"$ref":"#/components/schemas/Payroll-External-Type"},"final_termination_payroll":{"$ref":"#/components/schemas/Payroll-Final-Termination-Payroll-Type"},"withholding_pay_period":{"$ref":"#/components/schemas/Payroll-Withholding-Pay-Period-Type"},"skip_regular_deductions":{"$ref":"#/components/schemas/Payroll-Skip-Regular-Deductions-Type"},"fixed_withholding_rate":{"$ref":"#/components/schemas/Payroll-Fixed-Withholding-Rate-Type"},"pay_period":{"$ref":"#/components/schemas/Payroll-Pay-Period-Type"},"payroll_status_meta":{"$ref":"#/components/schemas/Payroll-Payroll-Status-Meta-Type"},"employee_compensations":{"type":"array","uniqueItems":false,"items":{"$ref":"#/components/schemas/Payroll-Employee-Compensations-Type"}},"payment_speed_changed":{"$ref":"#/components/schemas/Payroll-Payment-Speed-Changed-Type"},"created_at":{"$ref":"#/components/schemas/Created-At-Type"},"fixed_compensation_types":{"$ref":"#/components/schemas/Payroll-Fixed-Compensation-Types-Type"},"processing_request":{"$ref":"#/components/schemas/Payroll-Processing-Request"},"partner_owned_disbursement":{"$ref":"#/components/schemas/Payroll-Partner-Owned-Disbursement-Type"}}},"Payroll-Receipt":{"type":"object","x-examples":{"success_status":{"totals":{"company_debit":"0.00","net_pay_debit":"0.00","child_support_debit":"0.00","reimbursement_debit":"0.00","tax_debit":"0.00"},"taxes":[],"employee_compensations":[],"licensee":{"name":"Gusto, Zenpayroll Inc.","address":"525 20th St","city":"San Francisco","state":"CA","postal_code":"94107","phone_number":"4157778888"},"payroll_uuid":"9f624c0d-0d4f-499a-993a-846dfa47a48e","company_uuid":"0481a066-e26a-465b-a2c1-933bd5b03a69","name_of_sender":"Kiehn, Conroy and Prohaska","name_of_recipient":"Payroll Recipients","recipient_notice":"Payroll recipients include the employees listed below plus the tax agencies for the taxes listed below.","debit_date":"2025-06-12","license":"ZenPayroll, Inc., dba Gusto is a licensed money transmitter. For more about Gusto’s licenses and your state-specific rights to request information, submit complaints, dispute errors, or cancel transactions, visit our license page.","license_uri":"https://gusto.com/about/licenses","right_to_refund":"https://gusto.com/about/licenses","liability_of_licensee":"https://gusto.com/about/licenses"}},"properties":{"payroll_uuid":{"type":"string","description":"A unique identifier of the payroll receipt."},"company_uuid":{"type":"string","description":"A unique identifier of the company for the payroll."},"name_of_sender":{"type":"string","description":"The name of the company by whom the payroll was paid"},"name_of_recipient":{"type":"string","description":"Always the fixed string \"Payroll Recipients\""},"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.\""},"debit_date":{"type":"string","description":"The debit or funding date 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.\""},"license_uri":{"type":"string","description":"URL for the license information for the licensed payroll processor. Always the fixed string \"https://gusto.com/about/licenses\""},"right_to_refund":{"type":"string","description":""},"liability_of_licensee":{"type":"string","description":""},"totals":{"type":"object","description":"The subtotals for the payroll.","properties":{"company_debit":{"type":"string","format":"float","description":"The total company debit for the payroll."},"net_pay_debit":{"type":"string","format":"float","description":"The total company net pay for the payroll."},"child_support_debit":{"type":"string","format":"float","description":"The total child support debit for the payroll."},"reimbursement_debit":{"type":"string","format":"float","description":"The total reimbursements for the payroll."},"tax_debit":{"type":"string","format":"float","description":"The total tax debit for the payroll."}}},"taxes":{"type":"array","description":"An array of totaled employer and employee taxes for the pay period.","items":{"type":"object","properties":{"name":{"type":"string","description":"The amount paid for this tax."},"amount":{"type":"string","format":"float","description":"The total amount paid by both employer and employee for this tax."}}}},"employee_compensations":{"type":"array","description":"An array of employee compensations and withholdings for this payroll","items":{"type":"object","properties":{"employee_uuid":{"type":"string","description":"The UUID of the employee."},"employee_first_name":{"type":"string","description":"The first name of the employee."},"employee_last_name":{"type":"string","description":"The last name of the employee."},"payment_method":{"type":"string","description":"The employee's compensation payment method.","enum":["Direct Deposit","Check"]},"net_pay":{"type":"string","format":"float","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","format":"float","description":"The total of employer and employee taxes for the pay period."},"total_garnishments":{"type":"string","format":"float","description":"The total garnishments for the pay period."},"child_support_garnishment":{"type":"string","format":"float","description":"The total child support garnishment for the pay period."},"total_reimbursement":{"type":"string","format":"float","description":"The total reimbursement for the pay period."}}}},"licensee":{"type":"object","description":"The licensed payroll processor","properties":{"name":{"type":"string","description":"Always the fixed string \"Gusto, Zenpayroll Inc.\""},"address":{"type":"string","description":"Always the fixed string \"525 20th St\""},"city":{"type":"string","description":"Always the fixed string \"San Francisco\""},"state":{"type":"string","description":"Always the fixed string \"CA\""},"postal_code":{"type":"string","description":"Always the fixed string \"94107\""},"phone_number":{"type":"string","description":"Always the fixed string \"4157778888\""}}}}},"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."}}},"Contractor-Address":{"type":"object","x-examples":{"example":{"version":"23323096a8015e32d9795fadf1fd300d","contractor_uuid":"9779767c-6044-48e0-bf68-aeb370b9a2e7","street_1":"999 Kiera Stravenue","street_2":"Suite 391","city":"San Francisco","state":"CA","zip":"94107","country":"USA","active":true}},"properties":{"contractor_uuid":{"type":"string","description":"The UUID of the contractor"},"street_1":{"type":["string","null"],"readOnly":false},"street_2":{"type":["string","null"],"readOnly":false},"city":{"type":["string","null"],"readOnly":false},"state":{"type":["string","null"],"readOnly":false},"zip":{"type":["string","null"],"readOnly":false},"country":{"type":["string","null"],"readOnly":false,"default":"USA"},"active":{"type":"boolean","description":"The status of the location. Inactive locations have been deleted, but may still have historical data associated with them.","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."}}},"Contractor-Address-Update-Body":{"type":"object","properties":{"version":{"type":"string","example":"56d00c178bc7393b2a206ed6a86afcb4","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"},"street_2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"}},"required":["version"],"x-examples":{"example":{"version":"fe75bd065ff48b91c35fe8ff842f986c","street_1":"300 3rd Street","street_2":null,"city":"San Francisco","state":"CA","zip":"94107"}}},"Address":{"type":"object","allOf":[{"$ref":"#/components/schemas/Versionable"},{"type":"object","properties":{"street_1":{"type":["string","null"],"readOnly":false},"street_2":{"type":["string","null"],"readOnly":false},"city":{"type":["string","null"],"readOnly":false},"state":{"type":["string","null"],"readOnly":false},"zip":{"type":["string","null"],"readOnly":false},"country":{"type":["string","null"],"readOnly":false,"default":"USA"},"active":{"type":"boolean","description":"The status of the location. Inactive locations have been deleted, but may still have historical data associated with them.","readOnly":true}}}],"example":{"street_1":"412 Kiera Stravenue","street_2":"Suite 391","city":"San Francisco","state":"CA","zip":"94107","country":"USA","active":true}},"Department":{"type":"object","allOf":[{"$ref":"#/components/schemas/Versionable"},{"type":"object","properties":{"uuid":{"type":"string","description":"The UUID of the department"},"company_uuid":{"type":"string","description":"The UUID of the company"},"title":{"type":"string","description":"Name of the department"},"employees":{"type":"array","description":"Array of employees assigned to the department.","items":{"properties":{"uuid":{"type":"string"}}}},"contractors":{"type":"array","description":"Array of contractors assigned to the department.","items":{"properties":{"uuid":{"type":"string"}}}}}}],"x-examples":{"example":{"uuid":"56260b3d-c375-415c-b77a-75d99f717193","company_uuid":"7087a288-8349-4632-b92e-bc94fb79f29e","title":"Stage Hand","version":"d90440dd464601d1c8f4e9e240dfb7a6","employees":[{"uuid":"41199375-a999-4414-9f40-d9bf596b134d"}],"contractors":[{"uuid":"3488549f-60e4-494f-a34a-9d8aad3aabf5"}]},"example_created":{"uuid":"56260b3d-c375-415c-b77a-75d99f717193","company_uuid":"7087a288-8349-4632-b92e-bc94fb79f29e","title":"Stage Hand","version":"d90440dd464601d1c8f4e9e240dfb7a6","employees":[],"contractors":[]}}},"Department-List":{"type":"array","items":{"$ref":"#/components/schemas/Department"},"x-examples":{"example":[{"uuid":"56260b3d-c375-415c-b77a-75d99f717193","company_uuid":"7087a288-8349-4632-b92e-bc94fb79f29e","title":"Stage Hand","version":"d90440dd464601d1c8f4e9e240dfb7a6","employees":[{"uuid":"41199375-a999-4414-9f40-d9bf596b134d"}],"contractors":[]},{"uuid":"ec5c8a85-3233-4f39-a9f5-fb1ab7b5f5f3","company_uuid":"7087a288-8349-4632-b92e-bc94fb79f29e","title":"Actors","version":"34f39a30b45d077cb83aed2df4810d74","employees":[{"uuid":"7ee4aca1-814b-4034-b0f8-07f93cc679d1"}],"contractors":[]},{"uuid":"1802465d-4f68-4865-920c-1307ab095f12","company_uuid":"7087a288-8349-4632-b92e-bc94fb79f29e","title":"Band","version":"1fe3076d35ef7c97d0ae68c5f4df0acd","employees":[{"uuid":"a73955be-c009-44dc-915e-6246e2bdedbb"}],"contractors":[{"uuid":"3488549f-60e4-494f-a34a-9d8aad3aabf5"}]}]}},"Department-Create-Request-Body":{"type":"object","properties":{"title":{"type":"string","description":"Name of the department","example":"Stage Hand"}},"required":["title"]},"Department-Update-Request-Body":{"type":"object","allOf":[{"$ref":"#/components/schemas/Versionable-Required"},{"$ref":"#/components/schemas/Department-Create-Request-Body"}]},"Department-People-Request-Body":{"type":"object","allOf":[{"$ref":"#/components/schemas/Versionable-Required"},{"type":"object","properties":{"employees":{"type":"array","description":"Array of employees to add or remove from the department","items":{"type":"object","properties":{"uuid":{"type":"string"}}}},"contractors":{"type":"array","description":"Array of contractors to add or remove from the department","items":{"type":"object","properties":{"uuid":{"type":"string"}}}}}}]},"Child-Support-Data":{"description":"Child Support agency data","type":"object","properties":{"agencies":{"type":"array","description":"State child support agencies","items":{"type":"object","properties":{"state":{"type":"string","description":"Two letter state abbreviation"},"name":{"type":"string","description":"Name of state child support agency"},"manual_payment_required":{"type":"boolean","description":"Specifies if remitting payment to the agency is required outside of Gusto. If true, Gusto includes garnishment amounts for this agency in payroll calculation, but does not debit for or remit payment to the agency automatically. As of September 2024, only garnishments for South Carolina Integrated Child Support Services require manual payment. "},"fips_codes":{"type":"array","description":"FIPS codes for state or county child support orders","items":{"type":"object","properties":{"code":{"type":"string","description":"FIPS code for state or county"},"county":{"type":["string","null"],"description":"Name of county in the state for the corresponding FIPS code. When `null` the FIPS code applies state wide."}}}},"required_attributes":{"type":"array","description":"Describes which child support case identifying attributes are required for this agency. While most agencies only require a single identifier, some (e.g. OH) require multiple identifiers.","items":{"type":"object","properties":{"key":{"type":"string","description":"A required attribute when creating a garnishment for this state agency. The current values are listed as an enum; though unlikely, values could be added if state agency requirements change in the future.","enum":["case_number","order_number","remittance_number"]},"label":{"type":"string","description":"A human readable name of the attribute, e.g. CSE Case Number"}}}}}}}},"x-examples":{"Example":{"agencies":[{"state":"AK","name":"Alaska Child Support Services Division","manual_payment_required":false,"fips_codes":[{"county":null,"code":"0200000"}],"required_attributes":[{"key":"case_number","label":"CSE Case Number"}]},{"state":"OH","name":"Ohio Office of Child Support Enforcement","manual_payment_required":false,"fips_codes":[{"county":null,"code":"39000"}],"required_attributes":[{"key":"case_number","label":"CSE Case Number"},{"key":"order_number","label":"Order Identifier"}]}]}}},"Employee-Onboarding-Document":{"type":"object","description":"Configuration for which onboarding documents (e.g. Form I-9) are required for an employee during onboarding.","properties":{"uuid":{"type":["string","null"],"description":"The UUID of the onboarding documents config record. Null when no config has been saved yet.","readOnly":true},"i9_document":{"type":"boolean","description":"Whether to include Form I-9 for this employee during onboarding.\nWhen true, the employee will be prompted to complete Form I-9 as part of their onboarding.\n","readOnly":true}},"x-examples":{"config_with_i9":{"uuid":"7b1d0df1-6403-4a06-8768-c1dd7d24d27a","i9_document":true},"config_without_i9":{"uuid":"7b1d0df1-6403-4a06-8768-c1dd7d24d27a","i9_document":false},"config_not_yet_saved":{"uuid":null,"i9_document":false}}},"Employee-Onboarding-Documents-Config-Request":{"type":"object","description":"Request body for updating an employee's onboarding documents configuration.","properties":{"i9_document":{"type":"boolean","default":false,"description":"Whether to include Form I-9 for this employee during onboarding.\nWhen true, the employee will be prompted to complete Form I-9 as part of their onboarding.\n"}},"x-examples":{"enable_i9":{"i9_document":true},"disable_i9":{"i9_document":false}}},"I9-Authorization":{"type":"object","description":"An employee's I-9 authorization","properties":{"uuid":{"type":"string","description":"The UUID of the I-9 authorization","readOnly":true},"form_uuid":{"type":["string","null"],"description":"The UUID of the Form associated with this I-9 authorization. Use this with \"Employee Forms\" API endpoints.","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.","readOnly":true},"authorization_status":{"type":"string","description":"The employee's authorization status","enum":["citizen","noncitizen","permanent_resident","alien"]},"document_type":{"anyOf":[{"type":"string","enum":["uscis_alien_registration_number","form_i94","foreign_passport"]},{"type":"null"}],"description":"The document's document type"},"has_document_number":{"type":["boolean","null"],"description":"Whether or not a `document_number` exists for this document."},"expiration_date":{"type":["string","null"],"description":"The document's expiration date"},"country":{"type":["string","null"],"description":"The document's country of issuance"},"employer_signed":{"type":"boolean","description":"Whether the employer has signed the Form I-9","readOnly":true},"employee_signed":{"type":"boolean","description":"Whether the employee has signed the Form I-9","readOnly":true},"additional_info":{"type":["string","null"],"description":"Any additional notes"},"alt_procedure":{"type":["boolean","null"],"description":"Whether an alternative procedure authorized by DHS to examine documents was used"}},"required":["uuid","version","authorization_status","employer_signed","employee_signed"],"x-tags":["I-9 Verification"],"x-examples":{"alien_with_foreign_passport":{"uuid":"7f2337f9-9b78-44b9-aeed-be4777b833a8","version":"6ae7ff720107b356bf13b1606f60b24f","form_uuid":"c54046f7-1be4-4c54-8194-f4842c30c86d","authorization_status":"alien","document_type":"foreign_passport","has_document_number":true,"expiration_date":"2028-01-01","country":"Canada","employer_signed":false,"employee_signed":false,"additional_info":null,"alt_procedure":null},"citizen_authorization":{"uuid":"a12bc345-6789-4def-abcd-ef0123456789","version":"52b7c567242cb7393b2a206ed6a86afcb","form_uuid":null,"authorization_status":"citizen","document_type":null,"has_document_number":false,"expiration_date":null,"country":null,"employer_signed":false,"employee_signed":false,"additional_info":null,"alt_procedure":null},"employer_signed_authorization":{"uuid":"7f2337f9-9b78-44b9-aeed-be4777b833a8","version":"8bc7393b2a206ed6a86afcb4d00c1785","form_uuid":"c54046f7-1be4-4c54-8194-f4842c30c86d","authorization_status":"citizen","document_type":null,"has_document_number":false,"expiration_date":null,"country":null,"employer_signed":true,"employee_signed":true,"additional_info":"Additional info","alt_procedure":false}}},"I9-Authorization-Document":{"type":"object","description":"An employee's I-9 verification document","properties":{"uuid":{"type":"string","description":"The UUID of the I-9 verification document","readOnly":true},"document_type":{"type":"string","description":"The document's document type"},"document_title":{"type":"string","description":"The document's document title"},"expiration_date":{"type":["string","null"],"description":"The document's expiration date"},"issuing_authority":{"type":"string","description":"The document's issuing authority"}},"required":["uuid","document_type","document_title","issuing_authority"],"x-tags":["I-9 Verification"],"x-examples":{"driver_license":{"uuid":"7f2337f9-9b78-44b9-aeed-be4777b833a8","document_type":"driver_license","issuing_authority":"USA","expiration_date":"2027-01-01","document_title":"Driver's license"},"ssn_card":{"uuid":"9p2337f9-9b78-44b9-aeed-be4777b833a8","document_type":"ssn_card","issuing_authority":"USA","document_title":"Social Security card"}}},"I9-Authorization-Document-Option":{"type":"object","description":"An employee's I-9 verification document option based on the authorization status","properties":{"section":{"type":"string","description":"The document option's section in the list of acceptable documents on the Form I-9","readOnly":true,"enum":["A","A1","A2","A3","B","C"]},"description":{"type":"string","description":"The document option's description","readOnly":true},"document_type":{"type":"string","description":"The document option's document type","readOnly":true},"document_title":{"type":"array","description":"The document option's document titles","readOnly":true,"items":{"type":"string"}},"common_choice":{"type":"boolean","description":"Whether the document is a common choice for I-9 verification","readOnly":true}},"required":["section","description","document_type","document_title","common_choice"],"x-tags":["I-9 Verification"],"x-examples":{"example_a":{"section":"A","description":"Foreign passport","document_type":"foreign_passport_w_i94","document_title":["Foreign passport"],"common_choice":true},"example_b":{"section":"B","description":"Driver's license or state-issued ID card","document_type":"driver_license","document_title":["Driver's license","State ID card"],"common_choice":true},"example_c":{"section":"C","description":"Social Security card","document_type":"ssn_card","document_title":["Social Security card"],"common_choice":true}}},"I9-Authorization-Request-Body":{"description":"Request body for creating or updating an employee's I-9 authorization.","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. If supplied, this endpoint will update the existing I-9 authorization if it exists."},"authorization_status":{"type":"string","description":"The employee's authorization status.\n- `citizen`: A citizen is someone who was born in the United States or is a naturalized citizen living in the United States.\n- `noncitizen`: A noncitizen national is someone born in American Samoa, certain former citizens of the former Trust Territory of the Pacific Islands, and certain children of noncitizen nationals born abroad.\n- `permanent_resident`: A lawful permanent resident is someone who is not a US citizen and who resides under legally recognized and lawfully recorded permanent residence as an immigrant.\n- `alien`: Also referred to as a \"noncitizen authorized to work\". This includes anyone who is authorized to work in the United States but is not a US citizen, US national or lawful permanent resident.\n","enum":["citizen","noncitizen","permanent_resident","alien"]},"document_type":{"type":"string","description":"The type of document an employee holds, based on their authorization status.\n- This is unused for authorization status `citizen` or `noncitizen`.\n- If the authorization status is `permanent_resident`, this must be `uscis_alien_registration_number`.\n- If the authorization status is `alien`, this is required and may be any of the valid values.\n","enum":["uscis_alien_registration_number","form_i94","foreign_passport"]},"document_number":{"type":"string","description":"The document number. Formatting depends on the employee's document type.\n- For `document_type:'uscis_alien_registration_number'`, this must be a USCIS Number/A-Number, which is 7 to 9 digits.\n- For `document_type:'form_i94'`, this must be a Form I-94 Admission Number, which is 11 digits.\n- For `document_type:'foreign_passport'`, this must be the passport number.\n\nThis is required when the document type is present.\n"},"country":{"type":"string","description":"The document's country of issuance.\n\nThis is required when the document type is `foreign_passport`.\n"},"expiration_date":{"type":"string","description":"The document's expiration date.\n\nThis may only be used when the authorization status is `alien`.\n"}},"required":["authorization_status"],"x-examples":{"create_citizen":{"authorization_status":"citizen"},"update_alien_with_foreign_passport":{"version":"52b7c567242cb7393b2a206ed6a86afcb","authorization_status":"alien","document_type":"foreign_passport","document_number":"01234567","country":"Canada","expiration_date":"2028-01-01"}}},"I9-Authorization-Employer-Sign-Request-Body":{"description":"Request body for employer signing an employee's Form I-9.","type":"object","properties":{"signature_text":{"type":"string","description":"The signature"},"signer_title":{"type":"string","description":"The signer's job title"},"signed_by_ip_address":{"type":"string","description":"The IP address of the signatory who signed the form. Both IPv4 AND IPv6 are supported. You must provide the IP address with either this parameter OR you can leave out this parameter and set the IP address in the request header using the `x-gusto-client-ip` header instead."},"agree":{"type":"boolean","description":"Whether you agree to sign electronically"},"additional_info":{"type":"string","description":"Any additional notes"},"alt_procedure":{"type":"boolean","description":"Whether an alternative procedure authorized by DHS to examine documents was used"}},"required":["signature_text","signer_title","agree"],"x-examples":{"employer_sign":{"signature_text":"Jane Doe","signer_title":"Admin","signed_by_ip_address":"192.168.0.1","agree":true}}},"I9-Authorization-Documents-Request-Body":{"description":"Request body for creating an employee's I-9 authorization verification documents.","type":"object","properties":{"documents":{"type":"array","description":"An array of I-9 verification documents. Every request must contain the complete list of documents for the employee, as previous records are replaced.","items":{"type":"object","properties":{"document_type":{"type":"string","description":"The document type. Use the document options endpoint to get the possible values.","example":"us_passport"},"document_title":{"type":"string","description":"The document title associated with the document type","example":"US Passport"},"document_number":{"type":"string","description":"The document's document number","example":"F12345678"},"expiration_date":{"type":"string","description":"The document's expiration date","example":"2026-01-01"},"issuing_authority":{"type":"string","description":"The document's issuing authority","example":"USA"}},"required":["document_type","document_title","issuing_authority"]}}},"required":["documents"],"x-examples":{"create_documents":{"documents":[{"document_type":"us_passport","document_title":"US passport","document_number":"F12345678","expiration_date":"2035-04-01","issuing_authority":"US Department of State"}]}}},"Rehire-Body":{"type":"object","properties":{"effective_date":{"type":"string","description":"The day when the employee returns to work.","example":"2023-06-30"},"file_new_hire_report":{"type":"boolean","description":"The boolean flag indicating whether Gusto will file a new hire report for the employee."},"work_location_uuid":{"type":"string","description":"The uuid of the employee's work location.","example":"b6ae9d93-d4b8-4119-8c96-dba595dd8c30"},"employment_status":{"type":"string","description":"The employee's employment status. Supplying an invalid option will set the employment_status to *not_set*.","enum":["part_time","full_time","part_time_eligible","variable","seasonal","not_set"]},"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."}},"required":["effective_date","file_new_hire_report","work_location_uuid"]},"Fast-Payment-Limit-Param":{"type":"string","description":"Fast payment limit. This limit is an aggregate of all fast payrolls amount. This limit is only relevant when payment speed is 1-day or 2-day."},"Payment-Speed-Param":{"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.","enum":["1-day","2-day","4-day"]},"Fast-Payment-Limit-Required-Body":{"type":"object","properties":{"fast_payment_limit":{"$ref":"#/components/schemas/Fast-Payment-Limit-Param"},"payment_speed":{"$ref":"#/components/schemas/Payment-Speed-Param"}},"required":["fast_payment_limit"]},"Payment-Speed-Required-Body":{"type":"object","properties":{"fast_payment_limit":{"$ref":"#/components/schemas/Fast-Payment-Limit-Param"},"payment_speed":{"$ref":"#/components/schemas/Payment-Speed-Param"}},"required":["payment_speed"]},"Historical-Employee-Body":{"type":"object","description":"Request body for creating or updating a **historical employee**—someone who already separated from the company and must appear on year-to-date or tax filings without receiving ongoing payroll.\n\nSend this object under the JSON root key `employee`. All dates are ISO 8601 (`YYYY-MM-DD`). Use a `work_address.location_uuid` returned from your company locations API for an active work site.\n","properties":{"first_name":{"type":"string","description":"Legal first name as it appears on government-issued identification.","example":"Soren"},"middle_initial":{"type":"string","description":"Single middle initial, if any.","example":"A"},"last_name":{"type":"string","description":"Legal last name as it appears on government-issued identification.","example":"Kierkegaard"},"preferred_first_name":{"type":"string","description":"Preferred given name for display; omit when the same as legal first name.","example":"Angel"},"date_of_birth":{"type":"string","format":"date","description":"Date of birth (YYYY-MM-DD).","example":"1995-05-05"},"ssn":{"type":"string","pattern":"[0-9]{9}","description":"Nine-digit U.S. Social Security number **without** dashes or spaces. Must pass Gusto/SSA validation in production; use a valid test SSN in sandbox environments.\n","example":"123456294"},"work_address":{"type":"object","description":"Primary work location for this historical employment row.","required":["location_uuid"],"properties":{"location_uuid":{"type":"string","format":"uuid","description":"UUID of a company work location from the company locations response.","example":"1da85d35-1910-40a7-9c1f-8e2b3d4c5a6f"}}},"home_address":{"type":"object","description":"Residential address on file for tax withholding and compliance mail.","properties":{"street_1":{"type":"string","description":"Street address line 1.","example":"55 Mission St"},"street_2":{"type":["string","null"],"description":"Apartment, suite, unit, or building (optional).","example":"Floor 3"},"city":{"type":"string","description":"City.","example":"San Francisco"},"state":{"type":"string","description":"Two-letter U.S. state or territory postal abbreviation.","example":"CA"},"zip":{"type":"string","description":"ZIP or ZIP+4.","example":"94105"}},"required":["street_1","city","state","zip"]},"termination":{"type":"object","description":"End of the historical employment period.","required":["effective_date"],"properties":{"effective_date":{"type":"string","format":"date","description":"Last day of employment (termination date). This is recorded on the employment; use the calendar date the person stopped working for the company.","example":"2022-01-01"}}},"email":{"type":"string","format":"email","description":"Optional. When provided, stored on the employee record for notifications and profile.","example":"soren.kierkegaard@example.com"},"job":{"type":"object","description":"Hire date for the historical job used to build employments and filings.","required":["hire_date"],"properties":{"hire_date":{"type":"string","format":"date","description":"First calendar day the employee was employed in this role at the company.","example":"2020-01-01"}}},"employee_state_taxes":{"type":"object","description":"Workers' compensation fields for Washington (WA) or Wyoming (WY) when the work address is in those states; omit when not applicable.","properties":{"wc_covered":{"type":"boolean","description":"Whether this job is eligible for workers' compensation coverage in the states of Washington (WA) or Wyoming (WY).","example":true},"wc_class_code":{"type":"string","description":"The risk class code for workers' compensation in Washington or Wyoming state. For Washington, 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. For Wyoming you can search for the code online using [WY Workforce Services website](https://dws.wyo.gov/dws-division/workers-compensation/) or call the agency at (307) 235-3217.","example":"051000"}}}},"required":["first_name","last_name","date_of_birth","ssn","work_address","home_address","job","termination"],"x-examples":{"typical_historical_employee":{"first_name":"Soren","middle_initial":"A","last_name":"Kierkegaard","preferred_first_name":"Angel","date_of_birth":"1995-05-05","ssn":"123456294","email":"soren.kierkegaard@example.com","work_address":{"location_uuid":"1da85d35-1910-40a7-9c1f-8e2b3d4c5a6f"},"home_address":{"street_1":"55 Mission St","street_2":"Floor 3","city":"San Francisco","state":"CA","zip":"94105"},"job":{"hire_date":"2020-01-01"},"termination":{"effective_date":"2022-01-01"}}}},"Pay-Schedule-Assignment-Body":{"type":"object","properties":{"type":{"anyOf":[{"type":"string","enum":["single","hourly_salaried","by_employee","by_department"]},{"type":"null"}],"description":"The pay schedule assignment type."},"hourly_pay_schedule_uuid":{"type":"string","description":"Pay schedule for hourly employees."},"salaried_pay_schedule_uuid":{"type":"string","description":"Pay schedule for salaried employees."},"default_pay_schedule_uuid":{"type":"string","description":"Default pay schedule for employees."},"partial_assignment":{"type":"boolean","description":"Indicates whether the request provides pay schedule assignments for a partial list of employees or departments of the company. By default, this is set to false."},"employees":{"type":"array","description":"List of employees and their pay schedules.","items":{"type":"object","properties":{"employee_uuid":{"type":"string","description":"Employee UUID"},"pay_schedule_uuid":{"type":"string","description":"Pay schedule UUID"}}}},"departments":{"type":"array","description":"List of departments and their pay schedules.","items":{"type":"object","properties":{"department_uuid":{"type":"string","description":"Department UUID"},"pay_schedule_uuid":{"type":"string","description":"Pay schedule UUID"}}}}},"required":["type"]},"Form-Document-Content-Type-Type":{"type":["string","null"],"description":"The content type of the associated document. Most forms are PDFs with a content type of `application/pdf`. Some tax file packages will be zip files (containing PDFs) with a content type of `application/zip`. This attribute will be `null` when the document has not been prepared.","readOnly":true},"Form":{"title":"Form","type":"object","properties":{"uuid":{"type":"string","description":"The UUID of the form","readOnly":true},"employee_uuid":{"type":"string","description":"The UUID of the employee to which the form belongs, if applicable.","readOnly":true},"name":{"type":"string","description":"The type identifier of the form","readOnly":true},"title":{"type":"string","description":"The title of the form","readOnly":true},"description":{"type":"string","description":"The description of the form","readOnly":true},"draft":{"type":"boolean","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.","readOnly":true},"year":{"type":["integer","null"],"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.","readOnly":true},"quarter":{"type":["integer","null"],"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.","readOnly":true},"requires_signing":{"type":"boolean","description":"A boolean flag that indicates whether the form needs signing or not. Note that this value will change after the form is signed.","readOnly":true},"document_content_type":{"$ref":"#/components/schemas/Form-Document-Content-Type-Type"}},"x-examples":{"Example":{"uuid":"48cdd5ec-a4dd-4840-a424-ad79f38d8408","name":"company_direct_deposit","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.","draft":false,"year":null,"quarter":null,"requires_signing":true,"document_content_type":"application/pdf"},"employee_form":{"uuid":"48cdd5ec-a4dd-4840-a424-ad79f38d8408","employee_uuid":"c5fdae67-b148-4b52-8b33-1384024a1256","name":"w4_federal","title":"Form W-4: 2024","description":"Form W-4 determines how much federal income tax your employer will withhold from your pay.","draft":false,"year":2024,"quarter":null,"requires_signing":true,"document_content_type":"application/pdf"},"quarterly_tax_form":{"uuid":"7a2b9f3e-1c4d-4e5f-8a6b-2d3e4f5a6b7c","name":"form_941","title":"Form 941: Q2 2024","description":"Employer's Quarterly Federal Tax Return for the second quarter of 2024.","draft":false,"year":2024,"quarter":2,"requires_signing":false,"document_content_type":"application/pdf"},"sandbox_w2":{"uuid":"bf5b2496-26df-436e-b465-eae4ed5c8021","employee_uuid":"19394e76-a866-4570-b237-9a26b0163907","name":"US_W-2","title":"Draft Form W-2: 2021","description":"Form W-2 records your annual wages and taxes.","draft":true,"year":2021,"quarter":null,"requires_signing":false,"document_content_type":"application/pdf"}},"x-tags":["Forms"],"required":["uuid"]},"Form_1099":{"title":"Form","type":"object","properties":{"uuid":{"type":"string","description":"The UUID of the form","readOnly":true},"name":{"type":"string","description":"The type identifier of the form","readOnly":true},"title":{"type":"string","description":"The title of the form","readOnly":true},"description":{"type":"string","description":"The description of the form","readOnly":true},"draft":{"type":"boolean","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.","readOnly":true},"year":{"type":["integer","null"],"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.","readOnly":true},"quarter":{"type":["integer","null"],"description":"The quarter of this form. This value is currently always null since it is not present on any contractor forms.","readOnly":true},"requires_signing":{"type":"boolean","description":"A boolean flag that indicates whether the form needs signing or not. Note that this value will change after the form is signed.","readOnly":true},"document_content_type":{"$ref":"#/components/schemas/Form-Document-Content-Type-Type"},"contractor_uuid":{"type":"string","description":"The contractor UUID","readOnly":true}},"x-examples":{"Example":{"uuid":"48cdd5ec-a4dd-4840-a424-ad79f38d8408","name":"US_1099","title":"Form 1099: 2020","description":"Form 1099 records your annual income as a contractor.","draft":false,"requires_signing":false,"year":2020,"quarter":null,"document_content_type":"application/pdf","contractor_uuid":"123dd616-6dbc-4724-938a-403f6217a933"},"sandbox_1099":{"uuid":"29afb141-2256-431d-90e0-1c7344222342","contractor_uuid":"b68484a9-4487-4ee5-bafc-4245133a426c","name":"US_1099","title":"Form 1099: 2022","description":"Form 1099 records your annual income as a contractor.","draft":true,"requires_signing":false,"year":2022,"quarter":null,"document_content_type":"application/pdf"}},"x-tags":["Forms"],"required":["uuid"]},"Form-Pdf":{"title":"Form Pdf","type":"object","properties":{"uuid":{"type":"string","description":"the UUID of the form","readOnly":true},"document_url":{"type":["string","null"],"description":"the URL of the form"},"document_content_type":{"$ref":"#/components/schemas/Form-Document-Content-Type-Type"}},"x-examples":{"Example":{"uuid":"48cdd5ec-a4dd-4840-a424-ad79f38d8408","document_url":"https://app.gusto-demo.com/assets/forms/7757842065202782/original/form.pdf?1633667020","document_content_type":"application/pdf"},"document_not_ready":{"uuid":"48cdd5ec-a4dd-4840-a424-ad79f38d8408","document_url":null,"document_content_type":null}},"required":["uuid"]},"Document":{"title":"Document","type":"object","properties":{"uuid":{"type":"string","description":"The UUID of the document","readOnly":true},"title":{"type":"string","description":"The title of the document","readOnly":true},"name":{"type":"string","description":"The type identifier of the document","readOnly":true},"recipient_type":{"type":"string","description":"The type of recipient associated with the document (will be `Contractor` for Contractor Documents)","enum":["Company","Employee","Contractor"],"readOnly":true},"recipient_uuid":{"type":"string","description":"Unique identifier for the recipient associated with the document","readOnly":true},"pages":{"type":"array","description":"List of the document's pages and associated image URLs. This is only returned for documents with `required_signing` = `true`, and can be used for signing preparation.","items":{"type":"object","properties":{"image_url":{"type":"string","description":"Image URL for the page"},"page_number":{"type":"integer","description":"Page number"}}},"readOnly":true},"fields":{"type":"array","description":"List of the document's fields and associated data. Values are set for auto-filled fields. This is only returned for documents with `required_signing` = `true`, and can be used for signing preparation.","items":{"type":"object","properties":{"key":{"type":["string","null"],"description":"Unique identifier of the field. May be null for custom fields that do not correspond to a known Gusto-managed key mapping."},"value":{"type":["string","null"],"description":"Auto-filled value of the field"},"x":{"type":["integer","null"],"description":"X-coordinate location of the field on the page. May be null when the field has no positioning information."},"y":{"type":["integer","null"],"description":"Y-coordinate location of the field on the page. May be null when the field has no positioning information."},"width":{"type":["integer","null"],"description":"Width of the field. May be null when the field has no positioning information."},"height":{"type":["integer","null"],"description":"Height of the field. May be null when the field has no positioning information."},"page_number":{"type":["integer","null"],"description":"Page number of the field. May be null when the field has no positioning information."},"data_type":{"type":"string","description":"The field's data type"},"required":{"type":"boolean","description":"Whether the field is required"}}},"readOnly":true},"signed_at":{"type":["string","null"],"description":"When the document was signed (will be `null` if unsigned)","readOnly":true},"description":{"type":"string","description":"The description of the document","readOnly":true},"requires_signing":{"type":"boolean","description":"A boolean flag that indicates whether the document needs signing or not. Note that this value will change after the document is signed."},"draft":{"type":"boolean","description":"If the document is in a draft state","readOnly":true},"year":{"type":["integer","null"],"description":"The year of this document. This value is nullable and will not be present on all documents.","readOnly":true},"quarter":{"type":["integer","null"],"description":"The quarter of this document. This value is nullable and will not be present on all documents.","readOnly":true}},"x-examples":{"Example":{"uuid":"e83b3c20-dc4f-4382-bee3-b478fc42c68b","title":"Taxpayer Identification (Form W-9)","name":"taxpayer_identification_form_w_9","recipient_type":"Contractor","recipient_uuid":"f079c253-29e2-45e2-b384-2cc615c9c568","pages":[{"image_url":"http://app.gusto-dev.com:3000/assets/document_templates/20/unmapped_template/images/0.jpg","page_number":0},{"image_url":"http://app.gusto-dev.com:3000/assets/document_templates/20/unmapped_template/images/1.jpg","page_number":1}],"fields":[{"key":"text1596141656513","value":null,"x":69,"y":94,"width":261,"height":13,"page_number":0,"data_type":"text","required":true},{"key":"optional_text1596141704672","value":null,"x":69,"y":118,"width":262,"height":13,"page_number":0,"data_type":"text","required":false}],"signed_at":null,"description":"Form W-9, Request for Taxpayer Identification Number and Certification","requires_signing":true,"draft":false,"year":null,"quarter":null}},"x-tags":["Documents"]},"Document-Signed":{"title":"Document Signed","type":"object","properties":{"uuid":{"type":"string","description":"The UUID of the document","readOnly":true},"title":{"type":"string","description":"The title of the document","readOnly":true},"name":{"type":"string","description":"The type identifier of the document","readOnly":true},"recipient_type":{"type":"string","description":"The type of recipient associated with the document (will be `Contractor` for Contractor Documents)","enum":["Company","Employee","Contractor"],"readOnly":true},"recipient_uuid":{"type":"string","description":"Unique identifier for the recipient associated with the document","readOnly":true},"pages":{"type":"array","description":"List of the document's pages and associated image URLs.","items":{"type":"object","properties":{"image_url":{"type":"string","description":"Image URL for the page"},"page_number":{"type":"integer","description":"Page number"}}},"readOnly":true},"fields":{"type":"array","description":"List of the document's fields and associated data. Values reflect the data provided at signing.","items":{"type":"object","properties":{"key":{"type":["string","null"],"description":"Unique identifier of the field. May be null for custom fields that do not correspond to a known Gusto-managed key mapping."},"value":{"type":["string","null"],"description":"Value of the field"},"x":{"type":["integer","null"],"description":"X-coordinate location of the field on the page. May be null when the field has no positioning information."},"y":{"type":["integer","null"],"description":"Y-coordinate location of the field on the page. May be null when the field has no positioning information."},"width":{"type":["integer","null"],"description":"Width of the field. May be null when the field has no positioning information."},"height":{"type":["integer","null"],"description":"Height of the field. May be null when the field has no positioning information."},"page_number":{"type":["integer","null"],"description":"Page number of the field. May be null when the field has no positioning information."},"data_type":{"type":"string","description":"The field's data type"},"required":{"type":"boolean","description":"Whether the field is required"}}},"readOnly":true},"signed_at":{"type":["string","null"],"description":"When the document was signed (will be `null` if unsigned)","readOnly":true},"description":{"type":"string","description":"The description of the document","readOnly":true},"requires_signing":{"type":"boolean","description":"A boolean flag that indicates whether the document needs signing or not. Note that this value will change after the document is signed."},"draft":{"type":"boolean","description":"If the document is in a draft state","readOnly":true},"year":{"type":["integer","null"],"description":"The year of this document. This value is nullable and will not be present on all documents.","readOnly":true},"quarter":{"type":["integer","null"],"description":"The quarter of this document. This value is nullable and will not be present on all documents.","readOnly":true}},"x-examples":{"Example":{"uuid":"e83b3c20-dc4f-4382-bee3-b478fc42c68b","title":"Taxpayer Identification (Form W-9)","name":"taxpayer_identification_form_w_9","recipient_type":"Contractor","recipient_uuid":"f079c253-29e2-45e2-b384-2cc615c9c568","signed_at":"2024-09-03T16:39:22.000-07:00","description":"Form W-9, Request for Taxpayer Identification Number and Certification","requires_signing":false,"draft":false,"year":null,"quarter":null}},"x-tags":["Documents"]},"Document-Pdf":{"title":"Document Pdf","type":"object","properties":{"uuid":{"type":"string","description":"the UUID of the document","readOnly":true},"document_url":{"type":"string","description":"the URL of the document"}},"x-examples":{"Example":{"uuid":"e83b3c20-dc4f-4382-bee3-b478fc42c68b","document_url":"https://app.gusto-demo.com/assets/personal_documents/23/original.pdf?1724367941"}},"x-tags":["Documents"]},"Company-Industry-Selection-Required-Body":{"type":"object","properties":{"title":{"type":["string","null"],"example":"Computer Training","description":"Industry title"},"naics_code":{"type":"string","pattern":"^\\d{6}$","example":"611420","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."},"sic_codes":{"type":"array","description":"A list of Standard Industrial Classification (SIC) codes, which are four digit numbers 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`.","items":{"type":"string","pattern":"^\\d{4}$","example":"8243"}}},"required":["naics_code"]},"Industry":{"title":"Industry","type":"object","properties":{"company_uuid":{"type":"string","description":"Company UUID","readOnly":true},"title":{"type":["string","null"],"example":"Computer Training","description":"Industry title","readOnly":true},"naics_code":{"type":["string","null"],"example":"611420","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."},"sic_codes":{"type":"array","description":"A list of Standard Industrial Classification (SIC) codes, which are four digit numbers 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`.","items":{"type":"string","example":"8243"}}},"x-examples":{"Example":{"company_uuid":"423dd616-6dbc-4724-938a-403f6217a933","naics_code":"611420","sic_codes":["8243"],"title":"Computer Training"},"success_status":{"company_uuid":"423dd616-6dbc-4724-938a-403f6217a933","naics_code":"231208","sic_codes":["1500"],"title":"Construction"}},"x-tags":["Industry"]},"External-Payroll":{"description":"The representation of an external payroll.","type":"object","x-tags":["External Payrolls"],"title":"","properties":{"uuid":{"type":"string","description":"The UUID of the external payroll.","readOnly":true},"company_uuid":{"type":"string","description":"The UUID of the company.","readOnly":true},"check_date":{"type":"string","description":"External payroll's check date.","readOnly":true},"payment_period_start_date":{"type":"string","description":"External payroll's pay period start date.","readOnly":true},"payment_period_end_date":{"type":"string","description":"External payroll's pay period end date.","readOnly":true},"status":{"type":"string","enum":["unprocessed","processed"],"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.","readOnly":true},"external_payroll_items":{"type":"array","description":"External payroll items for employees","readOnly":true,"items":{"type":"object","properties":{"employee_uuid":{"type":"string"},"earnings":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"string","format":"float"},"hours":{"type":"string","format":"float"},"earning_type":{"type":"string"},"earning_id":{"type":"integer"}}}},"benefits":{"type":"array","items":{"type":"object","properties":{"benefit_id":{"type":"integer"},"company_contribution_amount":{"type":"string","format":"float"},"employee_deduction_amount":{"type":"string","format":"float"}}}},"taxes":{"type":"array","items":{"type":"object","properties":{"tax_id":{"type":"integer"},"amount":{"type":"string","format":"float"}}}}}}},"applicable_earnings":{"type":"array","description":"Applicable earnings based on company provisioning.","readOnly":true,"items":{"type":"object","properties":{"earning_type":{"type":"string"},"earning_id":{"type":"number"},"name":{"type":"string"},"input_type":{"type":"string"},"category":{"type":"string"}}}},"applicable_benefits":{"type":["array","null"],"description":"Applicable benefits based on company provisioning.","readOnly":true,"items":{"type":"object","properties":{"id":{"type":"integer"},"description":{"type":"string"},"active":{"type":"boolean"}}}},"applicable_taxes":{"type":"array","description":"Applicable taxes based on company provisioning.","readOnly":true,"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."}}}},"metadata":{"type":"object","description":"Stores metadata of the external payroll.","readOnly":true,"properties":{"deletable":{"type":"boolean","description":"Determines if the external payroll can be deleted.","readOnly":true}}}},"x-examples":{"Example":{"uuid":"c5fdae57-5483-4529-9aae-f0edceed92d4","company_uuid":"bcb305b0-2855-4025-8d22-e484a9e6b7c9","check_date":"2022-06-03","payment_period_start_date":"2022-05-15","payment_period_end_date":"2022-05-30","status":"unprocessed","external_payroll_items":[{"employee_uuid":"44f7cba9-7a3d-4f08-b7bd-6fcf5211f8ca","earnings":[{"amount":"10000.0","hours":"0.0","earning_type":"CompanyPayType","earning_id":1},{"amount":"500.0","hours":"0.0","earning_type":"CompanyEarningType","earning_id":4}],"benefits":[{"benefit_id":22,"company_contribution_amount":"100.0","employee_deduction_amount":"50.0"},{"benefit_id":25,"company_contribution_amount":"0.0","employee_deduction_amount":"300.0"}],"taxes":[{"tax_id":1,"amount":"400.0"},{"tax_id":2,"amount":"60.0"}]}],"applicable_earnings":[{"earning_type":"CompanyPayType","earning_id":1,"name":"Regular Wages","input_type":"amount","category":"default"},{"earning_type":"CompanyEarningType","earning_id":4,"name":"Cash Tips","input_type":"amount","category":"default"}],"applicable_benefits":[{"id":22,"description":"Kaiser","active":true},{"id":25,"description":"HSA","active":true}],"applicable_taxes":[{"id":1,"name":"Federal Income Tax","employer_tax":false,"resident_tax":false},{"id":2,"name":"Social Security","employer_tax":false,"resident_tax":false}],"metadata":{"deletable":true}}},"required":["uuid"]},"Webhook-Subscription":{"description":"The representation of webhook subscription.","type":"object","x-tags":["Webhooks"],"title":"","properties":{"uuid":{"type":"string","description":"The UUID of the webhook subscription.","readOnly":true},"url":{"type":"string","description":"The webhook subscriber URL. Updates will be POSTed to this URL.","readOnly":true},"status":{"type":"string","enum":["pending","verified","removed","unreachable"],"description":"The status of the webhook subscription.","readOnly":true},"subscription_types":{"type":"array","description":"Receive updates for these types.","readOnly":false,"items":{"type":"string","enum":["BankAccount","Company","CompanyBenefit","Contractor","ContractorPayment","Employee","EmployeeBenefit","EmployeeJobCompensation","ExternalPayroll","Form","Location","Notification","Payroll","PayrollSync","PaySchedule","Signatory","TimeOffRequest"]}}},"x-examples":{"Example":{"uuid":"c5fdae57-5483-4529-9aae-f0edceed92d4","url":"https://partner-app.com/subscriber","status":"verified","subscription_types":["BankAccount","Company","CompanyBenefit","Contractor","ContractorPayment","Employee","EmployeeBenefit","EmployeeJobCompensation","ExternalPayroll","Form","Location","Notification","Payroll","PayrollSync","PaySchedule","Signatory"]},"Pending":{"uuid":"a1b2c3d4-5678-90ab-cdef-1234567890ab","url":"https://partner-app.com/webhooks","status":"pending","subscription_types":["Company","Employee"]}},"required":["uuid"]},"Webhook-Verification-Token-Response":{"description":"The response from requesting a webhook subscription verification token.","type":"object","x-tags":["Webhooks"],"title":"","properties":{"message":{"type":"string","description":"A message indicating the verification token has been sent."}},"x-examples":{"Example":{"message":"Success! The subscriber will be notified with the verification token"}}},"External-Payroll-Basic":{"description":"The representation of an external payroll with minimal information.","type":"object","x-tags":["External Payrolls"],"title":"","properties":{"uuid":{"type":"string","description":"The UUID of the external payroll.","readOnly":true},"company_uuid":{"type":"string","description":"The UUID of the company.","readOnly":true},"check_date":{"type":"string","description":"External payroll's check date.","readOnly":true},"payment_period_start_date":{"type":"string","description":"External payroll's pay period start date.","readOnly":true},"payment_period_end_date":{"type":"string","description":"External payroll's pay period end date.","readOnly":true},"status":{"type":"string","enum":["unprocessed","processed"],"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.","readOnly":true}},"x-examples":{"Example":{"uuid":"c5fdae57-5483-4529-9aae-f0edceed92d4","company_uuid":"bcb305b0-2855-4025-8d22-e484a9e6b7c9","check_date":"2022-06-03","payment_period_start_date":"2022-05-15","payment_period_end_date":"2022-05-30","status":"unprocessed"}},"required":["uuid"]},"External-Payroll-Tax-Suggestions":{"description":"The representation of an external payroll with minimal information.","type":"object","x-tags":["External Payrolls"],"title":"","properties":{"employee_uuid":{"type":"string","description":"The UUID of the employee.","readOnly":true},"tax_suggestions":{"type":"array","description":"Possible tax liabilities selections.","readOnly":true,"items":{"type":"object","properties":{"tax_id":{"type":"integer","description":"The ID of the tax.","readOnly":true},"amount":{"type":"string","description":"Calculated tax amount.","readOnly":true}}}}},"x-examples":{"Example":{"employee_uuid":"d21848d5-446f-48a8-9430-30fbefeabda4","tax_suggestions":[{"tax_id":1,"amount":"500.0"},{"tax_id":2,"amount":"100.0"},{"tax_id":4,"amount":"30.0"}]}}},"Tax-Liabilities-Selections":{"description":"The representation of tax liabilities selections.","x-tags":["External Payrolls"],"title":"","type":"object","properties":{"tax_id":{"type":"integer","description":"The ID of the tax.","readOnly":true},"tax_name":{"type":"string","description":"The name of the tax.","readOnly":true},"description":{"type":["string","null"],"description":"A description of the tax, providing additional detail about the tax type.","readOnly":true},"last_unpaid_external_payroll_uuid":{"type":["string","null"],"description":"The UUID of last unpaid external payroll.","readOnly":true},"possible_liabilities":{"type":"array","description":"Possible tax liabilities selections.","readOnly":true,"items":{"type":"object","properties":{"liability_amount":{"type":"string","description":"Liability amount.","readOnly":true},"payroll_check_date":{"type":["string","null"],"description":"The external payroll check date.","readOnly":true},"external_payroll_uuid":{"type":["string","null"],"description":"The UUID of the external payroll.","readOnly":true}}}}},"x-examples":{"Example":{"tax_id":1,"tax_name":"Federal Income Tax","description":"Employee Federal Income Tax","last_unpaid_external_payroll_uuid":null,"possible_liabilities":[{"liability_amount":"0.0","payroll_check_date":null,"external_payroll_uuid":null},{"liability_amount":"3000.0","payroll_check_date":"2022-06-01","external_payroll_uuid":"1bf1efe1-72d4-4e6e-a181-611f3ea66435"}]}}},"External-Payroll-Create-Request":{"type":"object","description":"The request body for creating an external payroll.","x-tags":["External Payrolls"],"required":["check_date","payment_period_start_date","payment_period_end_date"],"properties":{"check_date":{"type":"string","format":"date","description":"The check date of the external payroll.","example":"2022-06-03"},"payment_period_start_date":{"type":"string","format":"date","description":"The start date of the external payroll payment period.","example":"2022-05-15"},"payment_period_end_date":{"type":"string","format":"date","description":"The end date of the external payroll payment period.","example":"2022-05-30"}}},"External-Payroll-Update-Request":{"type":"object","description":"The request body for updating an external payroll with employee payroll items.","x-tags":["External Payrolls"],"required":["external_payroll_items"],"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","description":"Payroll items for each employee in the external payroll.","items":{"type":"object","required":["employee_uuid"],"properties":{"employee_uuid":{"type":"string","format":"uuid","description":"The UUID of the employee.","example":"44f7cba9-7a3d-4f08-b7bd-6fcf5211f8ca"},"earnings":{"type":"array","description":"Earnings for the employee.","items":{"type":"object","properties":{"earning_type":{"type":"string","enum":["CompanyPayType","CompanyEarningType"],"description":"The earning type class name.","example":"CompanyPayType"},"earning_id":{"type":"integer","description":"The ID of the earning type.","example":1},"amount":{"type":"string","format":"float","description":"The earning amount in dollars.","example":"10000.00"},"hours":{"type":"string","format":"float","description":"The number of hours worked.","example":"80.0"}}}},"benefits":{"type":"array","description":"Benefits for the employee.","items":{"type":"object","properties":{"benefit_id":{"type":"integer","description":"The ID of the company benefit.","example":22},"company_contribution_amount":{"type":"string","format":"float","description":"The company contribution amount in dollars.","example":"100.00"},"employee_deduction_amount":{"type":"string","format":"float","description":"The employee deduction amount in dollars.","example":"50.00"}}}},"taxes":{"type":"array","description":"Taxes for the employee.","items":{"type":"object","properties":{"tax_id":{"type":"integer","description":"The ID of the tax.","example":1},"amount":{"type":"string","format":"float","description":"The tax amount in dollars.","example":"400.00"}}}}}}}}},"Tax-Liability-Selections-Request":{"type":"object","description":"The request body for updating tax liability selections.","x-tags":["External Payrolls"],"required":["liability_selections"],"properties":{"liability_selections":{"type":"array","description":"Tax liability selections to record for the company's external payrolls.","items":{"type":"object","required":["tax_id","last_unpaid_external_payroll_uuid","unpaid_liability_amount"],"properties":{"tax_id":{"type":"integer","description":"The ID of the tax.","example":1},"last_unpaid_external_payroll_uuid":{"type":["string","null"],"description":"The UUID of the last external payroll with an unpaid liability for this tax. Set to `null` to indicate no liability.","example":"1bf1efe1-72d4-4e6e-a181-611f3ea66435"},"unpaid_liability_amount":{"type":"string","format":"float","description":"The total cumulative unpaid liability amount for this tax across all external payrolls up to and including the one specified by `last_unpaid_external_payroll_uuid`.","example":"47.5"}}}}}},"Admin":{"title":"Admin","type":"object","description":"The representation of an admin user in Gusto.","x-examples":{"Example":{"uuid":"987058cc-23ee-46e9-81ef-5cee086cceca","first_name":"John","last_name":"Smith","email":"jsmith99@gmail.com","phone":"8009360383"}},"properties":{"uuid":{"type":"string","description":"The unique id of the admin."},"email":{"type":"string","description":"The email of the admin for Gusto's system."},"first_name":{"type":"string","description":"The first name of the admin."},"last_name":{"type":"string","description":"The last name of the admin."},"phone":{"type":["string","null"],"description":"The phone number of the admin."}},"x-tags":["Admins"],"required":["uuid"]},"Admin-Create-Request":{"type":"object","description":"The request body for creating a company admin.","required":["first_name","last_name","email"],"properties":{"first_name":{"type":"string","description":"The first name of the admin.","example":"John"},"last_name":{"type":"string","description":"The last name of the admin.","example":"Smith"},"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.","example":"jsmith99@gmail.com"}}},"Company":{"title":"Company","type":"object","description":"The representation of a company in Gusto.","properties":{"ein":{"type":"string","description":"The Federal Employer Identification Number of the company.","readOnly":true},"entity_type":{"description":"The tax payer type of the company.","anyOf":[{"type":"string","enum":["C-Corporation","S-Corporation","Sole proprietor","LLC","LLP","Limited partnership","Co-ownership","Association","Trusteeship","General partnership","Joint venture","Non-Profit"]},{"type":"null"}],"readOnly":true},"contractor_only":{"type":"boolean","description":"Whether the company only supports contractors."},"tier":{"type":["string","null"],"description":"The Gusto product tier of the company (not applicable to Embedded partner managed companies).","readOnly":true,"enum":["simple","plus","premium","core","complete","concierge","contractor_only","basic"]},"is_suspended":{"type":"boolean","description":"Whether or not the company is suspended in Gusto. Suspended companies may not run payroll."},"company_status":{"type":"string","description":"The status of the company in Gusto. \"Approved\" companies are approved to run payroll from a risk and compliance perspective. However, an approved company may still need to resolve other [payroll blockers](https://docs.gusto.com/embedded-payroll/docs/payroll-blockers) to be able to run payroll. \"Not Approved\" companies may not yet run payroll with Gusto and 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.","enum":["Approved","Not Approved","Suspended"],"readOnly":true},"uuid":{"type":"string","description":"A unique identifier of the company in Gusto.","readOnly":true},"name":{"type":"string","description":"The name of the company.","readOnly":true},"slug":{"type":"string","description":"The slug of the name of the company.","readOnly":true},"trade_name":{"type":["string","null"],"description":"The trade name of the company.","readOnly":true},"is_partner_managed":{"type":"boolean","description":"Whether the company is fully managed by a partner via the API","readOnly":true},"is_high_risk_business":{"type":"boolean","description":"Whether or not Gusto has identified the company as representing a high fraud risk.","readOnly":true},"is_marijuana_business":{"type":"boolean","description":"Whether or not the company is a marijuana-related business.","readOnly":true},"pay_schedule_type":{"anyOf":[{"type":"string","enum":["single","hourly_salaried","by_employee","by_department"]},{"type":"null"}],"description":"The pay schedule assignment type.","readOnly":true},"join_date":{"type":["string","null"],"description":"Company's first invoiceable event date","readOnly":true},"funding_type":{"description":"Company's default funding type","anyOf":[{"type":"string","enum":["ach","reverse_wire","wire_in","partner_disbursement","rtp","line_of_credit"]},{"type":"null"}]},"locations":{"type":"array","uniqueItems":false,"description":"The locations of the company.","items":{"$ref":"#/components/schemas/Company-Address"},"readOnly":true},"compensations":{"type":"object","description":"The available company-wide compensation rates for the company.","properties":{"hourly":{"type":"array","uniqueItems":true,"description":"The available hourly compensation rates for the company.","items":{"type":"object","properties":{"uuid":{"type":["string","null"],"description":"The UUID of the hourly compensation rate.","readOnly":true},"name":{"type":"string","description":"The name of the hourly compensation rate.","example":"Overtime","readOnly":true},"multiple":{"type":"number","description":"The amount multiplied by the base rate of a job to calculate compensation.","example":1.5,"readOnly":true}},"readOnly":true},"readOnly":true},"fixed":{"type":"array","uniqueItems":true,"description":"The available fixed compensation rates for the company.","items":{"type":"object","properties":{"uuid":{"type":["string","null"],"description":"The UUID of the fixed compensation.","readOnly":true},"name":{"type":"string","description":"The name of the fixed compensation.","example":"Bonus"}},"readOnly":true},"readOnly":true},"paid_time_off":{"type":"array","uniqueItems":true,"description":"The available types of paid time off for the company.","items":{"type":"object","properties":{"uuid":{"type":["string","null"],"description":"The UUID of the paid time off type.","readOnly":true},"name":{"type":"string","example":"Vacation Hours","description":"The name of the paid time off type.","readOnly":true}},"readOnly":true},"readOnly":true}},"readOnly":true},"primary_signatory":{"type":["object","null"],"description":"The primary signatory of the company.","properties":{"uuid":{"type":"string","readOnly":true,"description":"The UUID of the company's primary signatory."},"first_name":{"type":"string","readOnly":true,"description":"The company's primary signatory's first name."},"middle_initial":{"type":["string","null"],"readOnly":true,"description":"The company's primary signatory's middle initial."},"last_name":{"type":"string","readOnly":true,"description":"The company's primary signatory's last name."},"phone":{"type":"string","readOnly":true,"description":"The company's primary signatory's phone number."},"email":{"type":"string","readOnly":true,"description":"The company's primary signatory's email address."},"home_address":{"type":"object","properties":{"street_1":{"type":"string","readOnly":true},"street_2":{"type":["string","null"],"readOnly":true},"city":{"type":"string","readOnly":true},"state":{"type":"string","readOnly":true},"zip":{"type":"string","readOnly":true},"country":{"type":"string","readOnly":true}},"readOnly":true,"description":"The company's primary signatory's home address."}},"readOnly":true},"primary_payroll_admin":{"type":"object","description":"The primary payroll admin of the company.","properties":{"first_name":{"type":"string","readOnly":true,"description":"The company's primary payroll admin's first name."},"last_name":{"type":"string","readOnly":true,"description":"The company's primary payroll admin's last name."},"phone":{"type":["string","null"],"readOnly":true,"description":"The company's primary payroll admin's phone number."},"email":{"type":"string","readOnly":true,"description":"The company's primary payroll admin's email address."}}}},"x-examples":{"success_status":{"uuid":"c7a07c73-a703-4462-9343-1b181182b6e0","name":"Shoppe Studios LLC","trade_name":"Record Shoppe","is_partner_managed":true,"tier":"complete","locations":[{"street_1":"412 Kiera Stravenue","street_2":"Suite 391","city":"San Francisco","state":"CA","zip":"94107","country":"USA","active":true},{"street_1":"644 Fay Vista","street_2":"Suite 842","city":"Richmond","state":"VA","zip":"23218","country":"USA","active":true}],"ein":"00-0000001","entity_type":"C-Corporation","pay_schedule_type":"by_department","join_date":"2024-01-15","funding_type":"ach","slug":"shoppe-studios-llc","is_suspended":false,"company_status":"Approved","is_high_risk_business":false,"is_marijuana_business":false,"contractor_only":false,"compensations":{"hourly":[{"uuid":"7da6b57d-22f9-11f1-ad28-0242ac100003","name":"Overtime","multiple":1.5},{"uuid":"7da6b5ec-22f9-11f1-ad28-0242ac100003","name":"Double overtime","multiple":2},{"uuid":"7da6b22f-22f9-11f1-ad28-0242ac100003","name":"Regular","multiple":1},{"uuid":"7da6b3ac-22f9-11f1-ad28-0242ac100003","name":"Outstanding vacation","multiple":1},{"uuid":"7da6b532-22f9-11f1-ad28-0242ac100003","name":"Holiday","multiple":1},{"uuid":"7da6b44e-22f9-11f1-ad28-0242ac100003","name":"Emergency sick - self care","multiple":1},{"uuid":"7da6b49d-22f9-11f1-ad28-0242ac100003","name":"Emergency sick - caring for others","multiple":1},{"uuid":"7da6b4e6-22f9-11f1-ad28-0242ac100003","name":"FMLA Public Health Emergency Leave","multiple":1}],"fixed":[{"uuid":"7da68d82-22f9-11f1-ad28-0242ac100003","name":"Bonus"},{"uuid":"7da69024-22f9-11f1-ad28-0242ac100003","name":"Commission"},{"uuid":"7da69104-22f9-11f1-ad28-0242ac100003","name":"Paycheck Tips"},{"uuid":"7da6918f-22f9-11f1-ad28-0242ac100003","name":"Cash Tips"},{"uuid":"7da69216-22f9-11f1-ad28-0242ac100003","name":"Correction Payment"},{"uuid":"7da692a6-22f9-11f1-ad28-0242ac100003","name":"Severance"},{"uuid":"7da69356-22f9-11f1-ad28-0242ac100003","name":"Minimum Wage Adjustment"},{"uuid":null,"name":"Reimbursement"}],"paid_time_off":[{"uuid":"7dcdcb77-22f9-11f1-ad28-0242ac100003","name":"Vacation Hours"},{"uuid":"7dcdcc8b-22f9-11f1-ad28-0242ac100003","name":"Sick Hours"},{"uuid":null,"name":"Holiday Hours"}]},"primary_signatory":{"uuid":"2d7cd96f-e2fb-4db7-8c04-99ef531b4527","first_name":"Alda","middle_initial":"","last_name":"Carter","phone":"4160000000","email":"louie.hessel7757869450111547@zemlak.biz","home_address":{"street_1":"524 Roob Divide","street_2":"Suite 565","city":"San Francisco","state":"CA","zip":"94107","country":"USA"}},"primary_payroll_admin":{"first_name":"Ian","last_name":"Labadie","phone":"1-565-710-7559","email":"louie.hessel7757869450111547@zemlak.biz"}}},"x-tags":["Companies"],"required":["uuid"]},"Company-Onboarding-Status":{"description":"The representation of a company's onboarding status","type":"object","title":"","x-examples":{"Example":{"uuid":"c44d66dc-c41b-4a60-9e25-5e93ff8583f2","onboarding_completed":false,"onboarding_steps":[{"title":"Add Your Company's Addresses","id":"add_addresses","required":true,"completed":true,"completed_at":"2025-02-18T10:00:00Z","skippable":false,"requirements":[]},{"title":"Enter Your Federal Tax Information","id":"federal_tax_setup","required":true,"completed":true,"completed_at":"2025-02-18T10:00:00Z","skippable":false,"requirements":[]},{"title":"Select Industry","id":"select_industry","required":true,"completed":true,"completed_at":"2025-02-18T10:00:00Z","skippable":false,"requirements":[]},{"title":"Add Your Bank Account","id":"add_bank_info","required":true,"completed":true,"completed_at":"2025-02-18T10:00:00Z","skippable":false,"requirements":[]},{"title":"Add Your Employees","id":"add_employees","required":true,"completed":true,"completed_at":"2025-02-18T10:00:00Z","skippable":true,"requirements":["add_addresses"]},{"title":"Enter Your State Tax Information","id":"state_setup","required":true,"completed":false,"completed_at":null,"skippable":false,"requirements":["add_addresses","add_employees"]},{"title":"Select a Pay Schedule","id":"payroll_schedule","required":true,"completed":false,"completed_at":null,"skippable":false,"requirements":[]},{"title":"Sign Documents","id":"sign_all_forms","required":true,"completed":false,"completed_at":null,"skippable":false,"requirements":["add_employees","federal_tax_setup","state_setup","add_bank_info","payroll_schedule"]},{"title":"Verify Your Bank Account","id":"verify_bank_info","required":true,"completed":false,"completed_at":null,"skippable":false,"requirements":["add_bank_info"]}]}},"x-tags":["Companies"],"properties":{"uuid":{"type":"string","description":"the UUID of the company"},"onboarding_completed":{"type":"boolean","description":"a boolean flag for the company's onboarding status"},"onboarding_steps":{"type":"array","description":"a list of company onboarding steps","items":{"title":"Onboarding step","type":"object","properties":{"title":{"type":"string","description":"The display name of the onboarding step"},"id":{"type":"string","description":"The string identifier for each onboarding step","enum":["add_addresses","federal_tax_setup","select_industry","add_bank_info","add_employees","state_setup","payroll_schedule","sign_all_forms","verify_bank_info","external_payroll"]},"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."},"completed_at":{"type":["string","null"],"description":"The ISO 8601 timestamp indicating when the onboarding step was completed."},"skippable":{"type":"boolean","description":"The boolean flag indicating whether the step can be skipped or not."},"requirements":{"type":"array","description":"A list of onboarding steps that are required to be completed in order to proceed with the current onboarding step.","items":{"type":"string","enum":["add_addresses","federal_tax_setup","select_industry","add_bank_info","add_employees","state_setup","payroll_schedule","sign_all_forms","verify_bank_info","external_payroll"]}}}}}},"required":["uuid"]},"Payment-Configs":{"title":"Payment-Configs","type":"object","properties":{"company_uuid":{"type":"string","description":"Company uuid","readOnly":true},"partner_uuid":{"type":"string","description":"Partner uuid","readOnly":true},"fast_payment_limit":{"type":["string","null"],"description":"Payment limit for 1-day or 2-day payroll (string representation of decimal).","readOnly":true},"payment_speed":{"type":"string","enum":["1-day","2-day","4-day"],"description":"Payment speed. READ-ONLY.\n- `1-day`: Next-day ACH (only for partners that opt in).\n- `2-day`: Two-day ACH.\n- `4-day`: Standard ACH.\n","readOnly":true},"partner_owned_disbursement":{"type":"boolean","description":"Whether the company is configured to use the partner-owned disbursement payment rail","readOnly":true},"earned_fast_ach_blockers":{"type":"array","description":"Blockers preventing the company from earning fast ACH payments","readOnly":true,"items":{"type":"object","properties":{"blocker_type":{"type":"string","description":"The type of blocker","enum":["minimum_days","minimum_funded_payments"],"readOnly":true},"threshold":{"type":"number","description":"The threshold needed to unblock","readOnly":true}}}}},"x-examples":{"typical_payment_config":{"company_uuid":"423dd616-6dbc-4724-938a-403f6217a933","partner_uuid":"556f05d0-48e0-4c47-bce5-db9aea923043","fast_payment_limit":"5000.0","payment_speed":"2-day","partner_owned_disbursement":false,"earned_fast_ach_blockers":[]},"payment_config_with_blockers":{"company_uuid":"423dd616-6dbc-4724-938a-403f6217a933","partner_uuid":"556f05d0-48e0-4c47-bce5-db9aea923043","fast_payment_limit":null,"payment_speed":"2-day","partner_owned_disbursement":false,"earned_fast_ach_blockers":[{"blocker_type":"minimum_days","threshold":15},{"blocker_type":"minimum_funded_payments","threshold":5}]}},"x-tags":["Payment Configs"]},"Payment-Configs-Update-Request":{"type":"object","description":"Request body for updating company payment configs. At least one of payment_speed, fast_payment_limit, or partner_owned_disbursement is required.","properties":{"payment_configs":{"type":"object","properties":{"payment_speed":{"type":"string","enum":["1-day","2-day","4-day"],"description":"Desired payment speed. 1-day is only applicable to partners that opt in."},"fast_payment_limit":{"type":["number","null"],"description":"Payment limit for 1-day or 2-day payroll (in dollars)."},"partner_owned_disbursement":{"type":"boolean","description":"Whether to use the partner-owned disbursement payment rail."}}}},"x-examples":{"update_payment_speed_and_limit":{"payment_configs":{"payment_speed":"2-day","fast_payment_limit":1000}},"update_payment_speed_only":{"payment_configs":{"payment_speed":"4-day"}}}},"Contractor-Body":{"type":"object","properties":{"type":{"type":"string","description":"The contractor type.","default":"Individual","enum":["Individual","Business"]},"wage_type":{"type":"string","description":"The contractor’s wage type.\n","enum":["Fixed","Hourly"]},"start_date":{"type":"string","description":"The day when the contractor will start working for the company.\n","example":"2020-01-11"},"hourly_rate":{"type":"string","description":"The contractor’s hourly rate. This attribute is required if the wage_type is `Hourly`.","example":"40.0"},"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."},"email":{"type":"string","description":"The contractor’s email address."},"first_name":{"type":"string","description":"The contractor’s first name.\nThis attribute is required for `Individual` contractors and will be ignored for `Business` contractors."},"last_name":{"type":"string","description":"The contractor’s last name.\nThis attribute is required for `Individual` contractors and will be ignored for `Business` 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."},"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."},"work_state":{"type":["string","null"],"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."},"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."},"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."},"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."},"is_active":{"type":"boolean","description":"The status of the contractor. If the contractor's start date is in the future, updating this field to true means we are setting the start date to today. Attempting to deactivate a contractor while a dismissal is already scheduled, or reactivate while a rehire is already scheduled, will return a 422 error. Cancel the pending transition first using the appropriate cancel endpoint."}}},"Contractor-Update-Request-Body":{"description":"Request body for updating a contractor.","type":"object","allOf":[{"$ref":"#/components/schemas/Versionable-Required"},{"$ref":"#/components/schemas/Contractor-Body"}],"x-examples":{"update_individual_contractor":{"version":"b48c46abfed1487b873b442334b3c4ff","start_date":"2021-01-01","first_name":"Chanel","last_name":"Boyle","middle_initial":"X","wage_type":"Hourly","hourly_rate":"20.00","is_active":true},"update_business_contractor":{"version":"b48c46abfed1487b873b442334b3c4ff","start_date":"2020-01-11","business_name":"Contracting Solutions","ein":"991113334","wage_type":"Fixed","is_active":false}}},"Contractor-Create-Request-Body":{"description":"Request body for creating a contractor.","type":"object","required":["type","wage_type","start_date"],"allOf":[{"$ref":"#/components/schemas/Contractor-Body"}],"x-examples":{"create_individual_contractor":{"type":"Individual","wage_type":"Fixed","first_name":"Johnson","last_name":"Johnson","start_date":"2020-04-01","self_onboarding":true,"email":"johnson@johnson.com","file_new_hire_report":true,"work_state":"CA"},"create_business_contractor":{"type":"Business","wage_type":"Fixed","business_name":"Johnson-Johnson Contractors","start_date":"2020-04-01"}}},"Contractor-Onboarding-Status-Update-Request-Body":{"description":"Request body for updating a contractor's onboarding status.","type":"object","required":["onboarding_status"],"properties":{"onboarding_status":{"type":"string","description":"The updated onboarding status for the contractor.","enum":["admin_onboarding_incomplete","admin_onboarding_review","self_onboarding_not_invited","self_onboarding_invited","self_onboarding_started","self_onboarding_review","onboarding_completed"]}},"x-examples":{"update_onboarding_status":{"onboarding_status":"onboarding_completed"}}},"Contractor":{"description":"The representation of a contractor (individual or business) in Gusto.","type":"object","properties":{"uuid":{"type":"string","description":"The UUID of the contractor in Gusto.","readOnly":true},"company_uuid":{"type":"string","description":"The UUID of the company the contractor is employed by.","readOnly":true},"wage_type":{"type":"string","enum":["Fixed","Hourly"],"description":"The contractor's wage type, either \"Fixed\" or \"Hourly\"."},"is_active":{"type":"boolean","default":true,"description":"The status of the contractor with the company.","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."},"type":{"type":"string","enum":["Individual","Business"],"description":"The contractor's type, either \"Individual\" or \"Business\". "},"first_name":{"type":["string","null"],"description":"The contractor’s first name. This attribute is required for “Individual” contractors and will be ignored for “Business” contractors."},"last_name":{"type":["string","null"],"description":"The contractor’s last name. This attribute is required for “Individual” contractors and will be ignored for “Business” contractors."},"middle_initial":{"type":["string","null"],"description":"The contractor’s middle initial. This attribute is optional for “Individual” contractors and will be ignored for “Business” contractors."},"business_name":{"type":["string","null"],"description":"The name of the contractor business. This attribute is required for “Business” contractors and will be ignored for “Individual” contractors."},"ein":{"type":["string","null"],"description":"The Federal Employer Identification Number of the contractor business. This attribute is optional for “Business” contractors and will be ignored for “Individual” contractors."},"has_ein":{"type":["boolean","null"],"description":"Whether company's Employer Identification Number (EIN) is present"},"email":{"type":["string","null"],"description":"The contractor’s email address. This attribute is optional for “Individual” contractors and will be ignored for “Business” contractors. "},"start_date":{"type":"string","description":"The contractor's start date.","readOnly":true},"address":{"type":["object","null"],"description":"The contractor’s home address.","properties":{"street_1":{"type":"string","readOnly":true},"street_2":{"type":["string","null"],"readOnly":true},"city":{"type":"string","readOnly":true},"state":{"type":"string","readOnly":true},"zip":{"type":"string","readOnly":true},"country":{"type":"string","readOnly":true}},"readOnly":true},"hourly_rate":{"type":"string","example":"50.0","description":"The contractor’s hourly rate. This attribute is required if the wage_type is “Hourly”."},"file_new_hire_report":{"type":["boolean","null"],"description":"The boolean flag indicating whether Gusto will file a new hire report for the contractor"},"work_state":{"type":["string","null"],"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."},"onboarded":{"type":"boolean","description":"The updated onboarding status for the contractor"},"onboarding_status":{"type":"string","description":"One of the \"onboarding_status\" enum values.","enum":["admin_onboarding_incomplete","admin_onboarding_review","self_onboarding_not_invited","self_onboarding_invited","self_onboarding_started","self_onboarding_review","onboarding_completed"]},"payment_method":{"anyOf":[{"type":"string","enum":["Direct Deposit","Check"]},{"type":"null"}],"description":"The contractor's payment method."},"has_ssn":{"type":"boolean","description":"Indicates whether the contractor has an SSN in Gusto."},"department_uuid":{"type":["string","null"],"description":"The UUID of the department the contractor is under"},"department":{"type":["string","null"],"description":"The contractor's department in the company.","readOnly":true},"department_title":{"type":["string","null"],"description":"The title of the contractor's department.","readOnly":true},"dismissal_date":{"type":["string","null"],"description":"The contractor's dismissal date.","readOnly":true},"upcoming_employment":{"type":["object","null"],"description":"The contractor's upcoming employment details, if a rehire is scheduled.","readOnly":true,"properties":{"start_date":{"type":"string","description":"The start date of the upcoming employment."},"setup_status":{"type":["string","null"],"description":"The setup status of the upcoming employment."}}},"dismissal_cancellation_eligible":{"type":"boolean","description":"Whether the contractor's pending dismissal can be cancelled.","readOnly":true},"rehire_cancellation_eligible":{"type":"boolean","description":"Whether the contractor's pending rehire can be cancelled.","readOnly":true},"member_portal_invitation_status":{"type":["object","null"],"description":"Member portal invitation status information. Only included when the include param has the portal_invitations value set.","properties":{"status":{"type":"string","description":"The current status of the member portal invitation.","enum":["pending","sent","verified","complete","cancelled"]},"token_expired":{"type":["boolean","null"],"description":"Whether the invitation token has expired."},"welcome_email_sent_at":{"type":["string","null"],"format":"date-time","description":"The date and time when the welcome email was sent."},"last_password_resent_at":{"type":["string","null"],"format":"date-time","description":"The date and time when the password reset was last resent."}}},"partner_portal_invitation_sent":{"type":["boolean","null"],"description":"Whether an external partner portal invitation webhook has been sent for this contractor. Only included when the include param has the portal_invitations value set."}},"x-tags":["Contractors"],"required":["uuid"],"x-examples":{"Individual Contractor":{"uuid":"c9fc1ad3-c107-4e7b-aa21-2dd4b00a7a07","company_uuid":"b7457fec-3b76-43bb-9c6e-69cca4688942","wage_type":"Hourly","start_date":"2022-01-01","is_active":true,"version":"63859768485e218ccf8a449bb60f14ed","type":"Individual","first_name":"Kory","last_name":"Gottlieb","middle_initial":"P","business_name":null,"ein":null,"has_ein":false,"has_ssn":true,"department_uuid":"56260b3d-c375-415c-b77a-75d99f717193","email":"keira.west@mckenzie.org","file_new_hire_report":true,"work_state":"FL","onboarded":true,"onboarding_status":"onboarding_completed","address":{"street_1":"621 Jast Row","street_2":"Apt. 281","city":"Coral Springs","state":"FL","zip":"33065","country":"USA"},"hourly_rate":"60.00","payment_method":"Direct Deposit","department":"Engineering","department_title":"Engineering","dismissal_date":null,"upcoming_employment":null,"dismissal_cancellation_eligible":false,"rehire_cancellation_eligible":false,"member_portal_invitation_status":{"status":"sent","token_expired":false,"welcome_email_sent_at":"2024-01-15T14:30:00Z","last_password_resent_at":null},"partner_portal_invitation_sent":true},"Business Contractor":{"uuid":"c7c0659c-21a6-4b4e-b74c-9252576fc68c","company_uuid":"0ec4ae6e-e436-460d-b63c-94a14503d16f","wage_type":"Fixed","start_date":"2022-01-01","is_active":true,"version":"8aab307f1e8ed788697f8986346af559","type":"Business","first_name":null,"last_name":null,"middle_initial":null,"business_name":"Labadie-Stroman","ein":"XX-XXX0001","has_ein":true,"has_ssn":false,"email":"jonatan@kerluke.info","file_new_hire_report":false,"work_state":null,"onboarded":true,"onboarding_status":"onboarding_completed","address":{"street_1":"1625 Bednar Center","street_2":"Apt. 480","city":"Port Charlotte","state":"FL","zip":"33954","country":"USA"},"hourly_rate":"0.00","payment_method":"Direct Deposit","department_uuid":null,"department":null,"department_title":null,"dismissal_date":null,"upcoming_employment":null,"dismissal_cancellation_eligible":false,"rehire_cancellation_eligible":false,"member_portal_invitation_status":null,"partner_portal_invitation_sent":false}}},"Contractor-Onboarding-Status":{"description":"The representation of an contractor's onboarding status.","type":"object","title":"Contractor-Onboarding-Status","x-tags":["Contractor"],"x-examples":{"example":{"uuid":"bc57832c-d8bc-43a7-ae99-3a03380ff037","onboarding_status":"admin_onboarding_incomplete","onboarding_steps":[{"title":"Basic details","id":"basic_details","required":true,"completed":false,"requirements":[]},{"title":"Enter compensation details","id":"compensation_details","required":true,"completed":false,"requirements":[]},{"title":"Add an address","id":"add_address","required":true,"completed":false,"requirements":[]},{"title":"Payment details","id":"payment_details","required":true,"completed":false,"requirements":[]},{"title":"Sign and acknowledge documents","id":"sign_documents","required":false,"completed":false,"requirements":["basic_details","add_address"]},{"title":"File new hire report","id":"file_new_hire_report","required":false,"completed":false,"requirements":["basic_details"]}]}},"properties":{"uuid":{"type":"string","description":"Unique identifier for this contractor."},"onboarding_status":{"type":"string","description":"One of the \"onboarding_status\" enum values.","enum":["onboarding_completed","admin_onboarding_review","admin_onboarding_incomplete","self_onboarding_not_invited","self_onboarding_invited","self_onboarding_started","self_onboarding_review"]},"onboarding_steps":{"type":"array","description":"List of steps required to onboard a contractor.","items":{"title":"Onboarding step","type":"object","properties":{"title":{"type":"string","description":"User-friendly description of the onboarding step."},"id":{"type":"string","description":"String identifier for 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","description":"A list of onboarding steps required to begin this step.","items":{"type":"string"}}}}}},"required":["uuid"]},"Contractor-Payment":{"description":"The representation of a single contractor payment.","type":"object","x-examples":{"success_status":{"uuid":"04552eb9-7829-4b18-ae96-6983552948df","contractor_uuid":"bc57832c-d8bc-43a7-ae99-3a03380ff037,","bonus":"20.0","date":"2020-10-19","hours":"40.0","payment_method":"Direct Deposit","reimbursement":"100.0","hourly_rate":"18.0","may_cancel":true,"status":"Funded","wage":"0.0","wage_type":"Hourly","wage_total":"740.00"},"example":{"uuid":"04552eb9-7829-4b18-ae96-6983552948df","contractor_uuid":"bc57832c-d8bc-43a7-ae99-3a03380ff037","bonus":"20.0","date":"2020-10-19","hours":"40.0","payment_method":"Direct Deposit","reimbursement":"100.0","hourly_rate":"18.0","may_cancel":false,"status":"Funded","wage":"0.0","wage_type":"Hourly","wage_total":"740.00"}},"title":"Contractor Payment","properties":{"uuid":{"type":"string","description":"The unique identifier of the contractor payment in Gusto.","readOnly":true},"contractor_uuid":{"type":"string","description":"The UUID of the contractor.","readOnly":true},"bonus":{"type":"string","format":"float","description":"The bonus amount in the payment.","readOnly":true},"date":{"type":"string","description":"The payment date.","readOnly":true},"hours":{"type":"string","format":"float","description":"The number of hours worked for the payment.","readOnly":true},"payment_method":{"type":"string","description":"The payment method.","enum":["Direct Deposit","Check","Historical Payment","Correction Payment"],"readOnly":true},"reimbursement":{"type":"string","format":"float","description":"The reimbursement amount in the payment.","readOnly":true},"status":{"type":"string","description":"Contractor payment status","enum":["Funded","Unfunded"]},"hourly_rate":{"type":"string","format":"float","description":"The rate per hour worked for the payment.","readOnly":true},"may_cancel":{"type":"boolean","description":"Determine if the contractor payment can be cancelled.","readOnly":true},"wage":{"type":"string","format":"float","description":"The fixed wage of the payment, regardless of hours worked.","readOnly":true},"wage_type":{"type":"string","description":"The wage type for the payment.","enum":["Hourly","Fixed"],"readOnly":true},"wage_total":{"type":"string","format":"float","description":"(hours * hourly_rate) + wage + bonus","readOnly":true},"invoice_number":{"type":["string","null"],"description":"An optional invoice number associated with this contractor payment. This will be visible to the contractor on their paystub. Maximum 25 characters.","readOnly":true},"memo":{"type":["string","null"],"description":"An optional note or memo for this contractor payment. This will be visible to the contractor on their paystub.","readOnly":true}},"x-tags":["Contractor Payments"],"required":["uuid"]},"Contractor-Payment-Listing":{"description":"The representation of a contractor payment as it appears in a contractor's payment history.","type":"object","x-examples":{"success_status":{"uuid":"04552eb9-7829-4b18-ae96-6983552948df","check_date":"2020-06-15","bonus":"20.0","hours":"40.0","hourly_rate":"18.0","payment_method":"Direct Deposit","reimbursement":"100.0","status":"Funded","wage":"0.0","wage_type":"Hourly","wage_total":"740.00"}},"title":"Contractor Payment Listing","properties":{"uuid":{"type":"string","description":"The unique identifier of the contractor payment in Gusto.","readOnly":true},"check_date":{"type":"string","format":"date","description":"The check date for the payment.","readOnly":true},"bonus":{"type":"string","format":"float","description":"The bonus amount in the payment.","readOnly":true},"hours":{"type":"string","format":"float","description":"The number of hours worked for the payment.","readOnly":true},"hourly_rate":{"type":"string","format":"float","description":"The rate per hour worked for the payment.","readOnly":true},"payment_method":{"type":"string","description":"The payment method.","enum":["Direct Deposit","Check","Historical Payment","Correction Payment"],"readOnly":true},"reimbursement":{"type":"string","format":"float","description":"The reimbursement amount in the payment.","readOnly":true},"status":{"type":"string","description":"Contractor payment status","enum":["Funded","Unfunded"]},"wage":{"type":"string","format":"float","description":"The fixed wage of the payment, regardless of hours worked.","readOnly":true},"wage_type":{"type":"string","description":"The wage type for the payment.","enum":["Hourly","Fixed"],"readOnly":true},"wage_total":{"type":"string","format":"float","description":"(hours * hourly_rate) + wage + bonus","readOnly":true}},"x-tags":["Contractor Payments"],"required":["uuid"]},"Contractor-Payment-Body":{"description":"Request body for creating a contractor payment.","type":"object","required":["contractor_uuid","date"],"properties":{"contractor_uuid":{"type":"string","description":"The contractor receiving the payment."},"date":{"type":"string","format":"date","description":"Date of contractor payment.","example":"2020-01-01"},"payment_method":{"type":"string","enum":["Direct Deposit","Check","Historical Payment"],"default":"Direct Deposit"},"wage":{"type":"string","format":"float","description":"If the contractor is on a fixed wage, this is the fixed wage payment for the contractor, regardless of hours worked.","example":"5000"},"hours":{"type":"string","format":"float","description":"If the contractor is on an hourly wage, this is the number of hours that the contractor worked for the payment.","example":"40"},"bonus":{"type":"string","format":"float","description":"If the contractor is on an hourly wage, this is the bonus the contractor earned.","example":"500"},"reimbursement":{"type":"string","format":"float","description":"Reimbursed wages for the contractor.","example":"20"},"invoice_number":{"type":"string","description":"An optional invoice number to associate with this contractor payment. This will be visible to the contractor on their paystub. Maximum 25 characters.","maxLength":25,"example":"INV-001"},"memo":{"type":"string","description":"An optional note or memo for this contractor payment. This will be visible to the contractor on their paystub.","example":"Payment for consulting services"}},"x-tags":["Contractor Payments"]},"Contractor-Payments-Preview-Body":{"description":"Request body for previewing contractor payments. The expected debit date for the payments is calculated from the provided check date and the company's ACH speed.","type":"object","required":["contractor_payments"],"properties":{"contractor_payments":{"type":"array","description":"A list of contractor payments to preview.","items":{"type":"object","properties":{"contractor_uuid":{"type":"string","description":"The contractor receiving the payment."},"date":{"type":"string","description":"Date of the contractor payment (check date)."},"payment_method":{"type":"string","enum":["Direct Deposit","Check","Historical Payment"],"description":"The payment method."},"wage":{"type":"integer","description":"Fixed wage amount for the payment."},"hours":{"type":"integer","description":"Number of hours worked for the payment."},"hourly_rate":{"type":"integer","description":"Hourly rate for the payment."},"bonus":{"type":"integer","description":"Bonus amount for the payment."},"reimbursement":{"type":"integer","description":"Reimbursement amount for the payment."}}}}},"x-examples":{"Example":{"contractor_payments":[{"bonus":0,"date":"2022-09-02","contractor_uuid":"5376e95b-cca0-482b-bb81-aba5e360eb04","hours":0,"payment_method":"Check","reimbursement":0,"wage":123,"hourly_rate":0},{"bonus":0,"date":"2022-09-02","contractor_uuid":"0c984dce-de9a-47db-8bfb-5f0c823afe6f","hours":0,"payment_method":"Check","reimbursement":0,"wage":456,"hourly_rate":0}]}},"x-tags":["Contractor Payments"]},"Contractor-Payments-Preview":{"type":"object","description":"The expected debit date computed for a set of previewed contractor payments.","properties":{"expected_debit_date":{"type":"string","format":"date","description":"The calculated debit date. If the payment method is Direct Deposit, the debit date will account for the company's ACH speed. If the payment method is Check, the debit date will be the same as the check date."}},"x-examples":{"example":{"expected_debit_date":"2022-08-16"}},"x-tags":["Contractor Payments"]},"Contractor-Payment-Group":{"description":"The full contractor payment group, including associated contractor payments.","type":"object","allOf":[{"$ref":"#/components/schemas/Contractor-Payment-Group-Base"},{"type":"object","properties":{"partner_owned_disbursement":{"type":["boolean","null"],"description":"Whether the disbursement is partner owned.","readOnly":true},"submission_blockers":{"type":"array","description":"List of submission blockers for the contractor payment group.","readOnly":true,"items":{"$ref":"#/components/schemas/Payroll-Submission-Blocker-Type"}},"credit_blockers":{"type":"array","description":"List of credit blockers for the contractor payment group.","readOnly":true,"items":{"$ref":"#/components/schemas/Payroll-Credit-Blocker-Type"}},"totals":{"type":"object","properties":{"amount":{"type":"string","description":"The total amount for the group of contractor payments.","readOnly":true},"debit_amount":{"type":"string","description":"The total debit amount for the group of contractor payments. Sum of wage & reimbursement amount.","readOnly":true},"wage_amount":{"type":"string","description":"The total wage amount for the group of contractor payments.","readOnly":true},"reimbursement_amount":{"type":"string","description":"The total reimbursement amount for the group of contractor payments.","readOnly":true},"check_amount":{"type":"string","description":"The total check amount for the group of contractor payments.","readOnly":true}},"readOnly":true},"contractor_payments":{"type":"array","items":{"$ref":"#/components/schemas/Contractor-Payment-For-Group"}}}}],"x-examples":{"success":{"uuid":"f693e034-d833-46e3-88d4-2c820c383c57","company_uuid":"c54046f7-1be4-4c54-8194-f4842c30c86d","check_date":"2024-05-07","debit_date":"2024-05-01","status":"Unfunded","creation_token":"45ef81bb-ae24-4ad1-b2c6-6e563a4c30ed","contractor_payments":[{"uuid":"630dc982-f498-4ebc-a6dc-4d76711027ce","contractor_uuid":"2e6d0970-31bf-47ce-bdb4-713e4207ecf4","bonus":"0.0","hours":"40.0","hourly_rate":"18.0","may_cancel":false,"payment_method":"Direct Deposit","reimbursement":"75.0","status":"Unfunded","wage":"0.0","wage_type":"Hourly","wage_total":"720.0"},{"uuid":"12f51eba-d653-4357-8c05-1f1f8d0fd5e3","contractor_uuid":"a975fda0-fcf5-469a-a5fd-06e43d1cd99d","bonus":"0.0","hours":"0.0","hourly_rate":"0.0","may_cancel":false,"payment_method":"Check","reimbursement":"0.0","status":"Unfunded","wage":"1500.0","wage_type":"Fixed","wage_total":"1500.0"}],"totals":{"amount":"2295.0","debit_amount":"2295.0","wage_amount":"2220.0","reimbursement_amount":"75.0"}},"With submission blockers":{"uuid":"5ec3b582-7d04-4397-be1e-f0e79d00e1b7","company_uuid":"4a39b249-1e22-4fc9-a40f-cb07d2ab394e","check_date":"2025-08-21","debit_date":"2025-08-19","status":"Unfunded","creation_token":"5ec3b582-7d04-4397-be1e-f0e79d00e1b7","partner_owned_disbursement":false,"submission_blockers":[{"blocker_type":"fast_ach_threshold_exceeded","blocker_name":"Fast ACH Threshold Exceeded","selected_option":"wire_in","status":"resolved","unblock_options":[{"unblock_type":"wire_in","check_date":"2025-08-21","metadata":{"wire_in_deadline":"2025-08-21T18:00:00Z","wire_in_amount":"760000.0"}},{"unblock_type":"move_to_four_day","check_date":"2025-08-21","metadata":{"debit_date":"2025-08-15"}}]}],"credit_blockers":[{"blocker_type":"waiting_for_wire_in","blocker_name":"Waiting for Wire In","selected_option":"submit_wire","status":"unresolved","unblock_options":[{"unblock_type":"submit_wire","check_date":"2025-08-21","metadata":{"wire_in_deadline":"2025-08-21T18:00:00Z","wire_in_amount":"760000.0","wire_in_request_uuid":"7a31fef8-46c6-4114-9677-214b7a3cb532"}}]}],"contractor_payments":[{"uuid":"ca8c7899-c2dc-40bb-8b7e-08c1309f5135","contractor_uuid":"b4c6cd3c-4b45-4738-ad40-3da45b29a765","bonus":"0.0","hours":"0.0","hourly_rate":"0.0","may_cancel":false,"payment_method":"Direct Deposit","reimbursement":"750000.0","status":"Unfunded","wage":"10000.0","wage_type":"Fixed","wage_total":"10000.0"}],"totals":{"amount":"760000.00","debit_amount":"760000.00","wage_amount":"10000.00","reimbursement_amount":"750000.00","check_amount":"0.00"}}},"x-tags":["Contractor Payment Groups"]},"Contractor-Payment-Group-Base":{"description":"Base properties for contractor payment groups.","type":"object","properties":{"uuid":{"type":"string","description":"The unique identifier of the contractor payment group.","readOnly":true},"company_uuid":{"type":"string","description":"The UUID of the company.","readOnly":true},"check_date":{"type":"string","description":"The check date of the contractor payment group.","readOnly":true},"debit_date":{"type":"string","description":"The debit date of the contractor payment group.","readOnly":true},"status":{"type":"string","description":"The status of the contractor payment group.  Will be `Funded` if all payments that should be funded (i.e. have `Direct Deposit` for payment method) are funded.  A group can have status `Funded` while having associated payments that have status `Unfunded`, i.e. payment with `Check` payment method.","enum":["Unfunded","Funded"],"readOnly":true},"creation_token":{"type":["string","null"],"description":"Token used to make contractor payment group creation idempotent.  Will error if attempting to create a group with a duplicate token.","readOnly":true}}},"Contractor-Payment-Group-With-Blockers":{"description":"Contractor payment group with submission and credit blockers, but without individual contractor payments.","type":"object","allOf":[{"$ref":"#/components/schemas/Contractor-Payment-Group-Base"},{"type":"object","properties":{"partner_owned_disbursement":{"type":["boolean","null"],"description":"Whether the disbursement is partner owned.","readOnly":true},"submission_blockers":{"type":"array","description":"List of submission blockers for the contractor payment group.","readOnly":true,"items":{"$ref":"#/components/schemas/Payroll-Submission-Blocker-Type"}},"credit_blockers":{"type":"array","description":"List of credit blockers for the contractor payment group.","readOnly":true,"items":{"$ref":"#/components/schemas/Payroll-Credit-Blocker-Type"}},"totals":{"type":"object","properties":{"amount":{"type":"string","description":"The total amount for the group of contractor payments.","readOnly":true},"debit_amount":{"type":"string","description":"The total debit amount for the group of contractor payments. Sum of wage & reimbursement amount.","readOnly":true},"wage_amount":{"type":"string","description":"The total wage amount for the group of contractor payments.","readOnly":true},"reimbursement_amount":{"type":"string","description":"The total reimbursement amount for the group of contractor payments.","readOnly":true},"check_amount":{"type":"string","description":"The total check amount for the group of contractor payments.","readOnly":true}},"readOnly":true}}}],"x-examples":{"success":{"uuid":"94d9698e-9c95-45d6-b66e-d208258666ab","company_uuid":"5f5aaa38-f517-4f56-85e4-afdb83321663","check_date":"2025-09-22","debit_date":"2025-09-18","status":"Unfunded","creation_token":"94d9698e-9c95-45d6-b66e-d208258666ab","partner_owned_disbursement":false,"submission_blockers":[{"blocker_type":"fast_ach_threshold_exceeded","blocker_name":"Fast ACH Threshold Exceeded","selected_option":"wire_in","status":"resolved","unblock_options":[{"unblock_type":"wire_in","check_date":"2025-09-22","metadata":{"wire_in_deadline":"2025-09-22T18:00:00Z","wire_in_amount":"760000.0"}},{"unblock_type":"move_to_four_day","check_date":"2025-09-22","metadata":{"debit_date":"2025-09-16"}}]}],"credit_blockers":[{"blocker_type":"waiting_for_wire_in","blocker_name":"Waiting for Wire In","selected_option":"submit_wire","status":"unresolved","unblock_options":[{"unblock_type":"submit_wire","check_date":"2025-09-22","metadata":{"wire_in_deadline":"2025-09-22T18:00:00Z","wire_in_amount":"760000.0","wire_in_request_uuid":"96ea4784-979a-45aa-9ccb-83be86b6dcea"}}]}],"totals":{"amount":"760000.00","debit_amount":"760000.00","wage_amount":"10000.00","reimbursement_amount":"750000.00","check_amount":"0.00"}}},"x-tags":["Contractor Payment Groups"]},"Contractor-Payment-Group-Minimal":{"description":"The summary of a contractor payment group.","type":"object","allOf":[{"$ref":"#/components/schemas/Contractor-Payment-Group-Base"},{"type":"object","properties":{"totals":{"type":"object","properties":{"amount":{"type":"string","description":"The total amount for the group of contractor payments.","readOnly":true},"debit_amount":{"type":"string","description":"The total debit amount for the group of contractor payments. Sum of wage & reimbursement amount.","readOnly":true},"wage_amount":{"type":"string","description":"The total wage amount for the group of contractor payments.","readOnly":true},"reimbursement_amount":{"type":"string","description":"The total reimbursement amount for the group of contractor payments.","readOnly":true}},"readOnly":true}}}],"x-examples":{"success":[{"uuid":"7f2337f9-9b78-44b9-aeed-be4777b833a8","company_uuid":"c54046f7-1be4-4c54-8194-f4842c30c86d","check_date":"2024-03-15","debit_date":"2024-03-11","status":"Funded","creation_token":"a51a3500-3200-43af-a738-169d4b66a9db","totals":{"debit_amount":"740.00","wage_amount":"720.00","reimbursement_amount":"20.00"}},{"uuid":"56260b3d-c375-415c-b77a-75d99f717193","company_uuid":"c54046f7-1be4-4c54-8194-f4842c30c86d","check_date":"2024-05-02","debit_date":"2024-04-26","status":"Unfunded","creation_token":"45ef81bb-ae24-4ad1-b2c6-6e563a4c30ed","totals":{"debit_amount":"2365.00","wage_amount":"2270.00","reimbursement_amount":"95.00"}}]},"x-tags":["Contractor Payment Groups"]},"Contractor-Payment-For-Group":{"description":"The representation of a single contractor payment.","type":"object","properties":{"uuid":{"type":"string","description":"The unique identifier of the contractor payment in Gusto.","readOnly":true},"contractor_uuid":{"type":"string","description":"The UUID of the contractor.","readOnly":true},"bonus":{"type":"string","description":"The bonus amount in the payment.","readOnly":true},"hours":{"type":"string","description":"The number of hours worked for the payment.","readOnly":true},"payment_method":{"type":"string","description":"The payment method.","enum":["Direct Deposit","Check","Historical Payment","Correction Payment"],"readOnly":true},"reimbursement":{"type":"string","description":"The reimbursement amount in the payment.","readOnly":true},"status":{"type":"string","description":"The status of the contractor payment.  Will transition to `Funded` during payments processing if the payment should be funded, i.e. has `Direct Deposit` for payment method. Contractors payments with `Check` payment method will remain `Unfunded`.","enum":["Funded","Unfunded"]},"hourly_rate":{"type":"string","description":"The rate per hour worked for the payment.","readOnly":true},"may_cancel":{"type":"boolean","description":"Determine if the contractor payment can be cancelled.","readOnly":true},"wage":{"type":"string","description":"The fixed wage of the payment, regardless of hours worked.","readOnly":true},"wage_type":{"type":"string","description":"The wage type for the payment.","enum":["Hourly","Fixed"],"readOnly":true},"wage_total":{"type":"string","description":"(hours * hourly_rate) + wage + bonus","readOnly":true},"invoice_number":{"type":["string","null"],"description":"An optional invoice number associated with this contractor payment. This will be visible to the contractor on their paystub. Maximum 25 characters.","readOnly":true},"memo":{"type":["string","null"],"description":"An optional note or memo for this contractor payment. This will be visible to the contractor on their paystub.","readOnly":true}},"x-tags":["Contractor Payment Groups"]},"Contractor-Payment-For-Group-Preview":{"description":"Preview representation of a single contractor payment with nullable uuid.","type":"object","properties":{"uuid":{"type":["string","null"],"description":"The unique identifier of the contractor payment in Gusto.","readOnly":true},"contractor_uuid":{"type":"string","description":"The UUID of the contractor.","readOnly":true},"bonus":{"type":"string","description":"The bonus amount in the payment.","readOnly":true},"hours":{"type":"string","description":"The number of hours worked for the payment.","readOnly":true},"payment_method":{"type":"string","description":"The payment method.","enum":["Direct Deposit","Check","Historical Payment","Correction Payment"],"readOnly":true},"reimbursement":{"type":"string","description":"The reimbursement amount in the payment.","readOnly":true},"status":{"type":"string","description":"The status of the contractor payment.  Will transition to `Funded` during payments processing if the payment should be funded, i.e. has `Direct Deposit` for payment method. Contractors payments with `Check` payment method will remain `Unfunded`.","enum":["Funded","Unfunded"]},"hourly_rate":{"type":"string","description":"The rate per hour worked for the payment.","readOnly":true},"may_cancel":{"type":"boolean","description":"Determine if the contractor payment can be cancelled.","readOnly":true},"wage":{"type":"string","description":"The fixed wage of the payment, regardless of hours worked.","readOnly":true},"wage_type":{"type":"string","description":"The wage type for the payment.","enum":["Hourly","Fixed"],"readOnly":true},"wage_total":{"type":"string","description":"(hours * hourly_rate) + wage + bonus","readOnly":true},"invoice_number":{"type":["string","null"],"description":"An optional invoice number associated with this contractor payment. This will be visible to the contractor on their paystub. Maximum 25 characters.","readOnly":true},"memo":{"type":["string","null"],"description":"An optional note or memo for this contractor payment. This will be visible to the contractor on their paystub.","readOnly":true}},"x-tags":["Contractor Payment Groups"]},"Contractor-Payment-Summary":{"description":"The representation of the summary of contractor payments for a given company in a given time period.","type":"object","x-examples":{"success_status":{"total":{"reimbursements":"110.0","wages":"1840.0"},"contractor_payments":[{"contractor_uuid":"bc57832c-d8bc-43a7-ae99-3a03380ff037","reimbursement_total":"110.0","wage_total":"1840.0","payments":[{"uuid":"04552eb9-7829-4b18-ae96-6983552948df","contractor_uuid":"bc57832c-d8bc-43a7-ae99-3a03380ff037","bonus":"20.0","date":"2020-10-19","hours":"40.0","payment_method":"Direct Deposit","reimbursement":"100.0","hourly_rate":"18.0","may_cancel":true,"wage":"0.0","wage_type":"Hourly","wage_total":"740.00"},{"uuid":"25cfeb96-17fc-4fdf-8941-57f3fb9eea00","contractor_uuid":"bc57832c-d8bc-43a7-ae99-3a03380ff037","bonus":"100.0","date":"2020-10-19","hours":"0.00","payment_method":"Direct Deposit","reimbursement":"10.0","hourly_rate":"0.0","may_cancel":true,"wage":"1000.0","wage_type":"Fixed","wage_total":"1100.0"}]}]}},"properties":{"total":{"type":"object","description":"The wage and reimbursement totals for all contractor payments within a given time period.","properties":{"reimbursements":{"type":"string","format":"float","description":"The total reimbursements for contractor payments within a given time period.","readOnly":true},"wages":{"type":"string","format":"float","description":"The total wages for contractor payments within a given time period.","readOnly":true}},"readOnly":true},"contractor_payments":{"type":"array","uniqueItems":false,"description":"The individual contractor payments, within a given time period, grouped by contractor.","items":{"type":"object","description":"","properties":{"contractor_uuid":{"type":"number","description":"The UUID of the contractor.","readOnly":true},"reimbursement_total":{"type":"string","format":"float","description":"The total reimbursements for the contractor within a given time period.","readOnly":true},"wage_total":{"type":"string","format":"float","description":"The total wages for the contractor within a given time period.","readOnly":true},"payments":{"type":"array","uniqueItems":false,"description":"The contractor's payments within a given time period.","items":{"$ref":"#/components/schemas/Contractor-Payment"},"readOnly":true}}},"readOnly":true}},"x-tags":["Contractor Payments"]},"Contractor-Payment-Summary-By-Dates":{"description":"The representation of the summary of contractor payments for a given company in a given time period.","type":"object","x-examples":{"success_status":{"total":{"reimbursements":"110.0","wages":"1840.0"},"contractor_payments":[{"check_date":"2020-10-19","reimbursement_total":"110.0","wage_total":"1840.0","payments":[{"uuid":"04552eb9-7829-4b18-ae96-6983552948df","contractor_uuid":"bc57832c-d8bc-43a7-ae99-3a03380ff037","bonus":"20.0","date":"2020-10-19","hours":"40.0","payment_method":"Direct Deposit","reimbursement":"100.0","hourly_rate":"18.0","wage":"0.0","wage_type":"Hourly","wage_total":"740.00"},{"uuid":"25cfeb96-17fc-4fdf-8941-57f3fb9eea00","contractor_uuid":"bc57832c-d8bc-43a7-ae99-3a03380ff037","bonus":"100.0","date":"2020-10-19","hours":"0.00","payment_method":"Direct Deposit","reimbursement":"10.0","hourly_rate":"0.0","wage":"1000.0","wage_type":"Fixed","wage_total":"1100.0"}]}]}},"properties":{"total":{"type":"object","description":"The wage and reimbursement totals for all contractor payments within a given time period.","properties":{"reimbursements":{"type":"string","format":"float","description":"The total reimbursements for contractor payments within a given time period.","readOnly":true},"wages":{"type":"string","format":"float","description":"The total wages for contractor payments within a given time period.","readOnly":true}},"readOnly":true},"contractor_payments":{"type":"array","uniqueItems":false,"description":"The individual contractor payments, within a given time period, grouped by check date.","items":{"type":"object","description":"","properties":{"contractor_uuid":{"type":"string","description":"The UUID of the contractor.","readOnly":true},"check_date":{"type":"string","description":"The payment check date.","readOnly":true},"reimbursement_total":{"type":"string","format":"float","description":"The total reimbursements for the contractor within a given time period.","readOnly":true},"wage_total":{"type":"string","format":"float","description":"The total wages for the contractor within a given time period.","readOnly":true},"payments":{"type":"array","uniqueItems":false,"description":"The contractor's payments within a given time period.","items":{"$ref":"#/components/schemas/Contractor-Payment"},"readOnly":true}},"readOnly":true},"readOnly":true}},"x-tags":["Contractor Payments"]},"Contractor-Payment-Method":{"title":"Contractor-Payment-Method","type":"object","x-examples":{"check_method":{"version":"63859768485e218ccf8a449bb60f14ed","type":"Check","split_by":null,"splits":null},"Example-1":{"value":{"version":"63859768485e218ccf8a449bb60f14ed","type":"Direct Deposit","split_by":"Percentage","splits":[{"uuid":"e88f9436-b74e-49a8-87e9-777b9bfe715e","name":"BoA Checking Account","priority":1,"split_amount":100}]}},"Example-2":{"value":{"version":"63859768485e218ccf8a449bb60f14ed","type":"Check"}}},"description":"","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."},"type":{"anyOf":[{"type":"string","enum":["Direct Deposit","Check"]},{"type":"null"}],"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."},"split_by":{"anyOf":[{"type":"string","enum":["Amount","Percentage"]},{"type":"null"}],"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 values are in cents and the last split amount must be `null` to capture the remainder."},"splits":{"type":["array","null"],"items":{"$ref":"#/components/schemas/Payment-Method-Bank-Account"}}},"x-tags":["Contractor Payment Method"]},"Payment-Method-Bank-Account":{"type":"object","description":"Representation of a bank account item","properties":{"uuid":{"type":"string","description":"The bank account ID"},"name":{"type":"string","description":"The bank account name"},"hidden_account_number":{"type":"string","description":"Masked bank account number"},"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":{"description":"If `split_by` is 'Amount', this is in cents (e.g., 500 for $5.00) and exactly one account must have a `split_amount` of `null` to capture the remainder. If `split_by` is 'Percentage', this is the percentage value (e.g., 60 for 60%).","type":["integer","null"]}},"required":["uuid"]},"Payroll-Blockers-Error":{"description":"Payroll Blockers Error\n\nFor detailed information, see the [Payroll Blockers guide](https://docs.gusto.com/embedded-payroll/docs/payroll-blockers)","type":"object","x-examples":{"needs_onboarding":{"errors":[{"error_key":"base","category":"payroll_blocker","message":"Company must complete all onboarding requirements in order to run payroll.","metadata":{"key":"needs_onboarding"}}]}},"properties":{"errors":{"type":"array","items":{"type":"object","properties":{"error_key":{"type":"string","description":"The string \"base\""},"category":{"type":"string","description":"The string \"payroll_blocker\""},"message":{"type":"string","description":"Human readable description of the payroll blocker"},"metadata":{"type":"object","properties":{"key":{"type":"string","description":"A categorization of the payroll blocker, e.g. \"geocode_error\""}}}}}}}},"Create-Token-Authentication":{"description":"","type":"object","required":["access_token","token_type","expires_in","created_at"],"properties":{"access_token":{"type":"string","description":"A new access token that can be used for subsequent authenticated requests"},"token_type":{"type":"string","default":"Bearer","description":"The literal string 'Bearer'"},"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."},"created_at":{"type":"number","description":"Datetime for when the new access token is created."},"refresh_token":{"type":["string","null"],"description":"A token that must be passed to the refresh token endpoint to get a new authenticated token. Only present when refresh token is provided."}}},"Refresh-Token-Authentication":{"description":"","type":"object","allOf":[{"$ref":"#/components/schemas/Create-Token-Authentication"},{"type":"object","properties":{"refresh_token":{"type":"string","description":"A token that must be passed to the refresh token endpoint to get a new authenticated token."},"scope":{"type":"string","description":"All of the scopes for which the access token provides access."}}}]},"Authentication":{"description":"","type":"object","oneOf":[{"$ref":"#/components/schemas/Create-Token-Authentication"},{"$ref":"#/components/schemas/Refresh-Token-Authentication"}],"x-examples":{"create_token":{"access_token":"As8qKfNObHbwe7abbJqF0WUF6iCQoIW2R664TFzXd-A","token_type":"Bearer","created_at":1767644464,"expires_in":7200,"refresh_token":null},"refresh_token":{"access_token":"As8qKfNObHbwe7abbJqF0WUF6iCQoIW2R664TFzXd-A","refresh_token":"As8qKfNObHbwe7abbJqF0WUF6iCQoIW2R664TFzXd-A","scope":"public payroll:read","token_type":"Bearer","created_at":1767644464,"expires_in":7200}}},"Token-Info":{"type":"object","properties":{"scope":{"type":"string","description":"Space-separated list of OAuth scopes granted to this access token.\n","example":"companies:read public"},"resource":{"type":["object","null"],"description":"The resource associated with this access token. Null when\nthe token has no associated resource.\n","properties":{"type":{"type":"string","description":"The type of resource associated with the access token, e.g. `Company` for a company-level token or `Oauth::Application` for a system-level token.\n","example":"Company"},"uuid":{"type":"string","format":"uuid","description":"The UUID of the associated resource","example":"7b1d0df1-6403-4a06-8768-c1dd7d24d27a"}}},"resource_owner":{"type":["object","null"],"description":"The resource owner (user) who authorized this access token. Null for\nsystem-level tokens or when the owner cannot be determined.\n","properties":{"type":{"type":"string","enum":["CompanyAdmin","Employee","Contractor"],"description":"The type of resource owner:\n- `CompanyAdmin`: A company administrator\n- `Employee`: An employee\n- `Contractor`: A contractor\n","example":"CompanyAdmin"},"uuid":{"type":"string","format":"uuid","description":"The UUID of the resource owner","example":"8fdc31f0-a8a7-4872-a9f1-dcb5e6f876e3"}}}},"x-examples":{"company_admin_token":{"scope":"companies:read public","resource":{"type":"Company","uuid":"7b1d0df1-6403-4a06-8768-c1dd7d24d27a"},"resource_owner":{"type":"CompanyAdmin","uuid":"8fdc31f0-a8a7-4872-a9f1-dcb5e6f876e3"}},"system_token":{"scope":"partner_managed_companies:create public","resource":{"type":"Oauth::Application","uuid":"9c2a1b3d-4e5f-6789-abcd-ef0123456789"},"resource_owner":null}}},"Pay-Schedule":{"type":"object","title":"Pay Schedule","x-examples":{"Example":{"uuid":"f2a69c38-e2f9-4e31-b5c5-4754fc60a052","version":"68934a3e9455fa72420237eb05902327","frequency":"Twice per month","anchor_pay_date":"2020-05-15","anchor_end_of_pay_period":"2020-05-08","day_1":15,"day_2":31,"name":"Engineering","auto_payroll":false,"custom_name":"A new monthly pay schedule"},"success_status":{"uuid":"f2a69c38-e2f9-4e31-b5c5-4754fc60a052","version":"68934a3e9455fa72420237eb05902327","frequency":"Twice per month","anchor_pay_date":"2022-09-01","anchor_end_of_pay_period":"2022-08-18","day_1":1,"day_2":15,"name":null,"custom_name":"every 1st and 15th of the month","auto_payroll":true,"active":true,"auto_payroll_enablement_blockers":null}},"description":"The pay schedule object in Gusto captures the details of when employees work and when they should be paid. A company can have multiple pay schedules.\n\nResponse includes frequency, anchor dates, optional day_1/day_2 for monthly/semi-monthly, auto_payroll (named auto_pilot in API versions before 2025-11-15), and auto_payroll_enablement_blockers when Autopayroll is disabled.\n\n**Webhooks:** Subscribe to [Pay Schedule Events](https://docs.gusto.com/embedded-payroll/docs/pay-schedule-events) to receive `pay_schedule.created` and `pay_schedule.updated` when pay schedules are created or updated.\n","properties":{"uuid":{"$ref":"#/components/schemas/Pay-Schedule-Uuid"},"version":{"$ref":"#/components/schemas/Pay-Schedule-Version"},"frequency":{"$ref":"#/components/schemas/Pay-Schedule-Frequency"},"anchor_pay_date":{"$ref":"#/components/schemas/Pay-Schedule-Anchor-Pay-Date"},"anchor_end_of_pay_period":{"$ref":"#/components/schemas/Pay-Schedule-Anchor-End-Of-Pay-Period"},"day_1":{"$ref":"#/components/schemas/Pay-Schedule-Day-1"},"day_2":{"$ref":"#/components/schemas/Pay-Schedule-Day-2"},"name":{"$ref":"#/components/schemas/Pay-Schedule-Name"},"custom_name":{"$ref":"#/components/schemas/Pay-Schedule-Custom-Name"},"auto_payroll":{"$ref":"#/components/schemas/Pay-Schedule-Auto-Payroll"},"active":{"$ref":"#/components/schemas/Pay-Schedule-Active"},"auto_payroll_enablement_blockers":{"$ref":"#/components/schemas/Pay-Schedule-Auto-Payroll-Enablement-Blockers"}},"x-tags":["Pay Schedules"],"required":["uuid"]},"Pay-Schedule-Show":{"type":"object","title":"Pay Schedule","description":"Pay schedule returned from pay schedule endpoints (GET by ID, POST create, PUT update). Same fields as Pay-Schedule with a required `version` for [optimistic concurrency](https://docs.gusto.com/embedded-payroll/docs/api-fundamentals#optimistic-version-control).\n\nFor API version 2025-11-15 and later, responses use `auto_payroll`; earlier versions use `auto_pilot` for the same semantic.\n","required":["uuid","version"],"properties":{"uuid":{"$ref":"#/components/schemas/Pay-Schedule-Uuid"},"version":{"$ref":"#/components/schemas/Pay-Schedule-Version"},"frequency":{"$ref":"#/components/schemas/Pay-Schedule-Frequency"},"anchor_pay_date":{"$ref":"#/components/schemas/Pay-Schedule-Anchor-Pay-Date"},"anchor_end_of_pay_period":{"$ref":"#/components/schemas/Pay-Schedule-Anchor-End-Of-Pay-Period"},"day_1":{"$ref":"#/components/schemas/Pay-Schedule-Day-1"},"day_2":{"$ref":"#/components/schemas/Pay-Schedule-Day-2"},"name":{"$ref":"#/components/schemas/Pay-Schedule-Name"},"custom_name":{"$ref":"#/components/schemas/Pay-Schedule-Custom-Name"},"auto_payroll":{"$ref":"#/components/schemas/Pay-Schedule-Auto-Payroll"},"active":{"$ref":"#/components/schemas/Pay-Schedule-Active"},"auto_payroll_enablement_blockers":{"$ref":"#/components/schemas/Pay-Schedule-Auto-Payroll-Enablement-Blockers"}},"x-tags":["Pay Schedules"],"x-examples":{"Example":{"uuid":"f2a69c38-e2f9-4e31-b5c5-4754fc60a052","version":"68934a3e9455fa72420237eb05902327","frequency":"Twice per month","anchor_pay_date":"2020-05-15","anchor_end_of_pay_period":"2020-05-08","day_1":15,"day_2":31,"name":"Engineering","auto_payroll":false,"custom_name":"A new monthly pay schedule","active":true,"auto_payroll_enablement_blockers":null},"success_status":{"uuid":"f2a69c38-e2f9-4e31-b5c5-4754fc60a052","version":"68934a3e9455fa72420237eb05902327","frequency":"Twice per month","anchor_pay_date":"2022-09-01","anchor_end_of_pay_period":"2022-08-18","day_1":1,"day_2":15,"name":null,"custom_name":"every 1st and 15th of the month","auto_payroll":true,"active":true,"auto_payroll_enablement_blockers":null}}},"Pay-Schedule-Show-Response":{"type":"array","description":"List of pay schedules for a company, as returned from [GET /v1/companies/{company_id}/pay_schedules](ref:get-v1-companies-company_id-pay_schedules). Each entry matches Pay-Schedule-Show (includes `version`).\n","items":{"$ref":"#/components/schemas/Pay-Schedule-Show"},"x-tags":["Pay Schedules"],"x-examples":{"success_status":[{"uuid":"f2a69c38-e2f9-4e31-b5c5-4754fc60a052","version":"68934a3e9455fa72420237eb05902327","frequency":"Monthly","anchor_pay_date":"2022-12-11","anchor_end_of_pay_period":"2022-11-13","day_1":11,"day_2":null,"name":null,"custom_name":"every 11th of the month","auto_payroll":true,"active":true,"auto_payroll_enablement_blockers":null}]}},"Pay-Schedule-Version":{"type":"string","description":"The current version of the pay schedule. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/api-fundamentals#optimistic-version-control) for information on how to use this field for optimistic concurrency.","readOnly":true},"Pay-Schedule-Auto-Payroll":{"type":"boolean","description":"With automatic payroll enabled, payroll runs automatically one day before payroll deadlines. When false, payroll does not run automatically.\nReturned for API version 2025-11-15 and later; for earlier versions the response uses auto_pilot instead.\n","readOnly":true},"Pay-Schedule-Auto-Payroll-Enablement-Blockers":{"type":["array","null"],"description":"List of blockers preventing automatic payroll from being enabled. If automatic payroll is already enabled, this field is null.","items":{"$ref":"#/components/schemas/Pay-Schedule-Auto-Payroll-Enablement-Blocker"}},"Pay-Schedule-Auto-Payroll-Enablement-Blocker":{"type":"object","description":"A single blocker preventing Autopayroll enablement.","properties":{"key":{"type":"string","description":"The blocker type. Possible values: employees_not_on_direct_deposit, employees_not_salaried, missing_state_tax_requirements, missing_funding_method, one_day_ach_speed_not_supported, company_suspended, earned_fast_ach_not_met, hourly_employees_missing_default_hours."},"metadata":{"type":"object","description":"Blocker-specific metadata (e.g. employee_uuids, states)."}}},"Pay-Schedule-List":{"type":"array","description":"List of pay schedules for a company. The pay schedule object in Gusto captures the details of when employees work and when they should be paid. A company can have multiple pay schedules.","items":{"$ref":"#/components/schemas/Pay-Schedule-Show"},"x-examples":{"success_status":[{"uuid":"f2a69c38-e2f9-4e31-b5c5-4754fc60a052","version":"68934a3e9455fa72420237eb05902327","frequency":"Monthly","anchor_pay_date":"2022-12-11","anchor_end_of_pay_period":"2022-11-13","day_1":11,"day_2":null,"name":null,"custom_name":"every 11th of the month","auto_payroll":true,"active":true}]}},"Pay-Schedule-Preview-Pay-Period":{"type":"object","description":"A single pay period in a pay schedule preview, with check date, period boundaries, and payroll deadline.","required":["check_date","start_date","run_payroll_by","end_date"],"properties":{"check_date":{"type":"string","format":"date","description":"The payment date, \"Check date\", for the pay period."},"start_date":{"type":"string","format":"date","description":"The first day of the pay period."},"run_payroll_by":{"type":"string","format":"date","description":"The deadline to run payroll for direct deposit on the check date."},"end_date":{"type":"string","format":"date","description":"The last day of the pay period."}}},"Pay-Schedule-Preview":{"type":"object","description":"Preview of pay schedule dates for the next 18 months. Use this to show partners expected pay dates, pay period boundaries, and payroll deadlines before they create or change a pay schedule. See [Preview pay schedule dates](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-pay_schedules-preview) for usage.\n\n- **pay_periods**: One entry per pay period in the range; each includes check_date, start_date, end_date, and run_payroll_by.\n- **holidays**: Observed bank holidays (ISO date strings) that may affect payroll timing.\n","x-examples":{"success_status":{"pay_periods":[{"check_date":"2022-01-15","start_date":"2022-01-01","run_payroll_by":"2022-01-14","end_date":"2022-01-15"},{"check_date":"2022-01-31","start_date":"2022-01-16","run_payroll_by":"2022-01-30","end_date":"2022-01-31"}],"holidays":["2022-01-01","2022-01-17"]}},"properties":{"pay_periods":{"type":"array","description":"A list of pay periods for the previewed pay schedule (default range is 18 months from today, or up to end_date when provided).","items":{"$ref":"#/components/schemas/Pay-Schedule-Preview-Pay-Period"}},"holidays":{"type":"array","description":"A list of dates for bank closures (ISO date strings); may affect payroll processing.","items":{"type":"string","format":"date"}}}},"Pay-Schedule-Date-Input":{"type":"string","format":"date","description":"ISO 8601 date (YYYY-MM-DD). Required for anchor and period dates in create, update, and preview requests."},"Pay-Schedule-Create-Request":{"type":"object","description":"Request body for creating a pay schedule. Required when a company has no pay schedules (onboarding) or when adding an additional schedule. Be sure to [check state laws](https://www.dol.gov/agencies/whd/state/payday) to know what schedule is right for your customers.\n\n- **anchor_pay_date**: The first date that employees on this pay schedule will be paid (first company payday).\n- **anchor_end_of_pay_period**: The last date of the first pay period; can be the same as anchor_pay_date.\n","example":{"frequency":"Twice per month","anchor_pay_date":"2020-05-15","anchor_end_of_pay_period":"2020-05-08","day_1":15,"day_2":31,"custom_name":"demo pay schedule"},"properties":{"frequency":{"allOf":[{"$ref":"#/components/schemas/Pay-Schedule-Frequency-Create-Update"}],"example":"Twice per month"},"anchor_pay_date":{"allOf":[{"$ref":"#/components/schemas/Pay-Schedule-Date-Input"}],"example":"2020-05-15"},"anchor_end_of_pay_period":{"allOf":[{"$ref":"#/components/schemas/Pay-Schedule-Date-Input"}],"example":"2020-05-08"},"day_1":{"type":["integer","null"],"example":15,"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.\n\nOn create: required for Twice per month and Monthly; omit or null for Every week and Every other week.\n"},"day_2":{"type":["integer","null"],"example":31,"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, the second pay date is set to the last day of the month. It will be null for pay schedules with other frequencies.\n\nOn create: only for Twice per month; omit or null for other frequencies.\n"},"custom_name":{"type":["string","null"],"example":"demo pay schedule","description":"A custom pay schedule name; defaults to the pay frequency description when null or omitted.\n\nWhen null or omitted, the system generates a description from the pay frequency and pay days (e.g. \"every 1st and 15th of the month\" for twice-monthly, \"every 11th of the month\" for monthly, \"every Friday\" for weekly). The response returns this generated value in `custom_name` when no custom name was set. When provided, the value you set is stored and returned.\n"}},"required":["frequency","anchor_pay_date","anchor_end_of_pay_period"]},"Pay-Schedule-Update-Request":{"type":"object","description":"Request body for updating a pay schedule. Sent in the pay_schedule_update root key. Version is required for optimistic concurrency. Pay schedules may be automatically adjusted if an onboarded company misses their first pay date; see [Create a pay schedule](https://docs.gusto.com/embedded-payroll/docs/create-a-pay-schedule).","example":{"version":"68934a3e9455fa72420237eb05902327","auto_payroll":true,"frequency":"Twice per month","anchor_pay_date":"2021-10-15","anchor_end_of_pay_period":"2021-10-15","day_1":15,"day_2":31,"custom_name":"demo pay schedule"},"properties":{"version":{"type":"string","example":"68934a3e9455fa72420237eb05902327","description":"Current version of the pay schedule from the GET response; required for optimistic concurrency. Mismatch returns 409 Conflict."},"auto_payroll":{"type":"boolean","example":true,"description":"With automatic payroll enabled, payroll runs automatically one day before payroll deadlines. When false, payroll does not run automatically and must be run manually.\nFor API versions before 2025-11-15 the request field is auto_pilot.\n"},"frequency":{"allOf":[{"$ref":"#/components/schemas/Pay-Schedule-Frequency-Create-Update"}],"example":"Twice per month"},"anchor_pay_date":{"allOf":[{"$ref":"#/components/schemas/Pay-Schedule-Date-Input"}],"example":"2020-05-15"},"anchor_end_of_pay_period":{"allOf":[{"$ref":"#/components/schemas/Pay-Schedule-Date-Input"}],"example":"2020-05-08"},"day_1":{"type":["integer","null"],"example":15,"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.\n"},"day_2":{"type":["integer","null"],"example":31,"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, the second pay date is set to the last day of the month. It will be null for pay schedules with other frequencies.\n"},"custom_name":{"type":["string","null"],"example":"demo pay schedule","description":"A custom pay schedule name; null clears any custom name so the default frequency description applies."}},"required":["version"]},"Pay-Schedule-Create-Update":{"type":"object","title":"Pay Schedule","x-examples":{"Example":{"uuid":"f2a69c38-e2f9-4e31-b5c5-4754fc60a052","frequency":"Twice per month","anchor_pay_date":"2020-05-15","anchor_end_of_pay_period":"2020-05-08","day_1":15,"day_2":31,"name":"Engineering","auto_payroll":false,"custom_name":"A new monthly pay schedule"}},"description":"The representation of a pay schedule.","properties":{"uuid":{"$ref":"#/components/schemas/Pay-Schedule-Uuid"},"frequency":{"$ref":"#/components/schemas/Pay-Schedule-Frequency-Create-Update"},"anchor_pay_date":{"$ref":"#/components/schemas/Pay-Schedule-Anchor-Pay-Date"},"anchor_end_of_pay_period":{"$ref":"#/components/schemas/Pay-Schedule-Anchor-End-Of-Pay-Period"},"day_1":{"$ref":"#/components/schemas/Pay-Schedule-Day-1"},"day_2":{"$ref":"#/components/schemas/Pay-Schedule-Day-2"},"name":{"$ref":"#/components/schemas/Pay-Schedule-Name"},"custom_name":{"$ref":"#/components/schemas/Pay-Schedule-Custom-Name"},"auto_payroll":{"type":"boolean","description":"With automatic payroll enabled, payroll runs automatically one day before payroll deadlines. When false, payroll does not run automatically.\nIn API versions before 2025-11-15 this field is named `auto_pilot`.\n","readOnly":true},"active":{"$ref":"#/components/schemas/Pay-Schedule-Active"}},"x-tags":["Pay Schedules"],"required":["uuid"]},"Pay-Schedule-Uuid":{"type":"string","description":"The unique identifier of the pay schedule in Gusto.","readOnly":true},"Pay-Schedule-Frequency":{"type":"string","description":"The frequency that employees on this pay schedule are paid with Gusto.\n\nREAD-ONLY in responses. Possible values:\n\n- `Every week`: Employees are paid weekly.\n- `Every other week`: Employees are paid bi-weekly (every two weeks).\n- `Twice per month`: Employees are paid on two fixed days each month (e.g. 1st and 15th); use day_1 and day_2.\n- `Monthly`: Employees are paid once per month; use day_1 for the pay day.\n- `Quarterly`: Employees are paid every three months.\n- `Annually`: Employees are paid once per year.\n","enum":["Every week","Every other week","Twice per month","Monthly","Quarterly","Annually"],"readOnly":true},"Pay-Schedule-Frequency-Create-Update":{"type":"string","description":"The frequency that employees on this pay schedule are paid with Gusto. Only weekly, bi-weekly, twice per month, and monthly are supported on create and update.\n\n- `Every week`: Weekly pay.\n- `Every other week`: Biweekly pay.\n- `Twice per month`: Two pay dates per month; require day_1 and day_2 (use 31 for last day of month).\n- `Monthly`: One pay date per month; require day_1 (1-31).\n","enum":["Every week","Every other week","Twice per month","Monthly"]},"Pay-Schedule-Anchor-Pay-Date":{"type":"string","format":"date","description":"The first date that employees on this pay schedule are paid with Gusto (ISO 8601 YYYY-MM-DD).","readOnly":true},"Pay-Schedule-Anchor-End-Of-Pay-Period":{"type":"string","format":"date","description":"The last date of the first pay period. This can be the same date as the anchor pay date (ISO 8601 YYYY-MM-DD).","readOnly":true},"Pay-Schedule-Day-1":{"type":["integer","null"],"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.\n","readOnly":true},"Pay-Schedule-Day-2":{"type":["integer","null"],"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, the second pay date is set to the last day of the month. It will be null for pay schedules with other frequencies.\n","readOnly":true},"Pay-Schedule-Name":{"type":["string","null"],"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.","readOnly":true},"Pay-Schedule-Custom-Name":{"type":"string","description":"A custom name for a pay schedule; defaults to the pay frequency description when none was set by the partner.\n\nWhen the partner never set a custom name (or cleared it), this field contains the auto-generated description derived from frequency and pay days (e.g. \"every 1st and 15th of the month\", \"every Friday\"). When the partner set a custom name on create or update, this field contains that value.\n","readOnly":true},"Pay-Schedule-Active":{"type":"boolean","description":"Whether this pay schedule is associated with any employees. A pay schedule is inactive when it's unassigned.","readOnly":true},"Ytd-Benefit-Amounts-From-Different-Company":{"type":"object","description":"Ytd Benefit Amounts From Different Company","properties":{"uuid":{"type":"string","description":"The unique identifier for this benefit amount record."},"benefit_type":{"type":"integer","description":"The benefit type supported by Gusto. See [Benefit Types](https://docs.gusto.com/embedded-payroll/reference/get-v1-benefits) for more information."},"ytd_employee_deduction_amount":{"type":"string","description":"The year-to-date employee deduction made outside the current company."},"ytd_company_contribution_amount":{"type":"string","description":"The year-to-date company contribution made outside the current company."}},"required":["uuid","benefit_type","ytd_employee_deduction_amount","ytd_company_contribution_amount"],"x-examples":{"Ytd-Benefit-Amounts-List":[{"uuid":"c5fdae57-5483-4529-9aae-f0edceed92d3","benefit_type":1,"ytd_employee_deduction_amount":"5000.00","ytd_company_contribution_amount":"2500.00"},{"uuid":"1bfdb946-b2be-4909-ac46-9e7f73872d0a","benefit_type":5,"ytd_employee_deduction_amount":"2132.00","ytd_company_contribution_amount":"3345.00"}]}},"Ytd-Benefit-Amounts-From-Different-Company-Body":{"type":"object","description":"Year-to-date benefit amounts contributed at a different company for the specified employee.","properties":{"benefit_type":{"type":"integer","description":"The benefit type supported by Gusto."},"tax_year":{"type":"number","minimum":2000,"maximum":2999,"description":"The tax year for which this amount applies."},"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."}},"required":["benefit_type","tax_year","ytd_employee_deduction_amount","ytd_company_contribution_amount"],"x-tags":["Employee Benefits"]},"Company-Attachment":{"description":"The company attachment","type":"object","required":["uuid","name","category","upload_time"],"x-examples":{"success_status":{"uuid":"1263eae5-4411-48d9-bd6d-18ed93082e65","name":"Company_Attachment_File.pdf","category":"gep_notice","upload_time":"2024-09-10T01:54:20Z"},"compliance_attachment":{"uuid":"987058cc-23ee-46e9-81ef-5cee086cceca","name":"Compliance_Document.pdf","category":"compliance","upload_time":"2024-10-15T14:30:00Z"}},"x-tags":["Company Attachment"],"properties":{"uuid":{"type":"string","description":"UUID of the company attachment"},"name":{"type":"string","description":"name of the file uploaded"},"category":{"type":"string","description":"The category of the company attachment.\n- `gep_notice`: A tax notice attachment\n- `compliance`: A compliance attachment\n- `other`: Any other attachment type\n","enum":["gep_notice","compliance","other"]},"upload_time":{"type":"string","description":"The ISO 8601 timestamp of when an attachment was uploaded"}}},"Company-Attachment-List":{"type":"array","x-examples":{"success_status":[{"uuid":"5de11791-98fd-4587-9ed0-d5d804b8e647","name":"Company_Attachment_File1.pdf","category":"gep_notice","upload_time":"2022-02-01T00:00:00.000Z"},{"uuid":"987058cc-23ee-46e9-81ef-5cee086cceca","name":"Company_Attachment_File2.pdf","category":"compliance","upload_time":"2022-02-01T00:00:00.000Z"}]},"items":{"$ref":"#/components/schemas/Company-Attachment"}},"Company-Attachment-Download-Url":{"description":"The temporary url to download a Company Attachment File","type":"object","required":["url"],"x-examples":{"success_status":{"url":"https://s3.amazonaws.com/static.gusto.com/assets/uploaded_files/334721.pdf?parameter=daer8r3432423djklsdafaso"},"success_status_alternate":{"url":"https://s3.amazonaws.com/static.gusto.com/assets/uploaded_files/112233.pdf?parameter=abc123def456"}},"properties":{"url":{"type":"string","description":"A full URL to download a Company Attachment File"}}},"Company-Attachment-Create-Request-Body":{"description":"The binary payload of the file and the company attachment category.","type":"object","required":["document","category"],"properties":{"document":{"type":"string","format":"binary","description":"The binary payload of the file to be uploaded. Supported file types are .qbb, .qbm, .gif, .jpg, .png, .pdf, .xls, .xlsx, .doc and .docx."},"category":{"type":"string","description":"The category of a company attachment.\n- `gep_notice`: A tax notice attachment\n- `compliance`: A compliance attachment\n","enum":["gep_notice","compliance"]}}},"Company-Bank-Account":{"description":"The company bank account","type":"object","x-examples":{"success_status":{"uuid":"1263eae5-4411-48d9-bd6d-18ed93082e65","company_uuid":"e2c4c0ce-2986-48b9-86cf-ec27f6ed9a36","account_type":"Checking","routing_number":"851070439","hidden_account_number":"XXXX4087","verification_status":"verified","verification_type":"bank_deposits","name":"Employer Funding Account","reverse_wire_enabled":false},"plaid_external_status":{"uuid":"1263eae5-4411-48d9-bd6d-18ed93082e65","company_uuid":"e2c4c0ce-2986-48b9-86cf-ec27f6ed9a36","account_type":"Checking","routing_number":"851070439","hidden_account_number":"XXXX4087","verification_status":"verified","verification_type":"plaid_external","name":"Employer Funding Account","reverse_wire_enabled":true}},"x-tags":["Company Bank Accounts"],"properties":{"uuid":{"type":"string","description":"UUID of the bank account"},"company_uuid":{"type":"string","description":"UUID of the company"},"account_type":{"type":"string","description":"Bank account type","enum":["Checking","Savings"]},"routing_number":{"type":"string","description":"The bank account's routing number"},"hidden_account_number":{"type":"string","description":"Masked bank account number"},"verification_status":{"type":"string","enum":["awaiting_deposits","ready_for_verification","verified"],"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."},"verification_type":{"type":"string","enum":["bank_deposits","plaid","plaid_external"],"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."},"plaid_status":{"anyOf":[{"type":"string","enum":["connected","disconnected"]},{"type":"null"}],"description":"The Plaid connection status of the bank account. Only applies when verification type is Plaid."},"last_cached_balance":{"type":["string","null"],"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."},"balance_fetched_date":{"type":["string","null"],"description":"The balance fetch date associated with the last_cached_balance. Only applies when verification type is Plaid."},"name":{"type":"string","description":"Name of bank account"},"reverse_wire_enabled":{"type":["boolean","null"],"description":"Whether the company has at least one bank account with active reverse-wire\nfunding. The same value is returned on every bank-account row in this\nresponse."}},"required":["uuid"]},"Company-Bank-Account-Request":{"type":"object","properties":{"routing_number":{"type":"string","description":"The bank routing number"},"account_number":{"type":"string","description":"The bank account number"},"account_type":{"type":"string","description":"The bank account type","enum":["Checking","Savings"]}},"required":["routing_number","account_number","account_type"]},"Employee-Bank-Account-Request":{"type":"object","description":"Request body for creating or updating an employee bank account. Send these fields as top-level JSON keys (the API wraps them server-side).","properties":{"routing_number":{"type":"string","description":"The bank routing number (nine digits).","example":"266905059"},"account_number":{"type":"string","description":"The bank account number.","example":"5809431207"},"account_type":{"type":"string","description":"The bank account type.","example":"Checking","enum":["Checking","Savings"]},"name":{"type":"string","description":"A name for the bank account (e.g. \"Primary Checking\").","example":"BoA Checking Account"}},"required":["routing_number","account_number","account_type","name"]},"Company-Bank-Account-Verify-Request":{"type":"object","description":"Request body for verifying a company bank account with the two micro-deposit amounts.","required":["deposit_1","deposit_2"],"properties":{"deposit_1":{"type":"number","format":"float","description":"The first micro-deposit amount (order does not matter)."},"deposit_2":{"type":"number","format":"float","description":"The second micro-deposit amount (order does not matter)."}}},"Plaid-Processor-Token-Request":{"type":"object","description":"Request body for creating a verified company bank account from a Plaid processor token.","required":["owner_type","owner_id","processor_token"],"properties":{"owner_type":{"description":"The owner type of the bank account","type":"string","enum":["Company"]},"owner_id":{"description":"The owner UUID of the bank account","type":"string"},"processor_token":{"description":"The Plaid processor token","type":"string"}},"x-examples":{"example":{"owner_type":"Company","owner_id":"ef279fbd-0fc6-4cf1-a977-6939d621c429","processor_token":"processor-sandbox-0asd1-a92nc"}}},"Benefit-Type-Requirements":{"description":"","type":"object","x-tags":["Company Benefits"],"properties":{"employee_deduction":{"type":"object","description":"The amount to be deducted, per pay period, from the employee's pay.","properties":{"required":{"type":"boolean"},"editable":{"type":"boolean"},"default_value":{"type":["object","null"],"properties":{"value":{"type":"string"},"type":{"type":"string"}}},"choices":{"type":["array","null"],"items":{"type":"string"}}}},"contribution":{"type":"object","description":"An object representing the type and value of the company contribution.","properties":{"required":{"type":"boolean"},"editable":{"type":"boolean"},"default_value":{"type":["object","null"],"properties":{"value":{"type":"string"},"type":{"type":"string"}}},"choices":{"type":["array","null"],"items":{"type":"string"}}}},"deduct_as_percentage":{"type":"object","description":"Whether the employee deduction amount should be treated as a percentage to be deducted from each payroll.","properties":{"required":{"type":"boolean"},"editable":{"type":"boolean"},"default_value":{"type":["object","null"],"properties":{"value":{"type":"string"},"type":{"type":"string"}}},"choices":{"type":["array","null"],"items":{"type":"string"}}}},"catch_up":{"type":"object","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.","properties":{"required":{"type":"boolean"},"editable":{"type":"boolean"},"default_value":{"type":["object","null"],"properties":{"value":{"type":"string"},"type":{"type":"string"}}},"choices":{"type":["array","null"],"items":{"type":"string"}}}},"limit_option":{"type":"object","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'.","properties":{"required":{"type":"boolean"},"editable":{"type":"boolean"},"default_value":{"type":["object","null"],"properties":{"value":{"type":"string"},"type":{"type":"string"}}},"choices":{"type":["array","null"],"items":{"type":"string"}}}},"company_contribution_annual_maximum":{"type":"object","description":"The maximum company contribution amount per year. A null value signifies no limit.","properties":{"required":{"type":"boolean"},"editable":{"type":"boolean"},"default_value":{"type":["object","null"],"properties":{"value":{"type":"string"},"type":{"type":"string"}}},"choices":{"type":["array","null"],"items":{"type":"string"}}}},"coverage_salary_multiplier":{"type":"object","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.","properties":{"required":{"type":"boolean"},"editable":{"type":"boolean"},"default_value":{"type":["object","null"],"properties":{"value":{"type":"string"},"type":{"type":"string"}}},"choices":{"type":["array","null"],"items":{"type":"string"}}}},"coverage_amount":{"type":"object","description":"The amount that the employee is insured for. Note: company contribution cannot be present if coverage amount is set.","properties":{"required":{"type":"boolean"},"editable":{"type":"boolean"},"default_value":{"type":["object","null"],"properties":{"value":{"type":"string"},"type":{"type":"string"}}},"choices":{"type":["array","null"],"items":{"type":"string"}}}}},"x-examples":{"Example":{"employee_deduction":{"required":true,"editable":true,"default_value":null,"choices":null},"contribution":{"required":true,"editable":true,"default_value":null,"choices":["amount"]},"deduct_as_percentage":{"required":false,"editable":false,"default_value":null,"choices":null},"catch_up":{"required":false,"editable":false,"default_value":null,"choices":null},"limit_option":{"required":false,"editable":false,"default_value":null,"choices":null},"company_contribution_annual_maximum":{"required":false,"editable":false,"default_value":null,"choices":null},"coverage_salary_multiplier":{"required":false,"editable":false,"default_value":null,"choices":null},"coverage_amount":{"required":false,"editable":false,"default_value":null,"choices":null}}}},"Benefit-Summary":{"description":"","type":"object","x-tags":["Company Benefits"],"x-examples":{"typical_summary":{"start_date":"2022-01-01","end_date":"2022-12-31","description":"Simple IRA","company_benefit_deduction":"60.0","company_benefit_contribution":"30.0","employees":[{"uuid":"54b7114f-f5e2-4f4b-911b-5cd5ad9032b0","company_benefit_deduction":"60.0","company_benefit_contribution":"30.0","benefit_deduction":"660.0","benefit_contribution":"330.0","gross_pay":"18000.0","imputed_pay":"350.0","payroll_benefits":[{"payroll_uuid":"8cc3471b-9da5-47df-88ea-f238c7cb968b","payroll_type":"Regular","check_date":"2022-03-01","gross_pay":"3000.0","imputed_pay":"70.0","company_benefit_deduction":"10.0","company_benefit_contribution":"5.0","pay_period":{"start_date":"2022-02-01","end_date":"2022-02-28"}},{"payroll_uuid":"d9d92786-722b-4bf7-bb32-79140418d349","payroll_type":"Bonus","check_date":"2022-12-31","gross_pay":"3000.0","imputed_pay":"70.0","company_benefit_deduction":"20.0","company_benefit_contribution":"10.0","pay_period":{"start_date":"nil","end_date":"nil"}}]}]}},"properties":{"start_date":{"type":"string","description":"The start date of benefit summary."},"end_date":{"type":"string","description":"The end 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 the specific company benefit."},"company_benefit_contribution":{"type":"string","description":"The aggregate of company contribution for all employees given the period of time and the specific company benefit."},"employees":{"type":"array","description":"","items":{"type":"object","properties":{"uuid":{"type":"string","description":"The UUID of the employee"},"company_benefit_deduction":{"type":"string","description":"The sum of employee deduction for this employee given the period of time and the specific company benefit."},"company_benefit_contribution":{"type":"string","description":"The sum of company contribution for this employee given the period of time and the specific company benefit."},"benefit_deduction":{"type":"string","description":"The sum of employee benefit deduction for this employee given the period of time and the benefit type."},"benefit_contribution":{"type":"string","description":"The sum of company contribution for this employee given the period of time and the benefit type."},"gross_pay":{"type":"string","description":"Gross pay for this employee given the period of time."},"imputed_pay":{"type":"string","description":"Total imputed pay for this employee given the period of time (not scoped to a benefit type)."},"payroll_benefits":{"type":"array","items":{"type":"object","properties":{"payroll_uuid":{"type":"string"},"payroll_type":{"type":"string","description":"Whether it is regular or bonus payroll"},"check_date":{"type":"string","description":"Check date of this payroll."},"gross_pay":{"type":"string","description":"Gross pay for this employee on the payroll."},"imputed_pay":{"type":"string","description":"Total imputed pay for this employee on the payroll."},"company_benefit_deduction":{"type":"string","description":"The employee benefit deduction amount for this employee on the payroll."},"company_benefit_contribution":{"type":"string","description":"The company contribution amount for this employee on the payroll."},"pay_period":{"type":"object","properties":{"start_date":{"type":["string","null"],"description":"The beginning of the payroll's pay period."},"end_date":{"type":["string","null"],"description":"The end of the payroll's pay period."}}}}}}}}}}},"Supported-Benefit":{"description":"","type":"object","properties":{"benefit_type":{"type":"integer","description":"The benefit type in Gusto.","readOnly":true},"name":{"type":"string","description":"The name of the benefit.","readOnly":true},"description":{"type":"string","description":"The description of the benefit.","readOnly":true},"pretax":{"type":"boolean","description":"Whether the benefit is deducted before tax calculations, thus reducing one’s taxable income","readOnly":true},"posttax":{"type":"boolean","description":"Whether the benefit is deducted after tax calculations.","readOnly":true},"imputed":{"type":"boolean","description":"Whether the benefit is considered imputed income.","readOnly":true},"healthcare":{"type":"boolean","description":"Whether the benefit is healthcare related.","readOnly":true},"retirement":{"type":"boolean","description":"Whether the benefit is associated with retirement planning.","readOnly":true},"yearly_limit":{"type":"boolean","description":"Whether the benefit has a government mandated yearly limit. If the benefit has a government mandated yearly limit, employees cannot be added to more than one benefit of this type.","readOnly":true},"category":{"type":"string","description":"Category where the benefit belongs to.","readOnly":true},"writable_by_application":{"type":"boolean","description":"Whether this benefit can be written (created, updated, or destroyed). Returns true if the benefit type is permitted for the application, false otherwise.","readOnly":true}},"x-examples":{"Example":{"benefit_type":1,"name":"Medical Insurance","description":"Deductions and contributions for Medical Insurance","pretax":true,"posttax":false,"imputed":false,"healthcare":true,"retirement":false,"yearly_limit":false,"category":"Health"},"Supported-Benefits-List":{"benefit_type":1,"name":"Medical Insurance","description":"Deductions and contributions for Medical Insurance","pretax":true,"posttax":false,"imputed":false,"healthcare":true,"retirement":false,"yearly_limit":false,"category":"Health"}}},"Supported-Benefit-List":{"type":"array","items":{"$ref":"#/components/schemas/Supported-Benefit"},"x-examples":{"full_catalog":[{"benefit_type":1,"name":"Medical Insurance","description":"Health-related insurance under IRS section 125 includes medical, dental and vision insurance, and is the most common benefit provided by employers today. It allows paying for certain health benefits using pre-tax dollars. This lowers the employee taxable income and the overall tax payments for both the employee and the employer.","pretax":true,"posttax":false,"imputed":false,"healthcare":true,"retirement":false,"yearly_limit":false,"category":"Health"},{"benefit_type":2,"name":"Dental Insurance","description":"Health-related insurance under IRS section 125 includes medical, dental and vision insurance, and is the most common benefit provided by employers today. It allows paying for certain health benefits using pre-tax dollars. This lowers the employee taxable income and the overall tax payments for both the employee and the employer.","pretax":true,"posttax":false,"imputed":false,"healthcare":true,"retirement":false,"yearly_limit":false,"category":"Health"},{"benefit_type":3,"name":"Vision Insurance","description":"Health-related insurance under IRS section 125 includes medical, dental and vision insurance, and is the most common benefit provided by employers today. It allows paying for certain health benefits using pre-tax dollars. This lowers the employee taxable income and the overall tax payments for both the employee and the employer.","pretax":true,"posttax":false,"imputed":false,"healthcare":true,"retirement":false,"yearly_limit":false,"category":"Health"},{"benefit_type":6,"name":"Health Savings Account","description":"HSA allows employees to be reimbursed for qualified medical expenses. In most cases, deductions are pre-tax and lower the total amount of tax paid by employees and the employer. Employers may also make tax-free contributions to employee HSA. Remaining balances are carried over to the next year.","pretax":true,"posttax":false,"imputed":false,"healthcare":false,"retirement":false,"yearly_limit":true,"category":"Health"},{"benefit_type":7,"name":"Health FSA","description":"FSA allows employees to be reimbursed for qualified medical expenses. Contributions are pre-tax and lower the total amount of tax paid by employees and the employer.Employers may also make tax-free contributions to employee FSA. Remaining balances are not carried over to the next year.","pretax":true,"posttax":false,"imputed":false,"healthcare":false,"retirement":false,"yearly_limit":true,"category":"Health"},{"benefit_type":11,"name":"Dependent Care FSA","description":"Dependent Care FSA reimburses employees for expenses to care for dependents while the employee is at work (e.g. Daycares). Contributions are pre-tax and lower the total amount of tax paid by employees and the employer. Employers may also make tax-free contributions to employee FSA. Remaining balances are not carried over to the next year.","pretax":true,"posttax":false,"imputed":false,"healthcare":false,"retirement":false,"yearly_limit":true,"category":"Health"},{"benefit_type":8,"name":"SIMPLE IRA","description":"Simple IRA is a tax-deferred retirement savings plan for employees. It is often use by small businesses as an alternative to 401(k) due to its relatively low operating cost. Employers are required to contribute a specific percentage to an employee’s SIMPLE IRA.","pretax":true,"posttax":false,"imputed":false,"healthcare":false,"retirement":true,"yearly_limit":true,"category":"Savings and Retirement"},{"benefit_type":14,"name":"SIMPLE IRA (Non-elective)","description":"Simple IRA is a tax-deferred retirement savings plan for employees. It is often use by small businesses as an alternative to 401(k) due to its relatively low operating cost. Employers are required to contribute a specific percentage to an employee’s SIMPLE IRA.","pretax":true,"posttax":false,"imputed":false,"healthcare":false,"retirement":true,"yearly_limit":true,"category":"Savings and Retirement"},{"benefit_type":105,"name":"Roth 401(k)","description":"Roth 401(k) is an after-tax savings plan for employees. Contributions made by employees are taxable for federal and state withholding. Often, employers contribute additional pre-tax dollars to the employee’s Roth account to encourage saving for retirement.","pretax":false,"posttax":true,"imputed":false,"healthcare":false,"retirement":true,"yearly_limit":true,"category":"Savings and Retirement"},{"benefit_type":110,"name":"Roth 403(b)","description":"Roth 403(b) is an after-tax savings plan for certain clerics, employees of public schools, and employees of other types of tax-exempt organizations. Contributions made by employees are taxable for federal and state withholding. Often, employers contribute additional pre-tax dollars to the employee’s Roth account to encourage saving for retirement.","pretax":false,"posttax":true,"imputed":false,"healthcare":false,"retirement":true,"yearly_limit":true,"category":"Savings and Retirement"},{"benefit_type":5,"name":"401(k)","description":"401(k) is tax-deferred retirement savings plan for employees. It is the most common retirement plan benefit offered by employers in all sizes. Often, employers contribute to the employee savings plan additional pre-tax dollars as an encouragement for retirement saving.","pretax":true,"posttax":false,"imputed":false,"healthcare":false,"retirement":true,"yearly_limit":true,"category":"Savings and Retirement"},{"benefit_type":9,"name":"403(b)","description":"403(b) is tax-deferred retirement savings plan for certain clerics, employees of public schools, and employees of other types of tax-exempt organizations. Often, employers contribute to the employee savings plan additional pre-tax dollars as an encouragement for retirement saving.","pretax":true,"posttax":false,"imputed":false,"healthcare":false,"retirement":true,"yearly_limit":true,"category":"Savings and Retirement"},{"benefit_type":108,"name":"SEP-IRA","description":"A SEP-IRA is a pre-tax retirement savings plan where only the employer contributes. It is often used by small businesses as an alternative to 401(k) due to its relatively low operating cost. Employers are required to contribute the same percentage to all enrolled employees, with a maximum contribution of 25% of the employee’s compensation.","pretax":true,"posttax":false,"imputed":false,"healthcare":false,"retirement":true,"yearly_limit":true,"category":"Savings and Retirement"},{"benefit_type":109,"name":"SARSEP","description":"A SARSEP is a pre-tax retirement savings plan used by small businesses as an alternative to 401(k) due to its relatively low operating cost. While new SARSEP plans are not available, there are still some companies that are grandfathered into the plan. Employers are required to contribute the same percentage to all enrolled employees, with a maximum contribution of 25% of the employee’s compensation.","pretax":true,"posttax":false,"imputed":false,"healthcare":false,"retirement":true,"yearly_limit":true,"category":"Savings and Retirement"},{"benefit_type":107,"name":"Group-Term Life Insurance","description":"Group-Term Life Insurance is for coverage in excess of $50,000 per employee and is a taxable fringe benefit. Add this benefit only if you have employees with a coverage that is larger than $50,000. See IRS Publication 15-B to determine the dollar value of the excess coverage. Learn more about the taxability of this benefit on the IRS website","pretax":false,"posttax":true,"imputed":true,"healthcare":false,"retirement":false,"yearly_limit":false,"category":"Health"},{"benefit_type":10,"name":"Commuter Benefits (pre-tax)","description":"Tax-free commuter benefits allow employees to reduce their monthly commuting expenses for transit, carpooling, bicycling, and work-related parking costs. Please note that there is an annual maximum for this pre-tax benefit. The maximum dollar amount is found in IRS Publication 15-B","pretax":true,"posttax":false,"imputed":false,"healthcare":false,"retirement":false,"yearly_limit":false,"category":"Transportation"},{"benefit_type":106,"name":"Personal Use of Company Car","description":"Personal use of a company car is a non-cash, taxable fringe benefit. A portion of the car’s value is considered part of the employee’s total compensation for tax purposes, even though the employer owns or leases the car.","pretax":false,"posttax":true,"imputed":true,"healthcare":false,"retirement":false,"yearly_limit":false,"category":"Transportation"},{"benefit_type":111,"name":"529 College Savings","description":"529 College Savings is an after-tax savings plan for employees designed to encourage saving for future college costs. This benefit should be reported as a taxable benefit and will therefore be taxed.","pretax":false,"posttax":true,"imputed":true,"healthcare":false,"retirement":false,"yearly_limit":false,"category":"Other"},{"benefit_type":998,"name":"Short Term Disability (post-tax)","description":"Third Party Disability or Third Party Leave are policies offered by employers that pay an employee for a specific life event (maternity leave, injury). All payments made to employees come from a third-party, such as an insurer. For more information on the taxation of these plans, please refer to publication 15-A for more details.","pretax":false,"posttax":true,"imputed":false,"healthcare":false,"retirement":false,"yearly_limit":false,"category":"Health"},{"benefit_type":1000,"name":"Short Term Disability (post-tax imputed)","description":"Third Party Disability or Third Party Leave are policies offered by employers that pay an employee for a specific life event (maternity leave, injury). All payments made to employees come from a third-party, such as an insurer. For more information on the taxation of these plans, please refer to publication 15-A for more details.","pretax":false,"posttax":true,"imputed":false,"healthcare":false,"retirement":false,"yearly_limit":false,"category":"Health"},{"benefit_type":999,"name":"Long Term Disability (post-tax)","description":"Third Party Disability or Third Party Leave are policies offered by employers that pay an employee for a specific life event (maternity leave, injury). All payments made to employees come from a third-party, such as an insurer. For more information on the taxation of these plans, please refer to publication 15-A for more details.","pretax":false,"posttax":true,"imputed":false,"healthcare":false,"retirement":false,"yearly_limit":false,"category":"Health"},{"benefit_type":1001,"name":"Long Term Disability (post-tax imputed)","description":"Third Party Disability or Third Party Leave are policies offered by employers that pay an employee for a specific life event (maternity leave, injury). All payments made to employees come from a third-party, such as an insurer. For more information on the taxation of these plans, please refer to publication 15-A for more details.","pretax":false,"posttax":true,"imputed":false,"healthcare":false,"retirement":false,"yearly_limit":false,"category":"Health"},{"benefit_type":996,"name":"Short Term Disability (pre-tax)","description":"Third Party Disability or Third Party Leave are policies offered by employers that pay an employee for a specific life event (maternity leave, injury). All payments made to employees come from a third-party, such as an insurer. For more information on the taxation of these plans, please refer to publication 15-A for more details.","pretax":true,"posttax":false,"imputed":false,"healthcare":false,"retirement":false,"yearly_limit":false,"category":"Health"},{"benefit_type":997,"name":"Long Term Disability (pre-tax)","description":"Third Party Disability or Third Party Leave are policies offered by employers that pay an employee for a specific life event (maternity leave, injury). All payments made to employees come from a third-party, such as an insurer. For more information on the taxation of these plans, please refer to publication 15-A for more details.","pretax":true,"posttax":false,"imputed":false,"healthcare":false,"retirement":false,"yearly_limit":false,"category":"Health"},{"benefit_type":991,"name":"Voluntary Short Term Disability (post-tax)","description":"Third Party Disability or Third Party Leave are policies offered by employers that pay an employee for a specific life event (maternity leave, injury). All payments made to employees come from a third-party, such as an insurer. For more information on the taxation of these plans, please refer to publication 15-A for more details.","pretax":false,"posttax":true,"imputed":false,"healthcare":false,"retirement":false,"yearly_limit":false,"category":"Health"},{"benefit_type":992,"name":"Voluntary Long Term Disability (post-tax)","description":"Third Party Disability or Third Party Leave are policies offered by employers that pay an employee for a specific life event (maternity leave, injury). All payments made to employees come from a third-party, such as an insurer. For more information on the taxation of these plans, please refer to publication 15-A for more details.","pretax":false,"posttax":true,"imputed":false,"healthcare":false,"retirement":false,"yearly_limit":false,"category":"Health"},{"benefit_type":993,"name":"Voluntary Life (post-tax)","description":"Third Party Disability or Third Party Leave are policies offered by employers that pay an employee for a specific life event (maternity leave, injury). All payments made to employees come from a third-party, such as an insurer. For more information on the taxation of these plans, please refer to publication 15-A for more details.","pretax":false,"posttax":true,"imputed":false,"healthcare":false,"retirement":false,"yearly_limit":false,"category":"Health"},{"benefit_type":113,"name":"Commuter Parking","description":"Tax-free commuter benefits allow employees to reduce their monthly commuting expenses for transit, carpooling, bicycling, and work-related parking costs. Please note that there is an annual maximum for this pre-tax benefit. The maximum dollar amount is found in IRS Publication 15-B","pretax":true,"posttax":false,"imputed":false,"healthcare":false,"retirement":false,"yearly_limit":false,"category":"Transportation"},{"benefit_type":114,"name":"Commuter Transit","description":"Tax-free commuter benefits allow employees to reduce their monthly commuting expenses for transit, carpooling, bicycling, and work-related parking costs. Please note that there is an annual maximum for this pre-tax benefit. The maximum dollar amount is found in IRS Publication 15-B","pretax":true,"posttax":false,"imputed":false,"healthcare":false,"retirement":false,"yearly_limit":false,"category":"Transportation"},{"benefit_type":100,"name":"Other (taxable)","description":"Employer-sponsored benefits like this are called fringe benefits, and they don’t get special tax treatment—they’ll be reported as taxable wages on your employees’ paystubs.","pretax":false,"posttax":true,"imputed":true,"healthcare":false,"retirement":false,"yearly_limit":false,"category":"Other"},{"benefit_type":201,"name":"Cell Phone (taxable)","description":"Employer-sponsored benefits like this are called fringe benefits, and they don’t get special tax treatment—they’ll be reported as taxable wages on your employees’ paystubs.","pretax":false,"posttax":true,"imputed":true,"healthcare":false,"retirement":false,"yearly_limit":false,"category":"Other"},{"benefit_type":202,"name":"Gym & Fitness (taxable)","description":"Employer-sponsored benefits like this are called fringe benefits, and they don’t get special tax treatment—they’ll be reported as taxable wages on your employees’ paystubs.","pretax":false,"posttax":true,"imputed":true,"healthcare":false,"retirement":false,"yearly_limit":false,"category":"Other"},{"benefit_type":203,"name":"Housing (taxable)","description":"Employer-sponsored benefits like this are called fringe benefits, and they don’t get special tax treatment—they’ll be reported as taxable wages on your employees’ paystubs.","pretax":false,"posttax":true,"imputed":true,"healthcare":false,"retirement":false,"yearly_limit":false,"category":"Other"},{"benefit_type":204,"name":"Wellness (taxable)","description":"Employer-sponsored benefits like this are called fringe benefits, and they don’t get special tax treatment—they’ll be reported as taxable wages on your employees’ paystubs.","pretax":false,"posttax":true,"imputed":true,"healthcare":false,"retirement":false,"yearly_limit":false,"category":"Other"}]}},"Contribution-Exclusion":{"description":"The representation of a contribution exclusion for a company benefit.","type":"object","properties":{"contribution_uuid":{"type":"string","description":"The UUID of the contribution type.","example":"082dfd3e-5b55-11f0-bb42-ab7136ba04e2"},"contribution_type":{"type":"string","description":"The name of the contribution type.","example":"Bonus"},"excluded":{"type":"boolean","description":"Whether this contribution type is excluded from the benefit."}},"required":["contribution_uuid","contribution_type","excluded"],"x-tags":["Company Benefits"],"x-examples":{"exclusion_bonus":{"contribution_uuid":"b82e35c5-d7c6-4705-9e16-9f87499ade18","contribution_type":"Bonus","excluded":false},"exclusion_cash_tips":{"contribution_uuid":"f5618c94-ed7d-4366-b2c4-ff05e430064f","contribution_type":"Cash Tips","excluded":false},"exclusion_commission":{"contribution_uuid":"60191999-004a-49d9-b163-630574433653","contribution_type":"Commission","excluded":false},"exclusion_regular":{"contribution_uuid":"75a7a827-1f2d-4d6f-94f2-514c1fc32b13","contribution_type":"Regular","excluded":false},"exclusion_imputed":{"contribution_uuid":"eead3c7c-7964-4e3c-b609-670456127b09","contribution_type":"Life insurance imputed benefit","excluded":true}}},"Company-Benefit-Create-Request":{"description":"","type":"object","properties":{"benefit_type":{"type":"integer","description":"The ID of the benefit to which the company benefit belongs."},"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\"."},"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."},"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."},"catch_up_type":{"description":"The type of catch-up contribution for this benefit, as required by Section 603 of the SECURE 2.0 Act. Only applicable to pre-tax 401(k) and 403(b) benefits.","anyOf":[{"type":"string","enum":["elective","deemed"]},{"type":"null"}]}},"required":["description"]},"Company-Benefit-Update-Request":{"description":"","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."},"active":{"type":"boolean","description":"Whether this benefit is active for employee participation. Company benefits may only be deactivated if no employees are actively participating."},"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\"."},"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 short-term and long-term disability benefits (different from voluntary disability)."},"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 short-term and long-term disability benefits (different from voluntary disability)."},"catch_up_type":{"description":"The type of catch-up contribution for this benefit, as required by Section 603 of the SECURE 2.0 Act. Only applicable to pre-tax 401(k) and 403(b) benefits.","anyOf":[{"type":"string","enum":["elective","deemed"]},{"type":"null"}]}},"required":["version"]},"Contribution-Exclusion-Update-Request":{"description":"","type":"object","properties":{"contribution_exclusions":{"type":"array","description":"The list of contribution exclusions to update","items":{"$ref":"#/components/schemas/Contribution-Exclusion"}}},"required":["contribution_exclusions"]},"Employee-Benefit-Bulk-Update-Request":{"description":"","type":"object","properties":{"employee_benefits":{"type":"array","description":"The list of employee benefits to create or update","items":{"$ref":"#/components/schemas/Employee-Benefit-For-Company-Benefit"}}},"required":["employee_benefits"]},"Company-Benefit-With-Employee-Benefits":{"description":"The representation of a company benefit.","type":"object","x-examples":{"Example":{"uuid":"d2cec746-caee-464a-bcaf-00d93f7049c9","version":"98jr3289h3298hr9329gf9egskt3kagri32qqgiqe3872","active":true,"description":"Kaiser Permanente","source":"external","partner_name":"XYZ Corp","deletable":true,"supports_percentage_amounts":true,"responsible_for_employer_taxes":false,"responsible_for_employee_w2":false,"catch_up_type":"elective","employee_benefits":[{"employee_uuid":"ae44a0b2-3c89-41e1-91c8-5f8224a779ca","company_benefit_uuid":"d2cec746-caee-464a-bcaf-00d93f7049c9","active":true,"deduct_as_percentage":false,"employee_deduction":"3","company_contribution":"0","uuid":"9988f241-9aee-4383-bfca-eac79cf58135","contribution":{"type":"amount","value":"0"}}]}},"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."},"company_uuid":{"type":"string","description":"The UUID of the company.","readOnly":true},"uuid":{"type":"string","description":"The UUID of the company benefit.","readOnly":true},"benefit_type":{"type":"integer","description":"The type of the benefit to which the company benefit belongs (same as benefit_id).","readOnly":true},"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."},"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”."},"source":{"type":"string","enum":["internal","external","partnered"],"description":"The source of the company benefit. This can be \"internal\", \"external\", or \"partnered\". Company benefits created via the API default to \"external\". Certain partners can create company benefits with a source of \"partnered\".","readOnly":true},"partner_name":{"type":["string","null"],"description":"The partner name of the partner that created the company benefit. For example, \"XYZ Corp\".","readOnly":true},"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"},"supports_percentage_amounts":{"type":"boolean","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.","readOnly":true},"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."},"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."},"catch_up_type":{"description":"The type of catch-up contribution for this benefit, as required by Section 603 of the SECURE 2.0 Act. Only applicable to pre-tax 401(k) and 403(b) benefits.","anyOf":[{"type":"string","enum":["elective","deemed"]},{"type":"null"}]},"employee_benefits":{"type":"array","items":{"type":"object","properties":{"employee_uuid":{"type":"string","description":"The UUID of the employee to which the benefit belongs."},"company_benefit_uuid":{"type":"string","description":"The UUID of the company benefit."},"active":{"type":"boolean","default":true,"description":"Whether the employee benefit is active."},"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."},"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","description":"The value of the company contribution"},"effective_date":{"type":"string","description":"The date when the employee benefit becomes effective. If not provided, the benefit will be effective from 1970-01-01 (unix epoch)."},"expiration_date":{"type":"string","description":"The date when the employee benefit expires. If not provided, the benefit will have no expiration date."},"contribution":{"type":"object","description":"An object representing the type and value of the company contribution.","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":{"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.","oneOf":[{"type":"string"},{"type":"object","properties":{"tiers":{"type":"array","description":"","items":{"type":"object","description":"A single tier of a tiered matching scheme.","properties":{"rate":{"type":"string","description":"The percentage of employee deduction within this tier the company contribution will match."},"threshold":{"type":"string","description":"Specifies the upper limit (inclusive) percentage of the employee contribution that this tier applies to.\n\nUse threshold to define each tier's end point, with tiers applied cumulatively from 0% upwards.\n\nFor example:\n\nIf the first tier has a threshold of \"3\", and `rate` of \"100\", the company will match 100% of employee contributions from 0% up to and including 3% of payroll.\n\nIf the next tier has a threshold of \"5\" and a rate of \"50\", the company will match 50% of contributions from above 3% 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."}}}}}}]}}}}}}},"required":["uuid"]},"Company-Benefit":{"description":"The representation of a company benefit.","type":"object","x-examples":{"Example":{"uuid":"54e37c27-43e6-4ae5-a5b2-e29895a133be","version":"98jr3289h3298hr9329gf9egskt3kagri32qqgiqe3872","benefit_type":1,"active":true,"description":"Kaiser Permanente","enrollment_count":2,"source":"external","partner_name":"XYZ Corp","deletable":true,"supports_percentage_amounts":true,"responsible_for_employer_taxes":false,"responsible_for_employee_w2":false,"catch_up_type":"elective"}},"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."},"enrollment_count":{"type":"integer","description":"The number of employees enrolled in the benefit, only returned when enrollment_count query param is set to true.","readOnly":true},"company_uuid":{"type":"string","description":"The UUID of the company.","readOnly":true},"uuid":{"type":"string","description":"The UUID of the company benefit.","readOnly":true},"benefit_type":{"type":"integer","description":"The type of the benefit to which the company benefit belongs.","readOnly":true},"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."},"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”."},"source":{"type":"string","enum":["internal","external","partnered"],"description":"The source of the company benefit. This can be \"internal\", \"external\", or \"partnered\". Company benefits created via the API default to \"external\". Certain partners can create company benefits with a source of \"partnered\".","readOnly":true},"partner_name":{"type":["string","null"],"description":"The partner name of the partner that created the company benefit. For example, \"XYZ Corp\".","readOnly":true},"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"},"supports_percentage_amounts":{"type":"boolean","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.","readOnly":true},"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."},"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."},"catch_up_type":{"description":"The type of catch-up contribution for this benefit, as required by Section 603 of the SECURE 2.0 Act. Only applicable to pre-tax 401(k) and 403(b) benefits.","anyOf":[{"type":"string","enum":["elective","deemed"]},{"type":"null"}]}},"required":["uuid"]},"Earning-Type":{"description":"The representation of an earning type in Gusto.","type":"object","x-examples":{"success":{"name":"Cash Tips","uuid":"f5618c94-ed7d-4366-b2c4-ff05e430064f","active":true},"custom_earning_type":{"name":"Gym Membership Stipend","uuid":"6b4a8efb-db90-4c13-a75f-aae11b3f4ff9","active":true}},"properties":{"name":{"type":"string","description":"The name of the earning type."},"uuid":{"type":"string","description":"The ID of the earning type.","readOnly":true},"active":{"type":"boolean","description":"Whether the earning type is active."}},"x-tags":["Earning Types"],"required":["uuid"]},"Earning-Type-List":{"type":"object","description":"Lists of default and custom earning types for a company.","x-examples":{"success":{"default":[{"name":"Bonus","uuid":"b82e35c5-d7c6-4705-9e16-9f87499ade18","active":true},{"name":"Cash Tips","uuid":"f5618c94-ed7d-4366-b2c4-ff05e430064f","active":true},{"name":"Commission","uuid":"60191999-004a-49d9-b163-630574433653","active":true},{"name":"Correction Payment","uuid":"368226e0-8e8c-48f0-bc91-aee46caafbc9","active":true},{"name":"Minimum Wage Adjustment","uuid":"88a2e519-9ff5-4c19-9071-6a709f3c2939","active":true},{"name":"Paycheck Tips","uuid":"a3eaf03d-e712-4144-8f9b-71a85528adcf","active":true},{"name":"Severance","uuid":"a6a2eba7-6c7d-4ced-bbe8-43452fbc9f63","active":true}],"custom":[{"name":"Gym Membership Stipend","uuid":"6b4a8efb-db90-4c13-a75f-aae11b3f4ff9","active":true}]},"defaults_only":{"default":[{"name":"Bonus","uuid":"b82e35c5-d7c6-4705-9e16-9f87499ade18","active":true},{"name":"Cash Tips","uuid":"f5618c94-ed7d-4366-b2c4-ff05e430064f","active":true},{"name":"Commission","uuid":"60191999-004a-49d9-b163-630574433653","active":true},{"name":"Correction Payment","uuid":"368226e0-8e8c-48f0-bc91-aee46caafbc9","active":true},{"name":"Minimum Wage Adjustment","uuid":"88a2e519-9ff5-4c19-9071-6a709f3c2939","active":true},{"name":"Paycheck Tips","uuid":"a3eaf03d-e712-4144-8f9b-71a85528adcf","active":true},{"name":"Severance","uuid":"a6a2eba7-6c7d-4ced-bbe8-43452fbc9f63","active":true}],"custom":[]}},"properties":{"default":{"type":"array","description":"The default earning types for the company.","items":{"$ref":"#/components/schemas/Earning-Type"}},"custom":{"type":"array","description":"The custom earning types for the company.","items":{"$ref":"#/components/schemas/Earning-Type"}}}},"Employee-Benefit-Base-Object":{"description":"","type":"object","title":"","additionalProperties":true,"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."},"active":{"type":"boolean","default":true,"description":"Whether the employee benefit is active."},"employee_deduction":{"type":"string","default":"0.00","description":"The amount to be deducted, per pay period, from the employee's pay."},"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."},"employee_deduction_annual_maximum":{"type":["string","null"],"description":"The maximum employee deduction amount per year. A null value signifies no limit."},"contribution":{"type":"object","description":"An object representing the type and value of the company contribution.","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":{"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.","oneOf":[{"type":"string"},{"type":"object","properties":{"tiers":{"type":"array","description":"","items":{"type":"object","description":"A single tier of a tiered matching scheme.","properties":{"rate":{"type":"string","description":"The percentage of employee deduction within this tier the company contribution will match."},"threshold":{"type":"string","description":"Specifies the upper limit (inclusive) percentage of the employee contribution that this tier applies to.\n\nUse threshold to define each tier's end point, with tiers applied cumulatively from 0% upwards.\n\nFor example:\n\nIf the first tier has a threshold of \"3\", and `rate` of \"100\", the company will match 100% of employee contributions from 0% up to and including 3% of payroll.\n\nIf the next tier has a threshold of \"5\" and a rate of \"50\", the company will match 50% of contributions from above 3% 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."}}}}}}]}}},"elective":{"type":"boolean","description":"Whether the company contribution is elective (aka matching). For \"tiered\" contribution types, this is always true.","default":false},"company_contribution_annual_maximum":{"type":["string","null"],"description":"The maximum company contribution amount per year. A null value signifies no limit."},"limit_option":{"type":["string","null"],"description":"Some benefits require additional information to determine their limit.\n\n`Family` and `Individual` are applicable to HSA benefit.\n\n`Joint Filing or Single` and `Married and Filing Separately` are applicable to Dependent Care FSA benefit."},"catch_up":{"type":["boolean","null"],"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."},"retirement_loan_identifier":{"type":["string","null"],"description":"Identifier for a 401(k) loan assigned by the 401(k) provider"},"coverage_amount":{"type":["string","null"],"description":"The amount that the employee is insured for. Note: company contribution cannot be present if coverage amount is set."},"deduction_reduces_taxable_income":{"description":"Whether the employee deduction reduces taxable income or not. Only valid for Group Term Life benefits. Note: when the value is not \"unset\", coverage amount and coverage salary multiplier are ignored.","anyOf":[{"type":"string","enum":["unset","reduces_taxable_income","does_not_reduce_taxable_income"]},{"type":"null"}],"default":"unset"},"coverage_salary_multiplier":{"type":["string","null"],"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."},"company_contribution":{"type":"string","default":"0.00","description":"The amount to be paid, per pay period, by the company. This field will not appear for tiered contribution types.","deprecated":true},"contribute_as_percentage":{"type":"boolean","default":false,"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.","deprecated":true},"effective_date":{"type":"string","format":"date","description":"The date the employee benefit will start."},"expiration_date":{"type":["string","null"],"format":"date","description":"The date the employee benefit will expire. A null value indicates the benefit will not expire."}}},"Employee-Benefit-Create-Request":{"description":"","type":"object","properties":{"company_benefit_uuid":{"type":"string","description":"The UUID of the company benefit."},"active":{"type":"boolean","default":true,"description":"Whether the employee benefit is active."},"employee_deduction":{"type":"string","default":"0.00","description":"The amount to be deducted, per pay period, from the employee's pay."},"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."},"employee_deduction_annual_maximum":{"type":["string","null"],"description":"The maximum employee deduction amount per year. A null value signifies no limit."},"contribution":{"type":"object","description":"An object representing the company contribution type and value.","properties":{"type":{"type":"string","enum":["tiered","percentage","amount"],"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":{"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.","oneOf":[{"type":"string","description":"For the `amount` and `percentage` contribution types, the value of the corresponding amount or percentage."},{"type":"array","description":"For `tiered` contribution types, an array of tiers.","items":{"type":"object","description":"A single tier of a tiered matching scheme.","properties":{"rate":{"type":"string","description":"The percentage of employee deduction within this tier the company contribution will match."},"threshold":{"type":"string","description":"Specifies the upper limit (inclusive) percentage of the employee contribution that this tier applies to.\n\nUse threshold to define each tier's end point, with tiers applied cumulatively from 0% upwards.\n\nFor example:\n\nIf the first tier has a threshold of \"3\", and rate of \"100\", the company will match 100% of employee contributions from 0% up to and including 3% of payroll.\n\nIf the next tier has a threshold of \"5\" and a rate of \"50\", the company will match 50% of contributions from above 3% up to and including 5% of payroll."}}}}]}}},"elective":{"type":"boolean","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`.","default":false},"company_contribution_annual_maximum":{"type":["string","null"],"description":"The maximum company contribution amount per year. A null value signifies no limit."},"limit_option":{"description":"Some benefits require additional information to determine\ntheir limit.\n\n`Family` or `Individual`: Applicable to HSA benefit.\n\n`Joint Filing or Single` or `Married and Filing Separately`: Applicable to Dependent Care FSA benefit.","anyOf":[{"type":"string","enum":["Family","Individual","Joint Filing or Single","Married and Filing Separately"]},{"type":"null"}]},"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."},"coverage_amount":{"type":["string","null"],"description":"The amount that the employee is insured for. Note: company contribution cannot be present if coverage amount is set."},"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":{"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.","anyOf":[{"type":"string","enum":["unset","reduces_taxable_income","does_not_reduce_taxable_income"]},{"type":"null"}]},"company_contribution":{"type":"string","default":"0.00","description":"The amount to be paid, per pay period, by the company.","deprecated":true},"contribute_as_percentage":{"type":"boolean","default":false,"description":"Whether the company contribution amount should be treated as a percentage to be deducted from each payroll.","deprecated":true},"effective_date":{"type":"string","format":"date","default":"1970-01-01","description":"The date the employee benefit will start. If not provided, the benefit will be effective from 1970-01-01 (unix epoch)."},"expiration_date":{"type":["string","null"],"format":"date","default":null,"description":"The date the employee benefit will expire. A null value indicates the benefit will not expire."}},"required":["company_benefit_uuid"],"x-examples":{"Example":{"company_benefit_uuid":"f68abb42-431e-4392-bc3f-2795627e00f3","active":true,"employee_deduction":"100.00","contribution":{"type":"amount","value":"100.00"}}}},"Employee-Benefit-Update-Request":{"description":"","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."},"active":{"type":"boolean","description":"Whether the employee benefit is active."},"employee_deduction":{"type":"string","default":"0.00","description":"The amount to be deducted, per pay period, from the employee's pay."},"deduct_as_percentage":{"type":"boolean","description":"Whether the employee deduction amount should be treated as a percentage to be deducted from each payroll."},"employee_deduction_annual_maximum":{"type":["string","null"],"description":"The maximum employee deduction amount per year. A null value signifies no limit."},"effective_date":{"type":"string","format":"date","description":"The date the employee benefit will start."},"expiration_date":{"type":["string","null"],"format":"date","description":"The date the employee benefit will expire. A null value indicates the benefit will not expire."},"contribution":{"type":"object","description":"An object representing the type and value of the company contribution.","properties":{"type":{"type":"string","enum":["amount","percentage","tiered"],"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":{"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.","oneOf":[{"type":"string","description":"For the `amount` and `percentage` contribution types, the value of the corresponding amount or percentage."},{"type":"array","description":"For `tiered` contribution types, an array of tiers.","items":{"type":"object","description":"A single tier of a tiered matching scheme.","properties":{"rate":{"type":"string","description":"The percentage of employee deduction within this tier the company contribution will match."},"threshold":{"type":"string","description":"Specifies the upper limit (inclusive) percentage of the employee contribution that this tier applies to.\n\nUse threshold to define each tier's end point, with tiers applied cumulatively from 0% upwards.\n\nFor example:\n\nIf the first tier has a threshold of \"3\", and rate of \"100\", the company will match 100% of employee contributions from 0% up to and including 3% of payroll.\n\nIf the next tier has a threshold of \"5\" and a rate of \"50\", the company will match 50% of contributions from above 3% up to and including 5% of payroll."}}}}]}}},"elective":{"type":"boolean","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`.","default":false},"company_contribution_annual_maximum":{"type":["string","null"],"description":"The maximum company contribution amount per year. A null value signifies no limit."},"limit_option":{"description":"Some benefits require additional information to determine\ntheir limit.\n\n`Family` or `Individual`: Applicable to HSA benefit.\n\n`Joint Filing or Single` or `Married and Filing Separately`: Applicable to Dependent Care FSA benefit.","anyOf":[{"type":"string","enum":["Family","Individual","Joint Filing or Single","Married and Filing Separately"]},{"type":"null"}]},"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."},"coverage_amount":{"type":["string","null"],"description":"The amount that the employee is insured for. Note: company contribution cannot be present if coverage amount is set."},"deduction_reduces_taxable_income":{"description":"Whether the employee deduction reduces taxable income or not. Only valid for Group Term Life benefits. Note: when the value is not \"unset\", coverage amount and coverage salary multiplier are ignored.","anyOf":[{"type":"string","enum":["unset","reduces_taxable_income","does_not_reduce_taxable_income"]},{"type":"null"}],"default":"unset"},"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."},"company_contribution":{"type":"string","default":"0.00","description":"The amount to be paid, per pay period, by the company.","deprecated":true},"contribute_as_percentage":{"type":"boolean","default":false,"description":"Whether the company contribution amount should be treated as a percentage to be deducted from each payroll.","deprecated":true}},"required":["version"],"x-examples":{"Example":{"version":"09j3d29jqdpj92109j9j2d90dq","employee_deduction":"250.00"}}},"Employee-Benefit":{"description":"The representation of an employee benefit.","type":"object","title":"","x-examples":{"Example":{"version":"09j3d29jqdpj92109j9j2d90dq","employee_uuid":"73274962-63ce-4e5c-b689-1df8d4df09f4","company_benefit_uuid":"54e37c27-43e6-4ae5-a5b2-e29895a133be","active":true,"uuid":"e91ca856-a915-4339-9b18-29f9cd66b031","employee_deduction":"100.00","company_contribution":"100.00","employee_deduction_annual_maximum":"200.00","company_contribution_annual_maximum":"200.00","limit_option":null,"retirement_loan_identifier":null,"deduct_as_percentage":false,"contribute_as_percentage":false,"catch_up":false,"coverage_amount":null,"deduction_reduces_taxable_income":null,"coverage_salary_multiplier":"0.00","contribution":{"type":"amount","value":"100.00"},"elective":false,"effective_date":"2025-01-01","expiration_date":null},"Tiered Example":{"version":"09j3d29jqdpj92109j9j2d90dq","employee_uuid":"73274962-63ce-4e5c-b689-1df8d4df09f4","company_benefit_uuid":"54e37c27-43e6-4ae5-a5b2-e29895a133be","active":true,"uuid":"e91ca856-a915-4339-9b18-29f9cd66b031","employee_deduction":"100.00","employee_deduction_annual_maximum":"200.00","company_contribution_annual_maximum":"200.00","limit_option":null,"deduct_as_percentage":false,"catch_up":false,"coverage_amount":null,"deduction_reduces_taxable_income":null,"coverage_salary_multiplier":"0.00","elective":true,"contribution":{"type":"tiered","value":{"tiers":[{"rate":"100.0","threshold":"2.0","threshold_delta":"2.0"},{"rate":"50.0","threshold":"5.0","threshold_delta":"3.0"}]}},"effective_date":"2025-01-01","expiration_date":null}},"allOf":[{"$ref":"#/components/schemas/Employee-Benefit-Base-Object"},{"type":"object","additionalProperties":true,"properties":{"employee_uuid":{"type":"string","description":"The UUID of the employee to which the benefit belongs.","readOnly":true},"company_benefit_uuid":{"type":"string","description":"The UUID of the company benefit.","readOnly":true},"uuid":{"type":"string","description":"The UUID of the employee benefit.","readOnly":true}}}],"required":["uuid"]},"Employee-Benefit-For-Company-Benefit":{"description":"The representation of an employee benefit for a company benefit.","type":"object","title":"","allOf":[{"$ref":"#/components/schemas/Employee-Benefit-Base-Object"},{"type":"object","additionalProperties":true,"properties":{"employee_uuid":{"type":"string","description":"The UUID of the employee to which the benefit belongs."},"company_benefit_uuid":{"type":"string","description":"The UUID of the company benefit.","readOnly":true},"uuid":{"type":"string","description":"The UUID of the employee benefit. Required for updating an effective dated employee benefit."},"action":{"type":"string","description":"The action to perform on the employee benefit. Required for creating/updating an effective dated employee benefit.","enum":["create","update"]}}}],"required":["employee_uuid"]},"Employee-Pay-Stub":{"description":"The representation of an employee pay stub information.","type":"object","properties":{"uuid":{"type":"string","description":"The UUID of the employee pay stub.","readOnly":true},"check_date":{"type":"string","description":"The check date of the pay stub.","readOnly":true},"gross_pay":{"type":"string","description":"The gross pay amount for the pay stub.","readOnly":true},"net_pay":{"type":"string","description":"The net pay amount for the pay stub.","readOnly":true},"payroll_uuid":{"type":"string","description":"A unique identifier of the payroll to which the pay stub belongs.","readOnly":true},"check_amount":{"type":"string","description":"The check amount for the pay stub.","readOnly":true}},"x-tags":["Payrolls"],"required":["uuid"]},"Pay-Period":{"description":"The representation of a pay period.","type":"object","properties":{"start_date":{"type":"string","description":"The start date, inclusive, of the pay period.","readOnly":true},"end_date":{"type":"string","minLength":1,"description":"The end date, inclusive, of the pay period."},"pay_schedule_uuid":{"type":"string","description":"A unique identifier of the pay schedule to which the pay period belongs.","readOnly":true},"payroll":{"type":"object","description":"Information about the payroll for the pay period.","properties":{"payroll_uuid":{"type":"string","readOnly":true,"description":"The UUID of the payroll for this pay period."},"check_date":{"type":"string","description":"The date on which employees will be paid for the payroll if the payroll is submitted on time.","readOnly":true},"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."},"payroll_deadline":{"type":"string","format":"date-time","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.","readOnly":true},"payroll_type":{"type":"string","description":"Whether it is regular pay period or transition pay period.","enum":["regular","transition"],"readOnly":true}},"readOnly":true}},"x-examples":{"typical_pay_period":{"start_date":"2024-01-01","end_date":"2024-01-15","pay_schedule_uuid":"7b1d0df1-6403-4a06-8768-c1dd7d24d27a","payroll":{"payroll_uuid":"8c2e1ef2-7514-5b17-9879-d2ee8e35e38b","check_date":"2024-01-19","processed":false,"payroll_deadline":"2024-01-17T18:00:00Z","payroll_type":"regular"}}},"x-tags":["Payrolls"]},"People-Batch":{"type":"object","description":"A batch for bulk people creation.","x-examples":{"success_status":{"uuid":"191e7162-3026-497e-aca2-f81b7e93204e","idempotency_key":"80a74f8b-2c16-45e5-9038-aa108849c6e6","status":"pending","batch_action":"create"}},"properties":{"uuid":{"type":"string","format":"uuid","description":"The unique identifier of the people batch.","readOnly":true},"idempotency_key":{"type":"string","format":"uuid","description":"The idempotency key provided when creating the batch."},"status":{"type":"string","enum":["pending","processing","completed","failed","partial_success"],"description":"The current status of the batch processing."},"batch_action":{"type":"string","description":"The action being performed on the batch."}},"required":["uuid","idempotency_key","status","batch_action"]},"People-Batch-Results":{"type":"object","description":"A people batch with processing results.","x-examples":{"success_status":{"uuid":"f711ab7a-2d44-4556-b90c-9f883195f53a","idempotency_key":"95d84feb-3a17-4c0b-a00b-bf8d3dec3326","status":"pending","submitted_at":"2026-03-02T15:09:50-08:00","completed_at":null,"submitted_items":null,"processed_items":0,"excluded_items":0,"results":[]}},"properties":{"uuid":{"type":"string","format":"uuid","description":"The unique identifier of the people batch.","readOnly":true},"idempotency_key":{"type":"string","format":"uuid","description":"The idempotency key provided when creating the batch."},"status":{"type":"string","enum":["pending","processing","completed","failed","partial_success"],"description":"The current status of the batch processing."},"submitted_at":{"type":"string","format":"date-time","description":"The timestamp when the batch was submitted."},"completed_at":{"type":["string","null"],"format":"date-time","description":"The timestamp when the batch processing completed."},"submitted_items":{"type":["integer","null"],"description":"The number of items submitted in the batch."},"processed_items":{"type":"integer","description":"The number of items successfully processed."},"excluded_items":{"type":"integer","description":"The number of items excluded from processing."},"results":{"type":"array","description":"The results for each batch item.","items":{"type":"object","properties":{"external_id":{"type":"string","description":"The external ID provided in the batch request."},"role":{"type":"string","enum":["employee"],"description":"The type of person created."},"status":{"type":"string","enum":["success","partial_success","failed"],"description":"The status of this batch item."},"idx":{"type":"integer","description":"The index of this item in the original batch request."},"uuid":{"type":"string","format":"uuid","description":"The UUID of the created person."},"employee_uuid":{"type":"string","format":"uuid","description":"The UUID of the created employee (if role is employee)."},"errors":{"type":["array","null"],"description":"Errors encountered while processing this batch item.","items":{"type":"object","properties":{"error_key":{"type":"string","description":"The key identifying the error source."},"category":{"type":"string","description":"The error category."},"message":{"type":["string","null"],"description":"Human-readable error message."},"errors":{"type":["array","null"],"description":"Nested errors for sub-operations.","items":{"type":"object"}}}}}}}},"exclusions":{"type":["array","null"],"description":"Items excluded from processing due to validation errors.","items":{"type":"object","properties":{"external_id":{"type":"string","description":"The external ID of the excluded item(s)."},"category":{"type":"string","description":"The exclusion category."},"message":{"type":"string","description":"Human-readable explanation for exclusion."},"item_count":{"type":"integer","description":"Number of items affected by this exclusion."}}}}},"required":["uuid","idempotency_key","status"]},"People-Batch-Conflict-Error":{"type":"object","description":"Error response when a people batch idempotency key conflict occurs.","x-examples":{"conflict":{"errors":[{"error_key":"idempotency_key","category":"invalid_attribute_value","message":"Idempotency token already used","metadata":{"entity_uuid":"14c53a55-0a80-4d46-a866-f5f64bc06486","entity_type":"PeopleBatch"}}]}},"properties":{"errors":{"type":"array","items":{"type":"object","properties":{"error_key":{"type":"string","description":"The key identifying the error source."},"category":{"type":"string","description":"The error category."},"message":{"type":"string","description":"Human-readable error message."},"metadata":{"type":"object","properties":{"entity_uuid":{"type":"string","format":"uuid","description":"The UUID of the existing entity."},"entity_type":{"type":"string","description":"The type of the existing entity."}}}}}}}},"Payroll-Batch":{"type":"object","description":"A payroll cancellation batch request.","x-examples":{"success_status":{"uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","idempotency_key":"80a74f8b-2c16-45e5-9038-aa108849c6e6","batch_action":"cancel","status":"pending"}},"properties":{"uuid":{"type":"string","format":"uuid","description":"The unique identifier of the payroll cancellation batch.","readOnly":true},"idempotency_key":{"type":"string","format":"uuid","description":"The idempotency key provided when creating the batch."},"batch_action":{"type":"string","enum":["cancel"],"description":"The action being performed on the batch."},"status":{"type":"string","enum":["pending","processing","completed","failed"],"description":"The lifecycle status of the batch request itself. Terminal values are `completed` (processing finished — inspect `results` and `exclusions` for per-payroll outcomes) and `failed` (the batch crashed at the system level; can be retried). This is distinct from the per-payroll `status` returned inside `results[]`. A `completed` batch does not imply every payroll was cancelled."}},"required":["uuid","idempotency_key","batch_action","status"]},"Payroll-Batch-Results":{"type":"object","description":"A payroll cancellation batch with per-payroll results.","x-examples":{"success_status":{"uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","idempotency_key":"80a74f8b-2c16-45e5-9038-aa108849c6e6","status":"completed","submitted_at":"2026-04-01T14:30:00Z","completed_at":"2026-04-01T14:30:09Z","submitted_items":4,"processed_items":2,"excluded_items":2,"results":[{"idx":0,"uuid":"11111111-2222-3333-4444-555555555555","status":"success"},{"idx":1,"uuid":"66666666-7777-8888-9999-000000000000","status":"failed","errors":[{"error_key":"base","category":"not_cancellable","message":"Payroll cannot be canceled"}]}],"exclusions":[{"idx":2,"entity_type":"payroll","uuid":"11111111-2222-3333-4444-555555555555","company_uuid":"cccccccc-1111-2222-3333-444444444444","status":"failed","category":"duplicate_operation","message":"Duplicate UUID. Only the first occurrence is processed."},{"idx":3,"entity_type":"payroll","uuid":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee","company_uuid":"dddddddd-1111-2222-3333-444444444444","status":"failed","category":"not_found","message":"Payroll not found or not associated with this partner"}]}},"properties":{"uuid":{"type":"string","format":"uuid","description":"The unique identifier of the payroll cancellation batch.","readOnly":true},"idempotency_key":{"type":"string","format":"uuid","description":"The idempotency key provided when creating the batch."},"status":{"type":"string","enum":["pending","processing","completed","failed"],"description":"The lifecycle status of the batch request itself. Terminal values are `completed` (processing finished — inspect `results` and `exclusions` for per-payroll outcomes) and `failed` (the batch crashed at the system level; can be retried). This is distinct from the per-payroll `status` returned inside `results[]`. A `completed` batch does not imply every payroll was cancelled."},"submitted_at":{"type":"string","format":"date-time","description":"The timestamp when the batch was submitted."},"completed_at":{"type":["string","null"],"format":"date-time","description":"The timestamp when the batch processing completed."},"submitted_items":{"type":["integer","null"],"description":"The number of payrolls submitted in the batch."},"processed_items":{"type":"integer","description":"The number of payrolls processed (cancelled or attempted). Only present once the batch reaches a terminal status."},"excluded_items":{"type":"integer","description":"The number of payrolls excluded from processing. Only present once the batch reaches a terminal status."},"results":{"type":"array","description":"Per-payroll cancellation results. Only present once the batch reaches a terminal status. One entry per authorized payroll.","items":{"type":"object","properties":{"idx":{"type":"integer","description":"The index of this payroll in the original POST batch array."},"uuid":{"type":"string","format":"uuid","description":"The UUID of the payroll."},"status":{"type":"string","enum":["success","failed"],"description":"The outcome of cancelling this payroll. A cancel is atomic — there is no per-payroll `partial_success`.\n- `success`: the payroll was cancelled, or required no action (already cancelled / never run)\n- `failed`: the payroll could not be cancelled; see `errors`\n"},"errors":{"type":"array","description":"Present only when `status` is `failed`. A cancel is a single atomic operation, so this is a flat array with exactly one error.","items":{"type":"object","properties":{"error_key":{"type":"string","description":"The key identifying the error source."},"category":{"type":"string","enum":["not_cancellable","internal_error"],"description":"Machine-readable reason the cancellation failed.\n- `not_cancellable`: the payroll is past the point where it can be cancelled\n- `internal_error`: an unexpected error occurred; the request can be retried\n"},"message":{"type":"string","description":"Human-readable explanation of the failure."}}}}}}},"exclusions":{"type":"array","description":"Payrolls that could not be processed, determined at submission time. Only present once the batch reaches a terminal status. Every UUID submitted in the POST batch appears in exactly one of `results` or `exclusions`.","items":{"type":"object","properties":{"idx":{"type":"integer","description":"The index of this payroll in the original POST batch array."},"entity_type":{"type":"string","enum":["payroll"],"description":"The type of entity this exclusion represents."},"uuid":{"type":"string","format":"uuid","description":"The UUID of the excluded payroll."},"company_uuid":{"type":"string","format":"uuid","description":"The UUID of the company asserted to own the payroll."},"status":{"type":"string","enum":["failed"],"description":"Always `failed` for an excluded payroll."},"category":{"type":"string","enum":["not_found","duplicate_operation"],"description":"Machine-readable category for why the payroll was excluded.\n- `not_found`: the payroll does not exist, or is not associated with a company the partner is mapped to\n- `duplicate_operation`: the same payroll UUID appeared more than once in the request; only the first occurrence is processed\n"},"message":{"type":"string","description":"Human-readable explanation for the exclusion."}}}}},"required":["uuid","idempotency_key","status","submitted_at"]},"Payroll-Batch-Conflict-Error":{"type":"object","description":"Error response when a payroll cancellation idempotency key has already been used by the same partner.","x-examples":{"conflict":{"errors":[{"error_key":"idempotency_key","category":"invalid_attribute_value","message":"Idempotency key has already been used","metadata":{"request_uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}]}},"properties":{"errors":{"type":"array","items":{"type":"object","properties":{"error_key":{"type":"string","description":"The key identifying the error source."},"category":{"type":"string","description":"The error category."},"message":{"type":"string","description":"Human-readable error message."},"metadata":{"type":"object","properties":{"request_uuid":{"type":"string","format":"uuid","description":"The UUID of the existing payroll cancellation batch that already used this idempotency key."}}}}}}}},"Payroll-Digest":{"type":"object","description":"A payroll digest batch request.","x-examples":{"success_status":{"uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","idempotency_key":"80a74f8b-2c16-45e5-9038-aa108849c6e6","batch_action":"create","status":"pending"}},"properties":{"uuid":{"type":"string","format":"uuid","description":"The unique identifier of the payroll digest batch.","readOnly":true},"idempotency_key":{"type":"string","format":"uuid","description":"The idempotency key provided when creating the batch."},"batch_action":{"type":"string","enum":["create"],"description":"The action being performed on the batch."},"status":{"type":"string","enum":["pending","processing","completed","failed"],"description":"The lifecycle status of the batch request itself. Terminal values are `completed` (processing finished — inspect `results` and `exclusions` for per-company outcomes) and `failed` (request failed; can be retried). This is distinct from the per-company `status` returned inside `results[]` and `exclusions[]`."}},"required":["uuid","idempotency_key","batch_action","status"]},"Payroll-Digest-Results":{"type":"object","description":"A payroll digest batch with processing results.","x-examples":{"success_status":{"uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","idempotency_key":"80a74f8b-2c16-45e5-9038-aa108849c6e6","status":"completed","submitted_at":"2026-04-01T14:30:00Z","completed_at":"2026-04-01T14:30:12Z","submitted_items":4,"processed_items":2,"excluded_items":2,"results":[{"idx":0,"entity_type":"company","uuid":"c1111111-1111-1111-1111-111111111111","name":"Acme Corporation","status":"success","blockers":[{"type":"missing_bank_account","description":"Company bank account not set up"}],"payrolls":[{"payroll_uuid":null,"payroll_type":"regular","display_title":"Run biweekly payroll","auto_payroll":false,"status":"ready_to_start","pay_period":{"start_date":"2026-03-16","end_date":"2026-03-29","check_date":"2026-04-03","run_payroll_by":"2026-03-31"},"pay_schedule":{"uuid":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee","frequency":"Every other week","custom_name":"Custom - every 1st and 15th"},"totals":null},{"payroll_uuid":"11111111-2222-3333-4444-555555555555","payroll_type":"regular","display_title":"Run biweekly payroll","auto_payroll":true,"status":"submitted","pay_period":{"start_date":"2026-03-02","end_date":"2026-03-15","check_date":"2026-03-20","run_payroll_by":"2026-03-17"},"pay_schedule":{"uuid":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee","frequency":"Every other week","custom_name":"Custom - every 1st and 15th"},"totals":{"total_debit_amount":"15234.56","net_pay":"11456.78","total_employer_cost":"16890.12"}}]},{"idx":3,"entity_type":"company","uuid":"c2222222-2222-2222-2222-222222222222","name":"Widget Inc","status":"success","payrolls":[]}],"exclusions":[{"idx":1,"entity_type":"company","uuid":"c3333333-3333-3333-3333-333333333333","status":"failed","category":"not_found","message":"Company not found."},{"idx":2,"entity_type":"company","uuid":"c4444444-4444-4444-4444-444444444444","status":"failed","category":"company_inactive","message":"Company is inactive or not fully onboarded."}]}},"properties":{"uuid":{"type":"string","format":"uuid","description":"The unique identifier of the payroll digest batch.","readOnly":true},"idempotency_key":{"type":"string","format":"uuid","description":"The idempotency key provided when creating the batch."},"status":{"type":"string","enum":["pending","processing","completed","failed"],"description":"The lifecycle status of the batch request itself. Terminal values are `completed` (processing finished — inspect `results` and `exclusions` for per-company outcomes) and `failed` (request failed; can be retried). This is distinct from the per-company `status` returned inside `results[]` and `exclusions[]`."},"submitted_at":{"type":"string","format":"date-time","description":"The timestamp when the batch was submitted."},"completed_at":{"type":["string","null"],"format":"date-time","description":"The timestamp when the batch processing completed."},"submitted_items":{"type":["integer","null"],"description":"The number of companies submitted in the batch."},"processed_items":{"type":"integer","description":"The number of companies successfully processed. Only present once the batch reaches a terminal status."},"excluded_items":{"type":"integer","description":"The number of companies excluded from processing. Only present once the batch reaches a terminal status."},"results":{"type":"array","description":"Per-company results. Only present once the batch reaches a terminal status. Includes successfully processed companies (with their `payrolls` array, which may be empty when the company has no payrolls in the date window).","items":{"type":"object","properties":{"idx":{"type":"integer","description":"The index of this company in the original POST batch array."},"entity_type":{"type":"string","enum":["company"],"description":"The type of entity this result represents."},"uuid":{"type":"string","format":"uuid","description":"The UUID of the company."},"name":{"type":"string","description":"The legal/display name of the company."},"status":{"type":"string","enum":["success","partial_success","failed"],"description":"The status of this company's digest computation."},"blockers":{"type":"array","description":"Reasons the company cannot currently run payroll. Applies to every payroll in this company's `payrolls` array — blockers are evaluated at the company level, not per payroll. Empty when there are no blockers.","items":{"type":"object","properties":{"type":{"type":"string","description":"A machine-readable blocker key (e.g. `missing_bank_account`)."},"description":{"type":"string","description":"Human-readable description of the blocker."}}}},"payrolls":{"type":"array","description":"Payrolls for this company within the digest date window (7 days past, 30–60 days future). May be empty.","items":{"type":"object","properties":{"payroll_uuid":{"type":["string","null"],"format":"uuid","description":"UUID of the payroll. `null` for upcoming pay periods that have not been started yet (the `payrolls` API has not yet created a payroll record). Once a payroll is created, subsequent digest requests will include the real `payroll_uuid`."},"payroll_type":{"type":"string","description":"The type of payroll (e.g. `regular`, `new_hire`, `termination`, `transition`, `bonus`, `correction`)."},"display_title":{"type":"string","description":"Partner-facing display title for this payroll (e.g. \"Run biweekly payroll\")."},"auto_payroll":{"type":"boolean","description":"Whether the company has auto-payroll enabled for this pay schedule."},"status":{"type":"string","description":"The lifecycle status of the payroll (e.g. `ready_to_start`, `in_progress`, `submitted`, `completed`, `failed`)."},"pay_period":{"type":"object","properties":{"start_date":{"type":["string","null"],"format":"date","description":"First day of the pay period."},"end_date":{"type":["string","null"],"format":"date","description":"Last day of the pay period."},"check_date":{"type":["string","null"],"format":"date","description":"The date employees get paid."},"run_payroll_by":{"type":["string","null"],"format":"date","description":"The deadline to run payroll for this pay period."}}},"pay_schedule":{"type":["object","null"],"properties":{"uuid":{"type":"string","format":"uuid","description":"UUID of the pay schedule."},"frequency":{"type":"string","description":"Human-friendly pay frequency (e.g. \"Every other week\")."},"custom_name":{"type":["string","null"],"description":"Custom name for the pay schedule, when set."}}},"totals":{"type":["object","null"],"description":"Pay totals. `null` when the payroll has not been calculated, or when the calculation is stale (the partner edited hours/earnings after the last calculation).","properties":{"total_debit_amount":{"type":"string","description":"Total amount debited from the company bank account (string-formatted decimal)."},"net_pay":{"type":"string","description":"Total net pay across all employees on this payroll (string-formatted decimal)."},"total_employer_cost":{"type":"string","description":"Total employer cost including taxes and benefits (string-formatted decimal)."}}}}}}}}},"exclusions":{"type":"array","description":"Companies that could not be processed. Only present once the batch reaches a terminal status. Every UUID submitted in the POST batch appears in exactly one of `results` or `exclusions`.","items":{"type":"object","properties":{"idx":{"type":"integer","description":"The index of this company in the original POST batch array."},"entity_type":{"type":"string","enum":["company"],"description":"The type of entity this exclusion represents."},"uuid":{"type":"string","format":"uuid","description":"The UUID of the excluded company."},"status":{"type":"string","enum":["failed"],"description":"The status of this company's digest computation."},"category":{"type":"string","enum":["not_found","company_inactive","duplicate","internal_error"],"description":"Machine-readable category for why the company was excluded."},"message":{"type":"string","description":"Human-readable explanation for the exclusion."}}}}},"required":["uuid","idempotency_key","status","submitted_at"]},"Payroll-Digest-Conflict-Error":{"type":"object","description":"Error response when a payroll digest idempotency key has already been used by the same partner.","x-examples":{"conflict":{"errors":[{"error_key":"idempotency_key","category":"invalid_attribute_value","message":"Idempotency key has already been used","metadata":{"request_uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}]}},"properties":{"errors":{"type":"array","items":{"type":"object","properties":{"error_key":{"type":"string","description":"The key identifying the error source."},"category":{"type":"string","description":"The error category."},"message":{"type":"string","description":"Human-readable error message."},"metadata":{"type":"object","properties":{"request_uuid":{"type":"string","format":"uuid","description":"The UUID of the existing payroll digest batch that already used this idempotency key."}}}}}}}},"Reversal-Payroll-Uuids-Type":{"type":"array","description":"Array of reversal payroll UUIDs, if applicable.","uniqueItems":true,"items":{"type":"string","description":"The UUID of the reversal payroll.","nullable":false,"readOnly":true}},"Payroll-Minimal":{"description":"","type":"object","x-tags":["Payrolls"],"properties":{"payroll_deadline":{"$ref":"#/components/schemas/Payroll-Deadline-Type"},"check_date":{"$ref":"#/components/schemas/Payroll-Check-Date-Type"},"processed":{"$ref":"#/components/schemas/Payroll-Processed-Type"},"processed_date":{"$ref":"#/components/schemas/Payroll-Processed-Date-Type"},"calculated_at":{"$ref":"#/components/schemas/Payroll-Calculated-At-Type"},"uuid":{"$ref":"#/components/schemas/Payroll-Payroll-Uuid-Type"},"payroll_uuid":{"$ref":"#/components/schemas/Payroll-Payroll-Uuid-Type"},"company_uuid":{"$ref":"#/components/schemas/Payroll-Company-Uuid-Type"},"off_cycle":{"$ref":"#/components/schemas/Payroll-Off-Cycle-Type"},"off_cycle_reason":{"$ref":"#/components/schemas/Off-Cycle-Reason-Type"},"auto_payroll":{"$ref":"#/components/schemas/Auto-Pilot-Type"},"external":{"$ref":"#/components/schemas/Payroll-External-Type"},"final_termination_payroll":{"$ref":"#/components/schemas/Payroll-Final-Termination-Payroll-Type"},"withholding_pay_period":{"$ref":"#/components/schemas/Payroll-Withholding-Pay-Period-Type"},"skip_regular_deductions":{"$ref":"#/components/schemas/Payroll-Skip-Regular-Deductions-Type"},"fixed_withholding_rate":{"$ref":"#/components/schemas/Payroll-Fixed-Withholding-Rate-Type"},"pay_period":{"$ref":"#/components/schemas/Payroll-Pay-Period-Type"},"payroll_status_meta":{"$ref":"#/components/schemas/Payroll-Payroll-Status-Meta-Type"},"totals":{"$ref":"#/components/schemas/Payroll-Totals-Type"},"payment_speed_changed":{"$ref":"#/components/schemas/Payroll-Payment-Speed-Changed-Type"},"created_at":{"$ref":"#/components/schemas/Created-At-Type"},"submission_blockers":{"$ref":"#/components/schemas/Payroll-Submission-Blockers-Type"},"credit_blockers":{"$ref":"#/components/schemas/Payroll-Credit-Blockers-Type"},"reversal_payroll_uuids":{"$ref":"#/components/schemas/Reversal-Payroll-Uuids-Type"}},"required":["company_uuid","uuid","payroll_uuid","processed"]},"Payroll-Blocker":{"type":"object","required":["key","message"],"properties":{"key":{"type":"string","description":"A unique identifier for the payroll blocker reason. For a complete list of blockers and their meanings, see the [Payroll Blockers guide](https://docs.gusto.com/embedded-payroll/docs/payroll-blockers).","enum":["company_ownership_required","contractor_only_company","eftps_in_error","geocode_error","geocode_needed","invalid_signatory","missing_addresses","missing_bank_info","missing_bank_verification","missing_employee_setup","missing_federal_tax_setup","missing_forms","missing_industry_selection","missing_pay_schedule","missing_signatory","missing_state_tax_setup","needs_approval","needs_onboarding","pay_schedule_setup_not_complete","pending_information_request","pending_payroll_review","pending_recovery_case","soft_suspended","suspended"],"example":"needs_approval"},"message":{"type":"string","description":"A human-readable message describing the payroll blocker and what action is needed to resolve it.","example":"Company needs to be approved to run payroll."}},"x-examples":{"blockers_list":{"key":"needs_approval","message":"Company needs to be approved to run payroll."},"empty_blockers_list":[]}},"Printable-Payroll-Checks-Body":{"description":"Request body for generating printable payroll checks.","type":"object","required":["printing_format"],"properties":{"printing_format":{"type":"string","enum":["top","bottom"],"description":"The type of check stock being printed. Check the \"Types of check stock\" section in 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 we will start generating checks from. Use to override the sequence that will be used to generate check numbers."}},"x-tags":["Payrolls"]},"Payroll-Check":{"type":"object","properties":{"payroll_uuid":{"type":"string","description":"A unique identifier of the payroll."},"printing_format":{"type":"string","description":"The format the checks will be printed."},"starting_check_number":{"type":["integer","null"],"description":"The starting check number for the checks being printed."},"request_uuid":{"type":"string","description":"A unique identifier of the Generated Document request"},"status":{"type":"string","description":"Current status of the Generated Document"},"employee_check_number_mapping":{"type":"array","description":"An array of mapping employee uuids to their check numbers","items":{"type":"object","properties":{"employee_uuid":{"type":"string","description":"The UUID for an employee"},"check_number":{"type":"number","description":"The check number for the relevant employee"}}}}},"x-examples":{"example":{"payroll_uuid":"a83d0bd8-7d20-43b9-834c-6d514ef6cb20","printing_format":"top","starting_check_number":10,"request_uuid":"p83d0ca8-7d41-42a9-834y-7d218ef6cb20","status":"pending","employee_check_number_mapping":[{"employee_uuid":"f83d0bd8-7e20-43b9-834c-6d514ef6cb47","check_number":10}]}}},"Generated-Document":{"type":"object","properties":{"request_uuid":{"type":"string","description":"A unique identifier of the Generated Document request"},"status":{"type":"string","description":"Current status of the Generated Document","enum":["pending","started","succeeded","failed"]},"document_urls":{"type":"array","description":"The array of urls to access the documents.","items":{"type":"string"}}},"x-examples":{"Example":{"status":"succeeded","document_urls":["https://document.url.com"],"request_uuid":"p83d0ca8-7d41-42a9-834y-7d218ef6cb20"},"pending":{"status":"pending","document_urls":[],"request_uuid":"p83d0ca8-7d41-42a9-834y-7d218ef6cb20"}}},"Report":{"type":"object","properties":{"request_uuid":{"type":"string","description":"A unique identifier of the report request"},"status":{"type":"string","description":"Current status of the report, possible values are 'succeeded', 'pending', or 'failed'"},"report_urls":{"type":"array","description":"The array of urls to access the report","items":{"type":"string"}}},"x-examples":{"example":{"status":"succeeded","report_urls":["https://report.url.com"],"request_uuid":"p83d0ca8-7d41-42a9-834y-7d218ef6cb20"}}},"Create-Report":{"type":"object","properties":{"request_uuid":{"type":"string","description":"A unique identifier of the report request"},"company_uuid":{"type":"string","description":"Company UUID"},"custom_name":{"type":["string","null"],"description":"Title of the report"},"file_type":{"type":"string","description":"File type"}},"x-examples":{"example":{"request_uuid":"p83d0ca8-7d41-42a9-834y-7d218ef6cb20","company_uuid":"w83d0ca8-7d41-42a9-834y-7d218ef6cb20","custom_name":"Custom Report","file_type":"csv"}}},"Report-Template":{"type":"object","properties":{"columns":{"type":"array","description":"List of columns recommended","items":{"type":"string"}},"groupings":{"type":"array","description":"List of groupings recommended","items":{"type":"string"}},"company_uuid":{"type":"string","description":"Company UUID"},"report_type":{"type":"string","description":"Type of report template"}},"x-examples":{"example":{"columns":["regular_rate","regular_hours","regular_earnings"],"groupings":["payroll","employee"],"company_uuid":"p83d0ca8-7d41-42a9-834y-7d218ef6cb20","report_type":"payroll_journal"}}},"Create-Report-Body":{"description":"Request body for creating a custom report.","type":"object","required":["columns","file_type"],"properties":{"columns":{"type":"array","description":"Columns to include in the report","items":{"type":"string","enum":["additional_earnings","bank_account_account_number","bank_account_routing_number","bank_account_type","bank_account","bonus","cash_tips","check_amount","check_date","commission","date_of_birth","double_overtime_earnings","double_overtime_hours","double_overtime_rate","employee_additional_taxes","employee_benefit_contributions","employee_compensation_time_period","employee_compensation","employee_deductions","employee_department","employee_email","employee_donations","employee_federal_income_tax","employee_first_name","employee_last_name","employee_middle_initial","employee_medicare_additional_tax","employee_medicare_tax","employee_phone_number","employee_social_security_tax","employee_state_income_tax","employee_taxes","employee_uuid","employee_work_email","employer_additional_taxes","employer_benefit_contributions","employer_cost","employer_futa_tax","employer_medicare_tax","employer_social_security_tax","employer_suta_tax","employer_taxes","employment_type","employment","end_date","garnishments","gross_earnings","holiday_earnings","holiday_hours","home_address_city","home_address_state","home_address_street","home_address_zip","home_address","job_title","net_pay","one_time_reimbursements","overtime_earnings","overtime_hours","overtime_rate","paid_time_off_earnings","paid_time_off_hours","paid_time_off_rate","pay_period_end","pay_period_start","paycheck_tips","payment_method","payroll_type","payroll_uuid","preferred_first_name","recurring_reimbursements","regular_earnings","regular_hours","regular_rate","reimbursements","risk_class_code","sick_rate","sick_time_off_earnings","sick_time_off_hours","start_date","total_employer_benefit_contributions","total_time_off_earnings","total_time_off_hours","work_address_city","work_address_street","work_address_zip"]}},"groupings":{"type":"array","description":"Optional. How to group the report. If omitted, sensible defaults are derived from the `columns` requested.","items":{"type":"string","enum":["payroll","employee","work_address","work_address_state"]}},"custom_name":{"type":"string","description":"The title of the report"},"file_type":{"type":"string","description":"The type of file to generate","enum":["csv","json","pdf"]},"with_totals":{"type":"boolean","description":"Whether to include subtotals and grand totals in the report","default":false},"date_filter_type":{"type":"string","description":"Which payroll date `start_date` and `end_date` filter against.","default":"period_end_date","enum":["period_end_date","period_start_date","check_date"]},"start_date":{"type":"string","format":"date","description":"Start date of data to filter by","example":"2024-01-01"},"end_date":{"type":"string","format":"date","description":"End date of data to filter by","example":"2024-04-01"},"dismissed_start_date":{"type":"string","format":"date","description":"Dismissed start date of employees to filter by","example":"2024-01-01"},"dismissed_end_date":{"type":"string","format":"date","description":"Dismissed end date of employees to filter by","example":"2024-04-01"},"payment_method":{"type":"string","description":"Payment method to filter by","enum":["check","direct_deposit"]},"employment_type":{"type":"string","description":"Employee employment type to filter by","enum":["exempt","salaried_nonexempt","nonexempt","commission_only_exempt","commission_only_nonexempt"]},"employment_status":{"type":"string","description":"Employee employment status to filter by","enum":["active_full_time","active_part_time","active_part_time_eligible","active_variable","active_seasonal","active","dismissed"]},"employee_uuids":{"type":["array","null"],"description":"Employees to filter by","items":{"type":"string"}},"department_uuids":{"type":"array","description":"Departments to filter by","items":{"type":"string"}},"work_address_uuids":{"type":"array","description":"Work addresses to filter by","items":{"type":"string"}}},"x-tags":["Reports"]},"General-Ledger-Report-Body":{"description":"Request body for generating a general ledger report. The report can be aggregated by different dimensions such as job or department.","type":"object","required":["aggregation"],"properties":{"aggregation":{"type":"string","enum":["default","job","department","integration"],"description":"The breakdown of the report. Use 'default' for no split."},"integration_type":{"description":"The kind of integration set up for the company. Required when `aggregation` is 'integration'. Must be null if `aggregation` is not 'integration'.","anyOf":[{"type":"string","enum":["xero","qbo"]},{"type":"null"}]}},"x-tags":["Reports"]},"General-Ledger-Report":{"type":"object","description":"A request for a general ledger report. The report is generated asynchronously and the URL is available via the report GET endpoint using the returned `request_uuid`.","properties":{"payroll_uuid":{"type":"string","format":"uuid","description":"The UUID of the payroll record for which the report was generated."},"aggregation":{"type":"string","enum":["default","job","department","integration"],"description":"The breakdown level used for the report."},"integration_type":{"type":["string","null"],"description":"The `integration_type` used for the report when `aggregation` is 'integration' (e.g., `xero`, `qbo`). Otherwise, this will be null or an empty string."},"request_uuid":{"type":"string","format":"uuid","description":"UUID to use for polling the report status."}},"x-examples":{"example":{"payroll_uuid":"a83d0bd8-7d20-43b9-834c-6d514ef6cb20","aggregation":"integration","integration_type":"xero","request_uuid":"550e8400-e29b-41d4-a716-446655440000"}}},"Payroll-Reversal":{"type":"object","properties":{"reversed_payroll_uuid":{"type":"string","description":"The UUID for the payroll run being reversed."},"reversal_payroll_uuid":{"type":["string","null"],"description":"The UUID of the payroll where the reversal was applied."},"reason":{"type":"string","description":"A reason provided by the admin who created the reversal."},"approved_at":{"type":["string","null"],"description":"Timestamp of when the reversal was approved."},"category":{"type":["string","null"],"description":"Category chosen by the admin who requested the reversal."},"reversed_employee_uuids":{"type":"array","description":"Array of affected employee UUIDs.","items":{"type":"string"}}},"x-examples":{"Example":{"reversed_payroll_uuid":"09505984-8d8c-41a3-adbe-5740322ae8e9","reversal_payroll_uuid":"0424688e-0a2e-4cd0-ac86-42283e788fb3","reason":"Customer Request","approved_at":null,"category":"convert_check_ee_requested","reversed_employee_uuids":["5f036964-185e-4c85-bbf2-3873e1203b30"]}}},"Payroll-Reversal-List":{"type":"array","items":{"$ref":"#/components/schemas/Payroll-Reversal"},"x-examples":{"Example":[{"reversed_payroll_uuid":"09505984-8d8c-41a3-adbe-5740322ae8e9","reversal_payroll_uuid":"0424688e-0a2e-4cd0-ac86-42283e788fb3","reason":"Customer Request","approved_at":null,"category":"convert_check_ee_requested","reversed_employee_uuids":["5f036964-185e-4c85-bbf2-3873e1203b30"]}]}},"Gross-Up-Pay":{"type":"object","properties":{"gross_up":{"type":"string","format":"float","description":"Gross up earnings."}}},"Contractor-Payment-Receipt":{"type":"object","x-examples":{"example":{"contractor_payment_uuid":"afccb970-357e-4013-81f5-85dafc74f9b6","company_uuid":"c827aa0d-3928-4d5a-ab1f-400641a7d2b8","name_of_sender":"Torp and Sons and Sons","name_of_recipient":"Patricia Hamill","debit_date":"2022-06-02","totals":{"company_debit":"748.34"},"contractor_payments":[{"contractor_uuid":"f83d0bd8-7e20-43b9-834c-6d514ef6cb47","contractor_first_name":"Patricia","contractor_last_name":"Hamill","contractor_business_name":"","contractor_type":"Individual","payment_method":"Direct Deposit","wage":"448.34","bonus":"248.00","reimbursement":"100.00"}],"licensee":{"name":"Gusto, Zenpayroll Inc.","address":"525 20th St","city":"San Francisco","state":"CA","postal_code":"94107","phone_number":"4157778888"},"license":"Your payroll provider partners with Gusto Inc. for payments processing. Gusto Inc. is a licensed money transmitter. Learn more on our license page.","license_uri":"https://gusto.com/about/licenses","right_to_refund":"https://gusto.com/about/licenses","liability_of_licensee":"https://gusto.com/about/licenses"}},"properties":{"contractor_payment_uuid":{"type":"string","description":"A unique identifier of the contractor payment receipt."},"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."},"name_of_recipient":{"type":"string","description":"The individual or company name of the contractor receiving payment."},"debit_date":{"type":"string","description":"The debit date for the contractor payment.","format":"date","example":"2022-05-30"},"license":{"type":"string","description":"Always the fixed string \"Your payroll provider partners with Gusto Inc. for payments processing. Gusto Inc. is a licensed money transmitter. Learn more on our license page.\""},"license_uri":{"type":"string","description":"URL for the license information for the licensed payroll processor. Always the fixed string \"https://gusto.com/about/licenses\""},"right_to_refund":{"type":"string","description":"URL for information related to right to refund. Always the fixed string \"https://gusto.com/about/licenses\""},"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\""},"totals":{"type":"object","description":"The subtotals for the contractor payment.","properties":{"company_debit":{"type":"string","description":"The total company debit for the contractor payment."}}},"contractor_payments":{"type":"array","description":"An array of contractor payments for this contractor payment.","items":{"type":"object","properties":{"contractor_uuid":{"type":"string","description":"The UUID of the contractor."},"contractor_first_name":{"type":"string","description":"The first name of the contractor. Applies when `contractor_type` is `Individual`."},"contractor_last_name":{"type":"string","description":"The last name of the contractor.  Applies when `contractor_type` is `Individual`."},"contractor_business_name":{"type":"string","description":"The business name of the contractor. Applies when `contractor_type` is `Business`."},"contractor_type":{"type":"string","description":"The type of contractor.\n\n`Individual` `Business`"},"payment_method":{"type":"string","description":"The payment method.","enum":["Direct Deposit","Check","Historical Payment","Correction Payment"]},"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."}}}},"licensee":{"type":"object","description":"The licensed payroll processor","properties":{"name":{"type":"string","description":"Always the fixed string \"Gusto, Zenpayroll Inc.\""},"address":{"type":"string","description":"Always the fixed string \"525 20th St\""},"city":{"type":"string","description":"Always the fixed string \"San Francisco\""},"state":{"type":"string","description":"Always the fixed string \"CA\""},"postal_code":{"type":"string","description":"Always the fixed string \"94107\""},"phone_number":{"type":"string","description":"Always the fixed string \"4157778888\""}}}}},"Company-Custom-Field":{"type":"object","description":"A custom field on a company","x-tags":["Custom Fields"],"properties":{"uuid":{"type":"string","description":"UUID of the company custom field"},"name":{"type":"string","description":"Name of the company custom field"},"type":{"$ref":"#/components/schemas/Custom-Field-Type"},"description":{"type":["string","null"],"description":"Description of the company custom field"},"selection_options":{"type":["array","null"],"description":"An array of options for fields of type radio. Otherwise, null.","items":{"type":"string"}}},"required":["uuid","name","type"]},"Company-Custom-Field-List":{"type":"object","x-examples":{"success_status":{"custom_fields":[{"uuid":"ea7e5d57-6abb-47d7-b654-347c142886c0","name":"employee_level","description":"Employee Level","type":"text","selection_options":null},{"uuid":"024ec137-6c92-43a3-b061-14a9720531d6","name":"favorite fruit","description":"Which is your favorite fruit?","type":"radio","selection_options":["apple","banana","orange"]}]}},"properties":{"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/Company-Custom-Field"}}}},"Rehire":{"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."},"effective_date":{"type":"string","description":"The day when the employee returns to work."},"file_new_hire_report":{"type":"boolean","description":"The boolean flag indicating whether Gusto will file a new hire report for the employee."},"work_location_uuid":{"type":"string","description":"The uuid of the employee's work location."},"employment_status":{"type":"string","description":"The employee's employment status. Supplying an invalid option will set the employment_status to *not_set*.","enum":["part_time","full_time","part_time_eligible","variable","seasonal","not_set"]},"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."},"employee_uuid":{"type":"string","description":"The UUID of the employee.","readOnly":true},"active":{"type":"boolean","description":"Whether the employee's rehire has gone into effect.","readOnly":true}},"x-examples":{"example":{"version":"2e930d43acbdb241f8f14a2d531fa417","employee_uuid":"8c290660-b6c9-4ad7-9f6e-ea146aaf79e8","active":false,"effective_date":"2024-06-30","employment_status":"seasonal","file_new_hire_report":false,"work_location_uuid":"8cb87e2e-5b30-4c13-a4f4-bfffcbed1188","two_percent_shareholder":false},"active_rehire":{"version":"7c930f42bcadb241f8f14a2d531fb528","employee_uuid":"9d3b1770-c7d0-5be8-a07f-fb257bbg80f9","active":true,"effective_date":"2024-01-15","employment_status":"full_time","file_new_hire_report":true,"work_location_uuid":"9dc98f3f-6c41-5d24-a5b5-c363687ebf29","two_percent_shareholder":false},"created":{"version":"3a841e52dcbea351f9f25b3e642gb639","employee_uuid":"8c290660-b6c9-4ad7-9f6e-ea146aaf79e8","active":false,"effective_date":"2023-06-30","employment_status":"full_time","file_new_hire_report":true,"work_location_uuid":"b6ae9d93-d4b8-4119-8c96-dba595dd8c30","two_percent_shareholder":false}}},"Rehire-Update-Request-Body":{"description":"Request body for updating an employee rehire.","type":"object","allOf":[{"$ref":"#/components/schemas/Versionable-Required"},{"$ref":"#/components/schemas/Rehire-Body"}],"x-examples":{"update_rehire":{"version":"1928d0c378e519e9c03fb959bc959a6b","effective_date":"2023-06-30","work_location_uuid":"b6ae9d93-d4b8-4119-8c96-dba595dd8c30","file_new_hire_report":true}}},"Salary-Estimate":{"type":"object","description":"A salary estimate calculation for an S-Corp owner based on occupation, experience level, location, and business revenue.","properties":{"uuid":{"type":"string","description":"The UUID of the salary estimate.","readOnly":true},"employee_uuid":{"type":["string","null"],"description":"The UUID of the employee this salary estimate is for.","readOnly":true},"employee_job_uuid":{"type":["string","null"],"description":"The UUID of the employee job this salary estimate is associated with (once accepted).","readOnly":true},"annual_net_revenue":{"type":["string","null"],"description":"The annual net revenue of the business used for salary calculations."},"zip_code":{"type":["string","null"],"description":"The ZIP code used for location-based salary calculations.","pattern":"^\\d{5}$"},"result":{"type":["integer","null"],"description":"The calculated reasonable salary estimate in cents. Null if not yet calculated.","readOnly":true},"accepted_at":{"type":["string","null"],"format":"date-time","description":"The timestamp when this salary estimate was accepted and finalized.","readOnly":true},"created_at":{"type":"string","format":"date-time","description":"The timestamp when this salary estimate was created.","readOnly":true},"updated_at":{"type":"string","format":"date-time","description":"The timestamp when this salary estimate was last updated.","readOnly":true},"occupations":{"type":"array","description":"Array of occupations with their experience levels and time allocations.","items":{"type":"object","properties":{"code":{"type":"string","description":"Bureau of Labor Statistics (BLS) occupation code."},"name":{"type":"string","description":"Occupation name."},"description":{"type":"string","description":"Occupation description."},"experience_level":{"type":"string","description":"Experience level for this occupation.","enum":["novice","intermediate","average","skilled","expert"]},"time_percentage":{"type":"string","description":"Percentage of time spent in this occupation (as decimal string, 0-1)."},"primary":{"type":"boolean","description":"Whether this is the primary occupation."}},"required":["code","experience_level","time_percentage"]}}},"required":["uuid","employee_uuid","annual_net_revenue","zip_code","created_at","updated_at","occupations"],"x-examples":{"success_status":{"uuid":"7f5d3d93-6d6f-48c0-9f4e-cd12c2d3e4b2","employee_uuid":"8c290660-b6c9-4ad7-9f6e-ea146aaf79e8","employee_job_uuid":null,"annual_net_revenue":"500000","zip_code":"94107","result":12000000,"accepted_at":null,"created_at":"2025-01-15T10:30:00.000-08:00","updated_at":"2025-01-15T10:30:00.000-08:00","occupations":[{"code":"15-1252","name":"Software Developers, Systems Software","description":"Research, design, develop, and test operating systems-level software.","experience_level":"skilled","time_percentage":"1.0","primary":true}]}}},"BLS-Occupation":{"type":"object","description":"A Bureau of Labor Statistics occupation code with its title and description, used for salary estimate calculations.","properties":{"code":{"type":"string","description":"Bureau of Labor Statistics (BLS) occupation code.","example":"15-1252"},"title":{"type":"string","description":"Occupation title.","example":"Software Developers"},"description":{"type":"string","description":"Occupation description.","example":"Research, design, and develop computer and network software or specialized utility programs."}},"required":["code","title"],"x-examples":{"success_status":{"code":"15-1252","title":"Software Developers","description":"Research, design, and develop computer and network software or specialized utility programs."}}},"Signatory":{"description":"The representation of a company's signatory","type":"object","title":"Signatory","x-tags":["Signatories"],"properties":{"uuid":{"type":"string"},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"title":{"type":["string","null"]},"phone":{"type":["string","null"]},"email":{"type":"string"},"birthday":{"type":["string","null"]},"is_admin":{"type":"boolean","description":"Whether or not the signatory is also the payroll admin of the company."},"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."},"identity_verification_status":{"anyOf":[{"type":"string","enum":["Pass","Fail","Skipped"]},{"type":"null"}],"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 |"},"home_address":{"type":["object","null"],"properties":{"street_1":{"type":"string"},"street_2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"},"country":{"type":"string","default":"USA"}}}},"required":["uuid"],"x-examples":{"typical_signatory":{"uuid":"7b1d0df1-6403-4a06-8768-c1dd7d24d27a","first_name":"Bob","last_name":"Jones","title":"CEO","phone":"4156051234","email":"bob@example.com","birthday":"1980-08-04","is_admin":true,"has_ssn":true,"version":"e1bdd845a493c74908f8e15d6114169b","identity_verification_status":"Skipped","home_address":null},"signatory_with_address":{"uuid":"8c2e1ef2-7514-5b17-9879-d2ee8e35e38b","first_name":"Rachel","last_name":"Greene","title":"Onboarding specialist","phone":"4155551234","email":"rachel@example.com","birthday":null,"is_admin":false,"has_ssn":false,"version":"def456","identity_verification_status":null,"home_address":{"street_1":"525 20th Street","street_2":"Apt. 1","city":"San Francisco","state":"CA","zip":"94107","country":"USA"}}}},"Signatory-Invite-Request":{"type":"object","description":"Request body for inviting a signatory.","properties":{"first_name":{"type":"string","description":"The signatory's first name."},"middle_initial":{"type":"string"},"last_name":{"type":"string","description":"The signatory's last name."},"title":{"type":"string","description":"The signatory's title (e.g. CEO, President)."},"phone":{"type":"string","description":"The signatory's phone number."},"birthday":{"type":"string","format":"date","description":"The signatory's date of birth."},"email":{"type":"string","format":"email","description":"The signatory's email address."},"ssn":{"type":"string","description":"The signatory's SSN. Required for create with complete information; not used for invite."},"home_address":{"type":"object","description":"The signatory's home address.","properties":{"street_1":{"type":"string"},"street_2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"},"country":{"type":"string","default":"USA"}}}},"required":["first_name","last_name","email"],"x-tags":["Signatories"]},"Signatory-Create-Request":{"type":"object","description":"Request body for creating a signatory with complete information. All listed required fields must be provided.","properties":{"first_name":{"type":"string","description":"The signatory's first name."},"middle_initial":{"type":"string"},"last_name":{"type":"string","description":"The signatory's last name."},"title":{"type":"string","description":"The signatory's title (e.g. CEO, President)."},"phone":{"type":"string","description":"The signatory's phone number."},"birthday":{"type":"string","format":"date","description":"The signatory's date of birth."},"email":{"type":"string","format":"email","description":"The signatory's email address."},"ssn":{"type":"string","description":"The signatory's SSN."},"home_address":{"type":"object","description":"The signatory's home address.","properties":{"street_1":{"type":"string"},"street_2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"},"country":{"type":"string","default":"USA"}},"required":["street_1","city","state","zip"]}},"required":["first_name","last_name","email","title","phone","birthday","ssn","home_address"],"x-tags":["Signatories"]},"Signatory-Update-Request":{"type":"object","description":"Request body for updating a signatory. Email cannot be updated.","properties":{"version":{"type":"string","description":"Current version of the signatory (required for optimistic concurrency)."},"first_name":{"type":"string"},"middle_initial":{"type":"string"},"last_name":{"type":"string"},"title":{"type":"string"},"phone":{"type":"string"},"birthday":{"type":"string","format":"date"},"ssn":{"type":"string","description":"The signatory's SSN."},"home_address":{"type":"object","properties":{"street_1":{"type":"string"},"street_2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"},"country":{"type":"string"}}}},"required":["version"],"x-tags":["Signatories"]},"Flow":{"description":"The representation of a flow in Gusto white-label UI.","type":"object","x-examples":{"success_status":{"url":"https://flows.gusto-demo.com/flows/lO2BHHAMCScPVV9G5WEURW0Im_nP9mGYloQgjUWbenQ"}},"title":"Flow","x-tags":["Flows"],"properties":{"url":{"type":"string"}}},"Create-Flow-Request":{"description":"Request body for creating a flow.","type":"object","required":["flow_type"],"properties":{"flow_type":{"type":"string","description":"The type of flow to generate. Multiple flow types can be combined by separating them with commas (e.g., \"add_addresses,add_employees,sign_all_forms\").","example":"company_onboarding"},"entity_uuid":{"type":"string","description":"UUID of the target entity applicable to the flow. This field is optional for company flows."},"entity_type":{"type":"string","description":"The type of target entity applicable to the flow. This field is optional for company flows.","enum":["Company","Employee","Contractor","Payroll"]},"options":{"type":"object","description":"Optional configuration object that varies based on the flow_type. This can contain arbitrary key-value pairs specific to the flow being generated.","additionalProperties":true}},"x-examples":{"example":{"flow_type":"company_onboarding"},"with_entity":{"flow_type":"employee_form_signing","entity_uuid":"1b71bb5b-4811-46e9-8a8a-cf5521cbeda6","entity_type":"Employee"},"with_options":{"flow_type":"company_retirement_benefits","options":{"provider":"guideline"}}}},"Unprocessed-Termination-Pay-Period":{"description":"The representation of an unprocessed termination pay period.","type":"object","properties":{"start_date":{"type":"string","description":"The start date of the pay period.","readOnly":true},"end_date":{"type":"string","description":"The end date of the pay period."},"check_date":{"type":"string","description":"The check date of the pay period.","readOnly":true},"debit_date":{"type":"string","description":"The debit 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."}},"x-examples":{"typical_unprocessed_termination_pay_period":{"start_date":"2023-01-11","end_date":"2023-01-24","check_date":"2023-01-28","debit_date":"2023-01-26","employee_name":"Mary Warner","employee_uuid":"094f6ded-a790-4651-87e6-4a7f15dec7c6","pay_schedule_uuid":"00ebc4a4-ec88-4435-8f45-c505bb63e501"}},"x-tags":["Employee Employments"]},"Pay-Schedule-Assignment":{"description":"The representation of a pay schedule assignment.","type":"object","x-examples":{"example":{"type":"by_employee","employees":[{"employee_uuid":"f0238368-f2cf-43e2-9a07-b0265f2cec69","pay_schedule_uuid":"c277ac52-9871-4a96-a1e6-0c449684602a"}]}},"properties":{"type":{"anyOf":[{"type":"string","enum":["single","hourly_salaried","by_employee","by_department"]},{"type":"null"}],"description":"The pay schedule assignment type.","readOnly":true},"hourly_pay_schedule_uuid":{"type":["string","null"],"description":"Pay schedule for hourly employees.","readOnly":true},"salaried_pay_schedule_uuid":{"type":["string","null"],"description":"Pay schedule for salaried employees.","readOnly":true},"default_pay_schedule_uuid":{"type":["string","null"],"description":"Default pay schedule for employees.","readOnly":true},"employees":{"type":["array","null"],"description":"List of employees and their pay schedules.","readOnly":true,"items":{"$ref":"#/components/schemas/Pay-Schedule-Assignment-Employee"}},"departments":{"type":["array","null"],"description":"List of departments and their pay schedules.","readOnly":true,"items":{"$ref":"#/components/schemas/Pay-Schedule-Assignment-Department"}}},"x-tags":["Pay Schedules"]},"Pay-Schedule-Assignment-Employee":{"type":"object","x-examples":{"example-1":{"employee_uuid":"43b39ada-dc49-4879-9594-fe95f67ae434","pay_schedule_uuid":"3f029a58-155d-4c30-8361-cc266b2c1f11"}},"properties":{"employee_uuid":{"type":"string","description":"The UUID of the employee."},"pay_schedule_uuid":{"type":["string","null"],"description":"The employee's pay schedule UUID."}},"x-tags":["Pay Schedules"]},"Pay-Schedule-Assignment-Department":{"type":"object","x-examples":{"example-1":{"department_uuid":"43b39ada-dc49-4879-9594-fe95f67ae434","pay_schedule_uuid":"3f029a58-155d-4c30-8361-cc266b2c1f11"}},"properties":{"department_uuid":{"type":"string","description":"The UUID of the department."},"pay_schedule_uuid":{"type":"string","description":"The department's pay schedule UUID."}},"x-tags":["Pay Schedules"]},"Pay-Schedule-Assignment-Preview":{"description":"The representation of a pay schedule assignment preview.","type":"object","x-examples":{"example":{"type":"hourly_salaried","employee_changes":[{"employee_uuid":"43b39ada-dc49-4879-9594-fe95f67ae434","first_name":"Penny","last_name":"Parker","pay_frequency":"Twice per month — Salaried pay schedule","first_pay_period":{"pay_schedule_uuid":"3f029a58-155d-4c30-8361-cc266b2c1f11","start_date":"2023-07-01","end_date":"2023-08-01","check_date":"2023-08-02"},"transition_pay_period":{"start_date":"2023-06-20","end_date":"2023-06-30"}}]}},"properties":{"type":{"anyOf":[{"type":"string","enum":["single","hourly_salaried","by_employee","by_department"]},{"type":"null"}],"description":"The pay schedule assignment type.","readOnly":true},"employee_changes":{"type":"array","description":"A list of pay schedule changes including pay period and transition pay period.","items":{"$ref":"#/components/schemas/Pay-Schedule-Assignment-Employee-Change"}}},"x-tags":["Pay Schedules"]},"Pay-Schedule-Assignment-Employee-Change":{"type":"object","x-examples":{"example-1":{"employee_uuid":"43b39ada-dc49-4879-9594-fe95f67ae434","first_name":"Penny","last_name":"Parker","pay_frequency":"Twice per month — Salaried pay schedule","first_pay_period":{"pay_schedule_uuid":"3f029a58-155d-4c30-8361-cc266b2c1f11","start_date":"2023-07-01","end_date":"2023-08-01","check_date":"2023-08-02"},"transition_pay_period":{"start_date":"2023-06-20","end_date":"2023-06-30"}}},"properties":{"employee_uuid":{"type":"string","description":"The UUID of the employee.","readOnly":true},"first_name":{"type":"string","description":"The employee's first name.","readOnly":true},"last_name":{"type":"string","description":"The employee's last name.","readOnly":true},"pay_frequency":{"type":"string","description":"New pay schedule frequency and name.","readOnly":true},"first_pay_period":{"$ref":"#/components/schemas/Pay-Schedule-Assignment-Pay-Period"},"transition_pay_period":{"$ref":"#/components/schemas/Pay-Schedule-Assignment-Transition-Pay-Period"}},"x-tags":["Pay Schedules"]},"Pay-Schedule-Assignment-Pay-Period":{"description":"Pay schedule assignment first pay period information.","type":"object","x-examples":{"example-1":{"pay_schedule_uuid":"3f029a58-155d-4c30-8361-cc266b2c1f11","start_date":"2023-07-01","end_date":"2023-08-01","check_date":"2023-08-02"}},"properties":{"pay_schedule_uuid":{"type":"string","description":"The pay schedule UUID."},"start_date":{"type":"string","description":"Pay period start date."},"end_date":{"type":"string","description":"Pay period end date."},"check_date":{"type":"string","description":"Pay period check date."}},"x-tags":["Pay Schedules"]},"Pay-Schedule-Assignment-Transition-Pay-Period":{"description":"Pay schedule assignment transition pay period information.","type":"object","x-examples":{"example-1":{"start_date":"2023-07-01","end_date":"2023-08-01"}},"properties":{"start_date":{"type":"string","description":"Pay period start date."},"end_date":{"type":"string","description":"Pay period end date."}},"x-tags":["Pay Schedules"]},"Accruing-Time-Off-Hour":{"description":"The representation of an unprocessed termination pay period.","type":"object","properties":{"time_off_policy_uuid":{"type":"string","description":"A unique identifier of the time off policy."},"hours":{"type":"string","description":"Hours accrued during this pay period."}}},"Employee-Federal-Tax-Pre2020":{"title":"Employee-Federal-Tax-Pre2020","type":"object","description":"Federal tax information for employees using the pre-2020 W4 form.","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."},"employee_uuid":{"type":"string","description":"The UUID of the employee."},"employee_id":{"type":"integer","description":"The internal ID of the employee."},"company_id":{"type":"integer","description":"The internal ID of the company."},"w4_data_type":{"type":"string","description":"The version of w4 form.","enum":["pre_2020_w4"]},"filing_status":{"type":["string","null"],"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"},"federal_withholding_allowance":{"type":["number","null"],"description":"An exemption from paying a certain amount of income tax. May be null when filing_status is \"Exempt from withholding\"."},"additional_withholding":{"type":"string","description":"An additional withholding dollar amount."}},"required":["version","w4_data_type","additional_withholding"],"x-tags":["Employee Tax Setup"]},"Employee-Federal-Tax-Rev2020":{"title":"Employee-Federal-Tax-Rev2020","type":"object","description":"Federal tax information for employees using the revised 2020 W4 form.","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."},"employee_uuid":{"type":"string","description":"The UUID of the employee."},"employee_id":{"type":"integer","description":"The internal ID of the employee."},"company_id":{"type":"integer","description":"The internal ID of the company."},"w4_data_type":{"type":"string","description":"The version of w4 form.","enum":["rev_2020_w4"]},"filing_status":{"type":["string","null"],"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"},"extra_withholding":{"type":["string","null"],"description":"An employee can request an additional amount to be withheld from each paycheck."},"two_jobs":{"type":["boolean","null"],"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."},"dependents_amount":{"type":["string","null"],"description":"A dependent is a person other than the taxpayer or spouse who entitles the taxpayer to claim a dependency exemption."},"other_income":{"type":["string","null"],"description":"Other income amount."},"deductions":{"type":["string","null"],"description":"Deductions other than the standard deduction to reduce withholding."}},"required":["version","w4_data_type","filing_status","extra_withholding","two_jobs","dependents_amount","other_income","deductions"],"x-tags":["Employee Tax Setup"]},"Employee-Federal-Tax":{"title":"Employee-Federal-Tax","type":"object","description":"Federal tax information for an employee. The response structure varies based on the w4_data_type field.","oneOf":[{"$ref":"#/components/schemas/Employee-Federal-Tax-Pre2020"},{"$ref":"#/components/schemas/Employee-Federal-Tax-Rev2020"}],"discriminator":{"propertyName":"w4_data_type","mapping":{"pre_2020_w4":"#/components/schemas/Employee-Federal-Tax-Pre2020","rev_2020_w4":"#/components/schemas/Employee-Federal-Tax-Rev2020"}},"x-examples":{"rev_2020_w4":{"version":"56a489ce86ed6c1b0f0cecc4050a0b01","filing_status":"Single","two_jobs":false,"dependents_amount":"1000.0","other_income":"10.0","deductions":"11.0","extra_withholding":"9.0","w4_data_type":"rev_2020_w4","employee_uuid":"7d70e6b0-9889-4060-9eef-aafabc14e2f2","employee_id":1,"company_id":1},"rev_2020_w4_married_two_jobs":{"version":"63859768485e218ccf8a449bb60f14ed","w4_data_type":"rev_2020_w4","filing_status":"Married","two_jobs":true,"dependents_amount":"2000.0","other_income":"20.0","deductions":"11.0","extra_withholding":"9.0","employee_uuid":"8d70e6b0-9889-4060-9eef-aafabc14e2f2","employee_id":2,"company_id":1}},"x-tags":["Employee Tax Setup"]},"Employee-State-Tax":{"title":"Employee-State-Tax","type":"object","x-examples":{"example-1":{"uuid":"287d2c61-1d18-4126-8a4a-9cb29bbb6dac","employee_uuid":"2005e601-3c78-410a-9d40-b960ae130383","state":"CA","questions":[{"label":"Filing Status","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","key":"filing_status","input_question_format":{"type":"Select","options":[{"value":"S","label":"Single"},{"value":"M","label":"Married one income"},{"value":"MD","label":"Married dual income"},{"value":"H","label":"Head of household"},{"value":"E","label":"Do Not Withhold"}]},"answers":[{"value":"S","valid_from":"2010-01-01","valid_up_to":null}]},{"label":"Withholding Allowance","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","key":"withholding_allowance","input_question_format":{"type":"Number"},"answers":[{"value":1,"valid_from":"2010-01-01","valid_up_to":null}]},{"label":"Additional Withholding","description":"You can withhold an additional amount of California income taxes here.","key":"additional_withholding","input_question_format":{"type":"Currency"},"answers":[{"value":"0.0","valid_from":"2010-01-01","valid_up_to":null}]},{"label":"File a New Hire Report?","description":"State law requires you to file a new hire report within 20 days of hiring or re-hiring an employee.","key":"file_new_hire_report","input_question_format":{"type":"Select"},"options":[{"value":true,"label":"Yes, file the state new hire report for me."},{"value":false,"label":"No, I have already filed."}],"answers":[{"value":true,"valid_from":"2010-01-01","valid_up_to":null}]}]}},"x-tags":["Employee Tax Setup"],"properties":{"uuid":{"type":"string","description":"The uuid of the employee state field."},"employee_uuid":{"type":"string","description":"The employee's uuid"},"state":{"type":"string","description":"Two letter US state abbreviation"},"file_new_hire_report":{"type":["boolean","null"]},"is_work_state":{"type":"boolean"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/Employee-State-Tax-Question"}}},"required":["uuid","employee_uuid","state","questions"]},"Federal-Tax-Details":{"title":"Federal-Tax-Details","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."},"tax_payer_type":{"anyOf":[{"type":"string","enum":["C-Corporation","S-Corporation","Sole proprietor","LLC","LLP","Limited partnership","Co-ownership","Association","Trusteeship","General partnership","Joint venture","Non-Profit"]},{"type":"null"}],"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"},"filing_form":{"type":"string","enum":["941","944"],"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)"},"has_ein":{"type":"boolean","description":"Whether company's Employer Identification Number (EIN) is present"},"ein_verified":{"type":"boolean","description":"Whether the EIN has been successfully verified as a valid EIN with the IRS."},"ein_verification":{"type":"object","nullable":false,"description":"Information about the status of verifying the company's Employer Identification Number (EIN)","properties":{"status":{"type":"string","nullable":false,"enum":["pending","verified","failed"],"description":"The status of EIN verification:\n- `pending`: The EIN verification process has not completed (or the company does not yet have an EIN).\n- `verified`: The EIN has been successfully verified as a valid EIN with the IRS.\n- `failed`: The company's EIN did not pass verification. Common issues are being entered incorrectly or not matching the company's legal name."}}},"legal_name":{"type":"string","description":"The legal name of the company"},"effective_date":{"type":"string","description":"The date that these details took effect."},"deposit_schedule":{"type":"string","description":"How often the company sends money to the IRS. One of:\n  - Semiweekly\n  - Monthly"}},"x-examples":{"Success":{"version":"68934a3e9455fa72420237eb","tax_payer_type":"S-Corporation","taxable_as_scorp":true,"filing_form":"941","has_ein":true,"ein_verified":true,"ein_verification":{"status":"verified"},"legal_name":"Acme Corp","effective_date":"2024-01-01","deposit_schedule":"Semiweekly"}},"x-tags":["Federal Tax Details"]},"Federal-Tax-Details-Update":{"title":"Federal-Tax-Details-Update","type":"object","required":["version"],"properties":{"version":{"type":"string","example":"6cb95e00540706ca48d4577b3c839fbe","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","example":"Acme Corp.","description":"The legal name of the company"},"ein":{"type":"string","example":"123456789","description":"The company's Employer Identification Number (EIN). Must be 9 digits. Dashes are optional (e.g., '12-3456789' or '123456789')."},"tax_payer_type":{"type":"string","example":"LLP","enum":["C-Corporation","S-Corporation","Sole proprietor","LLC","LLP","Limited partnership","Co-ownership","Association","Trusteeship","General partnership","Joint venture","Non-Profit"],"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"},"filing_form":{"type":"string","example":"944","enum":["941","944"],"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)"},"taxable_as_scorp":{"type":"boolean","example":false,"description":"Whether the company is taxed as an S-Corporation"}},"x-tags":["Federal Tax Details"]},"Employee-Bank-Account":{"title":"Employee-Bank-Account","type":"object","x-examples":{"Example":{"uuid":"1531e824-8d9e-4bd8-9f90-0d04608125d7","employee_uuid":"9fcf1b1d-8886-4691-9283-383d3bdd4fd9","name":"BoA Checking Account","routing_number":"266905059","hidden_account_number":"XXXX1207","account_type":"Checking"}},"properties":{"uuid":{"type":"string","description":"UUID of the bank account"},"employee_uuid":{"type":"string","description":"UUID of the employee"},"account_type":{"type":"string","enum":["Checking","Savings"],"description":"Bank account type"},"name":{"type":"string","description":"Name for the bank account"},"routing_number":{"type":"string","description":"The bank account's routing number"},"hidden_account_number":{"type":"string","description":"Masked bank account number"}},"x-tags":["Employee Payment Method"],"required":["uuid"]},"Contractor-Bank-Account":{"title":"Contractor-Bank-Account","type":"object","x-examples":{"example":{"uuid":"1531e824-8d9e-4bd8-9f90-0d04608125d7","contractor_uuid":"9fcf1b1d-8886-4691-9283-383d3bdd4fd9","name":"BoA Checking Account","routing_number":"266905059","hidden_account_number":"XXXX1207","account_type":"Checking"}},"x-tags":["Contractor Payment Method"],"properties":{"uuid":{"type":"string","description":"UUID of the bank account"},"contractor_uuid":{"type":"string","description":"UUID of the contractor"},"account_type":{"type":"string","enum":["Checking","Savings"],"description":"Bank account type"},"name":{"type":"string","description":"Name for the bank account"},"routing_number":{"type":"string","description":"The bank account's routing number"},"hidden_account_number":{"type":"string","description":"Masked bank account number"}},"required":["uuid","contractor_uuid","name","routing_number","hidden_account_number","account_type"]},"Contractor-Bank-Account-List":{"title":"Contractor-Bank-Account-List","type":"array","items":{"$ref":"#/components/schemas/Contractor-Bank-Account"},"x-examples":{"example":[{"uuid":"1531e824-8d9e-4bd8-9f90-0d04608125d7","contractor_uuid":"9fcf1b1d-8886-4691-9283-383d3bdd4fd9","name":"BoA Checking Account","routing_number":"266905059","hidden_account_number":"XXXX1207","account_type":"Checking"}]}},"Contractor-Bank-Account-Create-Request-Body":{"title":"Contractor-Bank-Account-Create-Request-Body","type":"object","required":["name","routing_number","account_number","account_type"],"properties":{"name":{"type":"string","description":"Name for the bank account"},"routing_number":{"type":"string","description":"The bank account's routing number"},"account_number":{"type":"string","description":"The bank account's account number"},"account_type":{"type":"string","enum":["Checking","Savings"],"description":"Bank account type"}},"x-examples":{"example":{"name":"BoA Checking Account","routing_number":"266905059","account_number":"5809431207","account_type":"Checking"}}},"DetailedPaymentAccountSplit":{"title":"DetailedPaymentAccountSplit","type":"object","description":"Details of a single payment split for a payment method.","properties":{"bank_account_uuid":{"type":"string","description":"The UUID of the bank account.","readOnly":true},"hidden_account_number":{"type":"string","description":"The masked account number.","readOnly":true},"name":{"type":"string","description":"The name of the bank account.","readOnly":true},"priority":{"type":"integer","description":"The priority of the payment split.","readOnly":true},"split_amount":{"type":["integer","null"],"description":"If `split_by` is 'Amount', this is in cents (e.g., 500 for $5.00) and exactly one account must have a `split_amount` of `null` to capture the remainder. If `split_by` is 'Percentage', this is the percentage value (e.g., 60 for 60%).","readOnly":true},"encrypted_account_number":{"type":["string","null"],"description":"Ciphertext containing the full bank account number, which must be decrypted using a key provided by Gusto. Only visible with the appropriate `read:account_number` scope (e.g., `employee_payment_methods:read:account_number`).","readOnly":true}},"x-examples":{"AmountSplitExample":{"value":{"bank_account_uuid":"1531e824-8d9e-4bd8-9f90-0d04608125d7","hidden_account_number":"XXXX1207","encrypted_account_number":"mbNLVOm7psP16ocqXso5ZtzOXBrA-5Q-.zarrdLBmyYDDK4kCkF2reKtzx8udK8iDabtW","name":"Primary Checking","priority":1,"split_amount":50000}},"PercentageSplitExample":{"value":{"bank_account_uuid":"e88f9436-b74e-49a8-87e9-777b9bfe715e","hidden_account_number":"XXXX5678","encrypted_account_number":"mbNLVOm7psP16ocqXso5ZtzOXBrA-5Q-.zarrdLBmyYDDK4kCkF2reKtzx8udK8iDabtW","name":"Savings Account","priority":1,"split_amount":100}}}},"EmployeePaymentDetail":{"title":"EmployeePaymentDetail","type":"object","description":"Represents an employee's payment method details.","properties":{"employee_uuid":{"type":"string","description":"The UUID of the employee.","readOnly":true},"payment_method":{"type":"string","description":"The type of payment method.","enum":["Direct Deposit","Check"],"readOnly":true},"split_by":{"anyOf":[{"type":"string","enum":["Percentage","Amount"]},{"type":"null"}],"description":"How the payment is split. This field is applicable when `payment_method` is \"Direct Deposit\".","readOnly":true},"splits":{"type":["array","null"],"description":"An array of payment splits. This field is applicable when `payment_method` is \"Direct Deposit\".","items":{"$ref":"#/components/schemas/DetailedPaymentAccountSplit"},"readOnly":true}},"x-examples":{"DirectDepositExample":{"value":{"employee_uuid":"e2c4c0ce-2986-48b9-86cf-ec27f6ed9a36","payment_method":"Direct Deposit","split_by":"Percentage","splits":[{"bank_account_uuid":"1531e824-8d9e-4bd8-9f90-0d04608125d7","hidden_account_number":"XXXX1207","encrypted_account_number":"mbNLVOm7psP16ocqXso5ZtzOXBrA-5Q-.zarrdLBmyYDDK4kCkF2reKtzx8udK8iDabtW","name":"Primary Checking","priority":1,"split_amount":100}]}}}},"Employee-Payment-Method":{"title":"Employee-Payment-Method","type":"object","x-examples":{"direct_deposit_percentage":{"version":"63859768485e218ccf8a449bb60f14ed","type":"Direct Deposit","split_by":"Percentage","splits":[{"uuid":"4b35bebe-3445-4014-a748-1e264647d601","name":"Cayman Island Checking","hidden_account_number":"XXXX1234","priority":1,"split_amount":100}]},"Example-1":{"value":{"version":"63859768485e218ccf8a449bb60f14ed","type":"Direct Deposit","split_by":"Amount","splits":[{"uuid":"e88f9436-b74e-49a8-87e9-777b9bfe715e","name":"BoA Checking Account","priority":1,"split_amount":50000},{"uuid":"0d2b7f73-05d6-4184-911d-269edeecc30a","name":"Chase Checking Account","priority":2,"split_amount":100000},{"uuid":"1531e824-8d9e-4bd8-9f90-0d04608125d7","name":"US Bank Checking Account","priority":3,"split_amount":null}]}},"Example-2":{"value":{"version":"63859768485e218ccf8a449bb60f14ed","type":"Direct Deposit","split_by":"Percentage","splits":[{"uuid":"e88f9436-b74e-49a8-87e9-777b9bfe715e","name":"BoA Checking Account","priority":1,"split_amount":60},{"uuid":"0d2b7f73-05d6-4184-911d-269edeecc30a","name":"Chase Checking Account","priority":2,"split_amount":40}]}},"Example-3":{"value":{"version":"63859768485e218ccf8a449bb60f14ed","type":"Check"}}},"description":"","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."},"type":{"type":"string","enum":["Direct Deposit","Check"],"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."},"split_by":{"anyOf":[{"type":"string","enum":["Amount","Percentage"]},{"type":"null"}],"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 `null` to capture the remainder."},"splits":{"type":["array","null"],"items":{"$ref":"#/components/schemas/Payment-Method-Bank-Account"}}},"x-tags":["Employee Payment Method"]},"Tax-Requirement":{"type":"object","x-examples":{"ga-withholding-requirement-example":{"key":"71653ec0-00b5-4c66-a58b-22ecf21704c5","applicable_if":[],"label":"Withholding Number","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.","value":"1233214-AB","editable":true,"metadata":{"type":"account_number","mask":"#######-^^","prefix":null}}},"properties":{"key":{"$ref":"#/components/schemas/Tax-Requirement-Key"},"applicable_if":{"type":"array","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.","items":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/Tax-Requirement-Key"},"value":{"description":"The required value of the requirement identified by `key`","oneOf":[{"type":"boolean"},{"type":"string"},{"type":"number"},{"type":"null"}]}}}},"label":{"type":"string","description":"A customer facing description of the requirement"},"description":{"type":["string","null"],"description":"A more detailed customer facing description of the requirement"},"value":{"$ref":"#/components/schemas/Tax-Requirements-Value"},"metadata":{"$ref":"#/components/schemas/Tax-Requirement-Metadata"},"editable":{"type":"boolean","description":"Whether the value of this requirement can be updated"},"payroll_blocking":{"type":"boolean","description":"Whether this requirement, when blank, would block payroll processing for the company in this state.\nStable across changes to the field's value: a `payroll_blocking: true` field reports `true` whether\ncurrently empty or populated.\n"},"default_value_applied":{"type":"boolean","description":"Whether the current `value` is a default rather than an explicitly set one.\n"}}},"Tax-Requirement-Metadata":{"type":"object","x-examples":{"select-example":{"type":"select","options":[{"label":"Semiweekly","value":"Semi-weekly"},{"label":"Monthly","value":"Monthly"},{"label":"Quarterly","value":"Quarterly"}]},"tax_rate-example":{"metadata":{"type":"tax_rate","validation":{"type":"min_max","min":"0.0004","max":"0.081"}}},"radio-example":{"metadata":{"type":"radio","options":[{"label":"No, we cannot reimburse the state—we have to pay SUI taxes quarterly","short_label":"Not Reimbursable","value":false},{"label":"Yes, we can reimburse the state if an employee collects SUI benefits—we don’t have to pay SUI taxes quarterly","short_label":"Reimbursable","value":true}]}},"account_number-example":{"metadata":{"type":"account_number","mask":"######-##","prefix":null}}},"properties":{"type":{"type":"string","enum":["text","currency","radio","select","percent","account_number","tax_rate","workers_compensation_rate"],"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","readOnly":true},"options":{"type":"array","description":"[for `select` or `radio`] An array of objects describing the possible values.","items":{"type":"object","properties":{"label":{"type":"string","description":"A customer facing label for the answer"},"value":{"oneOf":[{"type":"string"},{"type":"boolean"}],"description":"The actual value to be submitted"},"short_label":{"type":["string","null"],"description":"A less verbose label that may sometimes be available"}},"required":["label","value"]}},"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"},"rate_type":{"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","enum":["percent","currency_per_hour"]},"mask":{"type":["string","null"],"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"},"prefix":{"type":["string","null"],"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`."},"validation":{"type":"object","description":"[for `tax_rate`] Describes the validation required for the tax rate","properties":{"type":{"type":"string","description":"Describes the type of tax_rate validation rule","enum":["one_of","min_max"]},"min":{"type":"string","description":"[for `min_max`] The inclusive lower bound of the tax rate"},"max":{"type":"string","description":"[for `min_max`] The inclusive upper bound of the tax rate"},"rates":{"type":"array","description":"[for `one_of`] The possible, unformatted tax rates for selection.\n- e.g. [\"0.0\", \"0.001\"] representing 0% and 0.1%\n","items":{"type":"string"}}},"required":["type"]}},"required":["type"],"description":""},"Tax-Requirement-Set":{"type":"object","x-examples":{"tax-requirements-set-ga-registrations-example":{"state":"GA","key":"registrations","label":"Registrations","effective_from":null,"requirements":[{"key":"71653ec0-00b5-4c66-a58b-22ecf21704c5","applicable_if":[],"label":"Withholding Number","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.","value":"1233214-AB","metadata":{"type":"account_number","mask":"#######-^^","prefix":null}},{"key":"6c0911ab-5860-412e-bdef-6437cd881df5","applicable_if":[],"label":"DOL Account Number","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.","value":"474747-88","metadata":{"type":"account_number","mask":"######-##","prefix":null}}]}},"description":"","properties":{"state":{"$ref":"#/components/schemas/State"},"key":{"$ref":"#/components/schemas/Tax-Requirement-Set-Key"},"label":{"type":"string","description":"Customer facing label for the requirement set, e.g. \"Registrations\""},"effective_from":{"$ref":"#/components/schemas/Tax-Requirement-Effective-From"},"requirements":{"type":"array","items":{"$ref":"#/components/schemas/Tax-Requirement"}}}},"Tax-Requirements-State":{"title":"Tax-Requirements-State","type":"object","x-examples":{"tax-requirements-state-ga-example":{"company_uuid":"6c14eac3-0da2-474d-bda1-786b3602d381","state":"GA","requirement_sets":[{"state":"GA","key":"registrations","label":"Registrations","effective_from":null,"requirements":[{"key":"71653ec0-00b5-4c66-a58b-22ecf21704c5","applicable_if":[],"label":"Withholding Number","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.","value":"1233214-AB","editable":true,"payroll_blocking":false,"default_value_applied":false,"metadata":{"type":"account_number","mask":"#######-^^","prefix":null}},{"key":"6c0911ab-5860-412e-bdef-6437cd881df5","applicable_if":[],"label":"DOL Account Number","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.","value":"474747-88","editable":true,"payroll_blocking":false,"default_value_applied":false,"metadata":{"type":"account_number","mask":"######-##","prefix":null}}]},{"state":"GA","key":"taxrates","label":"Tax Rates","effective_from":"2022-01-01","requirements":[{"key":"suireimbursable","applicable_if":[],"label":"SUI Reimburser","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.","value":false,"editable":true,"payroll_blocking":false,"default_value_applied":false,"metadata":{"type":"radio","options":[{"label":"No, we cannot reimburse the state—we have to pay SUI taxes quarterly","short_label":"Not Reimbursable","value":false},{"label":"Yes, we can reimburse the state if an employee collects SUI benefits—we don’t have to pay SUI taxes quarterly","short_label":"Reimbursable","value":true}]}},{"key":"e0ac2284-8d30-4100-ae23-f85f9574868b","applicable_if":[{"key":"suireimbursable","value":false}],"label":"Total Tax Rate","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.","value":"0.05","editable":true,"payroll_blocking":true,"default_value_applied":false,"metadata":{"type":"tax_rate","validation":{"type":"min_max","min":"0.0004","max":"0.081"}}}]},{"state":"GA","key":"depositschedules","label":"Deposit Schedules","effective_from":"2022-01-01","requirements":[{"key":"6ddfcbeb-94d3-4003-bfc2-8c6e1ca9f70c","applicable_if":[],"label":"Deposit Schedule","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>.","value":"Monthly","editable":true,"payroll_blocking":false,"default_value_applied":false,"metadata":{"type":"select","options":[{"label":"Semiweekly","value":"Semi-weekly"},{"label":"Monthly","value":"Monthly"},{"label":"Quarterly","value":"Quarterly"}]}}]},{"state":"GA","key":"depositschedules","label":"Deposit Schedules","effective_from":"2022-07-01","requirements":[{"key":"6ddfcbeb-94d3-4003-bfc2-8c6e1ca9f70c","applicable_if":[],"label":"Deposit Schedule","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>.","value":"Monthly","editable":true,"payroll_blocking":false,"default_value_applied":false,"metadata":{"type":"select","options":[{"label":"Semiweekly","value":"Semi-weekly"},{"label":"Monthly","value":"Monthly"},{"label":"Quarterly","value":"Quarterly"}]}}]}]},"tax-requirements-metadata-select":{"company_uuid":"6c14eac3-0da2-474d-bda1-786b3602d381","state":"GA","requirement_sets":[{"state":"GA","key":"depositschedules","label":"Deposit Schedules","effective_from":"2022-01-01","requirements":[{"key":"6ddfcbeb-94d3-4003-bfc2-8c6e1ca9f70c","applicable_if":[],"label":"Deposit Schedule","description":"The deposit schedule assigned by the state agency.","value":"Monthly","editable":true,"payroll_blocking":false,"default_value_applied":false,"metadata":{"type":"select","options":[{"label":"Semiweekly","value":"Semi-weekly"},{"label":"Monthly","value":"Monthly"},{"label":"Quarterly","value":"Quarterly"}]}}]}]},"tax-requirements-metadata-radio":{"company_uuid":"6c14eac3-0da2-474d-bda1-786b3602d381","state":"GA","requirement_sets":[{"state":"GA","key":"taxrates","label":"Tax Rates","effective_from":"2022-01-01","requirements":[{"key":"suireimbursable","applicable_if":[],"label":"SUI Reimburser","description":"Instead of paying state unemployment insurance (SUI) taxes quarterly, some businesses may be allowed to reimburse the state if one of their employees collects unemployment benefits.","value":false,"editable":true,"payroll_blocking":false,"default_value_applied":false,"metadata":{"type":"radio","options":[{"label":"No, we cannot reimburse the state—we have to pay SUI taxes quarterly","short_label":"Not Reimbursable","value":false},{"label":"Yes, we can reimburse the state if an employee collects SUI benefits—we don't have to pay SUI taxes quarterly","short_label":"Reimbursable","value":true}]}}]}]},"tax-requirements-metadata-account-number":{"company_uuid":"6c14eac3-0da2-474d-bda1-786b3602d381","state":"GA","requirement_sets":[{"state":"GA","key":"registrations","label":"Registrations","effective_from":null,"requirements":[{"key":"71653ec0-00b5-4c66-a58b-22ecf21704c5","applicable_if":[],"label":"Withholding Number","description":"Your state withholding account number.","value":"1233214-AB","editable":true,"payroll_blocking":false,"default_value_applied":false,"metadata":{"type":"account_number","mask":"#######-^^","prefix":null}}]}]},"tax-requirements-metadata-tax-rate":{"company_uuid":"6c14eac3-0da2-474d-bda1-786b3602d381","state":"GA","requirement_sets":[{"state":"GA","key":"taxrates","label":"Tax Rates","effective_from":"2022-01-01","requirements":[{"key":"e0ac2284-8d30-4100-ae23-f85f9574868b","applicable_if":[{"key":"suireimbursable","value":false}],"label":"Total Tax Rate","description":"The assigned SUI tax rate for this state.","value":"0.05","editable":true,"payroll_blocking":true,"default_value_applied":false,"metadata":{"type":"tax_rate","validation":{"type":"min_max","min":"0.0004","max":"0.081"}}}]}]}},"description":"","properties":{"company_uuid":{"type":"string"},"state":{"$ref":"#/components/schemas/State"},"requirement_sets":{"type":"array","items":{"$ref":"#/components/schemas/Tax-Requirement-Set"}}}},"Tax-Requirement-States-List":{"type":"array","x-examples":{"success_status":[{"state":"GA","setup_status":"not_started","default_rates_applied":false,"ready_to_run_payroll":false},{"state":"CA","setup_status":"complete","default_rates_applied":false,"ready_to_run_payroll":true}]},"items":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/State"},"setup_status":{"type":"string","enum":["not_started","in_progress","complete"],"description":"The current status of the state tax setup.\n- `not_started`: No requirements have been filled\n- `in_progress`: Some requirements have been filled, or default rates are applied\n- `complete`: All requirements have been filled without default rates\n"},"default_rates_applied":{"type":"boolean","description":"Whether the state is using system-assigned default SUI rates rather than employer-specific rates."},"ready_to_run_payroll":{"type":"boolean","description":"Whether the state tax setup is sufficiently complete for the company to run payroll."}}}},"Tax-Requirement-Set-Update":{"type":"array","description":"Array of requirement sets to update. Each set corresponds to a category of requirements for the state.","items":{"type":"object","required":["key","state"],"properties":{"key":{"$ref":"#/components/schemas/Tax-Requirement-Set-Key"},"state":{"$ref":"#/components/schemas/State"},"effective_from":{"$ref":"#/components/schemas/Tax-Requirement-Effective-From"},"requirements":{"type":"array","items":{"type":"object","required":["key"],"properties":{"key":{"$ref":"#/components/schemas/Tax-Requirement-Key"},"value":{"$ref":"#/components/schemas/Tax-Requirements-Value"}}}}}}},"Tax-Requirements-Value":{"description":"The value or \"answer\" for a tax requirement. Type depends on the requirement metadata type (e.g. string for text/account_number, boolean for radio/checkbox, number for percent/currency/tax_rate). Null when the requirement has not been answered.","example":"1233214-AB","oneOf":[{"type":"boolean"},{"type":"string"},{"type":"number"},{"type":"null"}]},"Tax-Requirement-Set-Key":{"title":"Tax-Requirement-Set-Key","type":"string","example":"registrations","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-Requirement-Key":{"title":"Tax-Requirement-Key","type":"string","example":"71653ec0-00b5-4c66-a58b-22ecf21704c5","description":"An identifier for an individual requirement. Uniqueness is guaranteed within a requirement set."},"Tax-Requirement-Effective-From":{"title":"Tax-Requirement-Effective-From","type":["string","null"],"example":"2022-01-01","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."},"State":{"title":"State","type":"string","example":"GA","description":"One of the two-letter state abbreviations for the fifty United States and the District of Columbia (DC)"},"Time-Off-Policy":{"type":"object","x-examples":{"success_status":{"uuid":"3f746cd0-dd08-408f-b712-8180c7c621e9","company_uuid":"de83cff2-8e7a-448e-a28c-14258a9971c3","name":"test policy","policy_type":"vacation","accrual_method":"per_hour_worked","accrual_rate":"40.0","accrual_rate_unit":"40.0","paid_out_on_termination":true,"accrual_waiting_period_days":10,"carryover_limit_hours":"100.0","max_accrual_hours_per_year":"100.0","max_hours":"100.0","complete":true,"version":"f5556bce3d75ec2b62bd11990aa7993a","is_active":true,"policy_reset_date":"01-01","employees":[{"uuid":"c61d1895-5cf8-4217-88c8-20d7c3132a04","balance":"40.0"},{"uuid":"3633ce57-abb7-422f-8c5a-455566618e6a","balance":"20.0"}]},"success_status_no_employees":{"uuid":"3f746cd0-dd08-408f-b712-8180c7c621e9","company_uuid":"de83cff2-8e7a-448e-a28c-14258a9971c3","name":"test policy","policy_type":"vacation","accrual_method":"per_hour_worked","accrual_rate":"40.0","accrual_rate_unit":"40.0","paid_out_on_termination":true,"accrual_waiting_period_days":10,"carryover_limit_hours":"100.0","max_accrual_hours_per_year":"100.0","max_hours":"100.0","complete":true,"version":"f5556bce3d75ec2b62bd11990aa7993a","is_active":true,"policy_reset_date":"01-01","employees":[]},"deactivated_status":{"uuid":"3f746cd0-dd08-408f-b712-8180c7c621e9","company_uuid":"de83cff2-8e7a-448e-a28c-14258a9971c3","name":"test policy","policy_type":"vacation","accrual_method":"per_hour_worked","accrual_rate":"40.0","accrual_rate_unit":"40.0","paid_out_on_termination":true,"accrual_waiting_period_days":10,"carryover_limit_hours":"100.0","max_accrual_hours_per_year":"100.0","max_hours":"100.0","complete":true,"version":null,"is_active":false,"policy_reset_date":"01-01","employees":[]}},"description":"Representation of a Time Off Policy","properties":{"uuid":{"type":"string","description":"Unique identifier of a time off policy"},"company_uuid":{"type":"string","description":"Unique identifier for the company owning the time off policy"},"name":{"type":"string","description":"Name of the time off policy"},"policy_type":{"type":"string","description":"Type of the time off policy. Only \"vacation\" and \"sick\" can be created through the API, but other types may be present if the company was previously a Gusto.com customer.","enum":["vacation","sick","bereavement","custom","floating_holiday","jury_duty","learning_and_development","parental_leave","personal_day","volunteer","weather"]},"accrual_method":{"type":"string","description":"Policy time off accrual method"},"accrual_rate":{"type":["string","null"],"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_rate_unit":{"type":["string","null"],"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\"."},"paid_out_on_termination":{"type":"boolean","description":"Boolean representing if an employee's accrued time off hours will be paid out on termination"},"accrual_waiting_period_days":{"type":["integer","null"],"description":"Number of days before an employee on the policy will begin accruing time off hours"},"carryover_limit_hours":{"type":["string","null"],"format":"float","description":"The max number of hours an employee can carryover from one year to the next"},"max_accrual_hours_per_year":{"type":["string","null"],"format":"float","description":"The max number of hours an employee can accrue in a year"},"max_hours":{"type":["string","null"],"format":"float","description":"The max number of hours an employee can accrue"},"policy_reset_date":{"type":["string","null"],"description":"The date the policy resets. Format MM-DD"},"complete":{"type":"boolean","description":"boolean representing if a policy has completed configuration"},"version":{"type":["string","null"],"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. The version will be null if the policy is no longer active."},"is_active":{"type":"boolean","description":"boolean representing if a policy is active or not"},"employees":{"type":"array","description":"List of employee UUIDs under a time off policy","items":{"type":"object","properties":{"uuid":{"type":"string"},"balance":{"type":"string","description":"The time off balance for the employee"}}}}},"required":["uuid","company_uuid","name","policy_type","accrual_method","is_active","employees"]},"Time-Off-Policy-Request-Base":{"type":"object","description":"Base Request Objectfor creating or updating a time off policy","properties":{"name":{"type":"string","description":"Name of the time off policy","example":"Vacation Policy"},"policy_type":{"type":"string","description":"Type of the time off policy. Currently only \"vacation\" and \"sick\" are supported","enum":["vacation","sick"]},"accrual_method":{"type":"string","description":"Accrual method of the time off policy","enum":["unlimited","per_pay_period","per_calendar_year","per_anniversary_year","per_hour_worked","per_hour_worked_no_overtime","per_hour_paid","per_hour_paid_no_overtime"]},"accrual_rate":{"type":["string","null"],"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_rate_unit":{"type":["string","null"],"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\"."},"paid_out_on_termination":{"type":"boolean","description":"Boolean representing if an employee's accrued time off hours will be paid out on termination. If accrual_method is unlimited, then paid_out_on_termination must be `false`."},"accrual_waiting_period_days":{"type":["integer","null"],"description":"Number of days before an employee on the policy will begin accruing time off hours. If accrual_method is per_anniversary_year, per_calendar_year, or unlimited, then accrual_waiting_period_days should be 0."},"carryover_limit_hours":{"type":["string","null"],"description":"The max number of hours an employee can carryover from one year to the next. If accrual_method is unlimited, then carryover_limit_hours must be blank."},"max_accrual_hours_per_year":{"type":["string","null"],"description":"The max number of hours an employee can accrue in a year. If accrual_method is yearly (per_anniversary_year, per_calendar_year) or unlimited, then max_accrual_hours_per_year must be blank."},"max_hours":{"type":["string","null"],"description":"The max number of hours an employee can accrue. If accrual_method is unlimited, then max_hours must be blank."},"policy_reset_date":{"type":["string","null"],"description":"The date the policy resets. Format MM-DD"},"complete":{"type":"boolean","description":"boolean representing if a policy has completed configuration"}}},"Time-Off-Policy-Request":{"type":"object","description":"Request body for creating a time off policy","allOf":[{"$ref":"#/components/schemas/Time-Off-Policy-Request-Base"},{"type":"object","required":["name","policy_type","accrual_method"]}]},"Time-Off-Policy-Update-Request":{"type":"object","description":"Request body for updating a time off policy","allOf":[{"$ref":"#/components/schemas/Time-Off-Policy-Request-Base"}]},"Time-Off-Activity":{"type":"object","x-examples":{"example":{"policy_uuid":"a7838f74-4c29-4b70-9bfb-02a4e3e60709","time_off_type":"vacation","policy_name":"Paid Time Off","event_type":"TimeOffEvent::AddToPolicy","event_description":"Added to policy: Vacation Per Hour Worked","effective_time":"2022-09-27T13:43:03.000-07:00","balance":"0.0","balance_change":"0.0"}},"description":"Representation of a Time Off Activity","properties":{"policy_uuid":{"type":["string","null"],"description":"unique identifier of a time off policy"},"time_off_type":{"type":"string","description":"Type of the time off activity","enum":["vacation","sick"]},"policy_name":{"type":["string","null"],"description":"The name of the time off policy for this activity"},"event_type":{"type":"string","description":"The type of the time off event/activity"},"event_description":{"type":["string","null"],"description":"A description for the time off event/activity"},"effective_time":{"type":["string","null"],"description":"The datetime of the time off activity"},"balance":{"type":["string","null"],"format":"float","description":"The time off balance at the time of the activity"},"balance_change":{"type":["string","null"],"format":"float","description":"The amount the time off balance changed as a result of the activity"}}},"Time-Off-Activity-List":{"type":"array","description":"A list of time off activities for an employee","items":{"$ref":"#/components/schemas/Time-Off-Activity"},"x-examples":{"example":[{"policy_uuid":"a7838f74-4c29-4b70-9bfb-02a4e3e60709","time_off_type":"vacation","policy_name":"Paid Time Off","event_type":"TimeOffEvent::AddToPolicy","event_description":"Added to policy: Vacation Per Hour Worked","effective_time":"2022-09-27T13:43:03.000-07:00","balance":"0.0","balance_change":"0.0"},{"policy_uuid":"a7838f74-4c29-4b70-9bfb-02a4e3e60709","time_off_type":"vacation","policy_name":"Paid Time Off","event_type":"TimeOffEvent::Accrual","event_description":"Accrual","effective_time":"2022-09-27T14:43:03.000-07:00","balance":"2.0","balance_change":"2.0"}]}},"Holiday-Pay-Policy":{"type":"object","x-examples":{"success_status":{"version":"1b37938b017c7fd7116bada007072290","company_uuid":"b7845189-f12b-4378-918a-d2b9de3dc4ea","federal_holidays":{"new_years_day":{"selected":true,"name":"New Year's Day","date":"January 1"},"mlk_day":{"selected":true,"name":"Martin Luther King, Jr. Day","date":"Third Monday in January"},"presidents_day":{"selected":false,"name":"Presidents' Day","date":"Third Monday in February"},"memorial_day":{"selected":true,"name":"Memorial Day","date":"Last Monday in May"},"juneteenth":{"selected":false,"name":"Juneteenth","date":"June 19"},"independence_day":{"selected":true,"name":"Independence Day","date":"July 4"},"labor_day":{"selected":false,"name":"Labor Day","date":"First Monday in September"},"columbus_day":{"selected":false,"name":"Columbus Day (Indigenous Peoples' Day)","date":"Second Monday in October"},"veterans_day":{"selected":true,"name":"Veterans Day","date":"November 11"},"thanksgiving":{"selected":true,"name":"Thanksgiving","date":"Fourth Thursday in November"},"christmas_day":{"selected":true,"name":"Christmas Day","date":"December 25"}},"employees":[{"uuid":"1ca3cd25-3eda-48c6-ac88-f0e7fb91a15a"}]}},"description":"Representation of a Holiday Pay Policy","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."},"company_uuid":{"type":"string","description":"A unique identifier for the company owning the holiday pay policy"},"federal_holidays":{"type":"object","description":"List of the eleven supported federal holidays and their details","properties":{"new_years_day":{"type":"object","properties":{"selected":{"type":"boolean"},"name":{"type":"string"},"date":{"type":"string"}}},"mlk_day":{"type":"object","properties":{"selected":{"type":"boolean"},"name":{"type":"string"},"date":{"type":"string"}}},"presidents_day":{"type":"object","properties":{"selected":{"type":"boolean"},"name":{"type":"string"},"date":{"type":"string"}}},"memorial_day":{"type":"object","properties":{"selected":{"type":"boolean"},"name":{"type":"string"},"date":{"type":"string"}}},"juneteenth":{"type":"object","properties":{"selected":{"type":"boolean"},"name":{"type":"string"},"date":{"type":"string"}}},"independence_day":{"type":"object","properties":{"selected":{"type":"boolean"},"name":{"type":"string"},"date":{"type":"string"}}},"labor_day":{"type":"object","properties":{"selected":{"type":"boolean"},"name":{"type":"string"},"date":{"type":"string"}}},"columbus_day":{"type":"object","properties":{"selected":{"type":"boolean"},"name":{"type":"string"},"date":{"type":"string"}}},"veterans_day":{"type":"object","properties":{"selected":{"type":"boolean"},"name":{"type":"string"},"date":{"type":"string"}}},"thanksgiving":{"type":"object","properties":{"selected":{"type":"boolean"},"name":{"type":"string"},"date":{"type":"string"}}},"christmas_day":{"type":"object","properties":{"selected":{"type":"boolean"},"name":{"type":"string"},"date":{"type":"string"}}}}},"employees":{"type":"array","description":"List of employee uuids under a holiday pay policy","items":{"type":"object","properties":{"uuid":{"type":"string"}}}}},"required":["version","company_uuid","federal_holidays","employees"]},"Holiday-Pay-Policy-Request":{"type":"object","description":"Request body for creating or updating a holiday pay policy","properties":{"federal_holidays":{"type":"object","description":"An object containing federal holiday objects, each containing a boolean selected property.","properties":{"new_years_day":{"type":"object","properties":{"selected":{"type":"boolean"}}},"mlk_day":{"type":"object","properties":{"selected":{"type":"boolean"}}},"presidents_day":{"type":"object","properties":{"selected":{"type":"boolean"}}},"memorial_day":{"type":"object","properties":{"selected":{"type":"boolean"}}},"juneteenth":{"type":"object","properties":{"selected":{"type":"boolean"}}},"independence_day":{"type":"object","properties":{"selected":{"type":"boolean"}}},"labor_day":{"type":"object","properties":{"selected":{"type":"boolean"}}},"columbus_day":{"type":"object","properties":{"selected":{"type":"boolean"}}},"veterans_day":{"type":"object","properties":{"selected":{"type":"boolean"}}},"thanksgiving":{"type":"object","properties":{"selected":{"type":"boolean"}}},"christmas_day":{"type":"object","properties":{"selected":{"type":"boolean"}}}}}}},"Paid-Holiday":{"type":"object","description":"A paid holiday derived from the company's holiday pay policy","x-examples":{"success_status":{"holiday_name":"New Year's Day","holiday_key":"new_years_day","start_date":"2023-01-02","end_date":"2023-01-02"}},"properties":{"holiday_key":{"type":["string","null"],"description":"The holiday's identifier (null for custom holidays)"},"holiday_name":{"type":"string","description":"The holiday's official name"},"start_date":{"type":"string","description":"The holiday's start date (YYYY-MM-DD)"},"end_date":{"type":"string","description":"The holiday's end date (YYYY-MM-DD)"}}},"Paid-Holidays":{"type":"array","description":"Representation of a company's paid holidays as described by their holiday pay policy","items":{"$ref":"#/components/schemas/Paid-Holiday"}},"Event":{"type":"object","x-examples":{"example":{"uuid":"f7397a24-57ad-4fae-b011-d258e8232900","event_type":"employee.bank_account.created","resource_type":"Company","resource_uuid":"92a20431-9489-4bde-ad27-6feb20b969d5","entity_type":"BankAccount","entity_uuid":"92a20431-9489-4bde-ad27-6feb20b969d5","timestamp":1686784995}},"description":"Representation of an Event","properties":{"uuid":{"type":"string","description":"Unique identifier for the event."},"event_type":{"type":"string","description":"Description of the event (e.g., payroll.submitted, or company.form.signed)."},"resource_type":{"type":"string","enum":["Company"],"description":"Name of the parent resource of the described entity."},"resource_uuid":{"type":"string","description":"Unique identifier for the parent resource."},"entity_type":{"type":"string","description":"Name of the entity that the event corresponds to."},"entity_uuid":{"type":"string","description":"Unique identifier for the entity."},"timestamp":{"type":"integer","description":"Time at which this event was created. Measured in seconds since the Unix epoch."}},"required":["uuid"]},"Event-List":{"type":"array","description":"A list of events","x-examples":{"success_status":[{"uuid":"f7397a24-57ad-4fae-b011-d258e8232900","event_type":"employee.created","resource_type":"Company","resource_uuid":"92a20431-9489-4bde-ad27-6feb20b969d5","entity_type":"Employee","entity_uuid":"92a20431-9489-4bde-ad27-6feb20b969d5","timestamp":1686784995},{"uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","event_type":"company.provisioned","resource_type":"Company","resource_uuid":"92a20431-9489-4bde-ad27-6feb20b969d5","entity_type":"Company","entity_uuid":"92a20431-9489-4bde-ad27-6feb20b969d5","timestamp":1686784994}]},"items":{"$ref":"#/components/schemas/Event"}},"Invoice-Data":{"type":"object","x-examples":{"example":{"active_companies":[{"company_uuid":"05ed3150-591e-4f8b-bfd5-55d478edd2d8","active_employees":5,"active_contractors":3,"initial_invoice_period":"2022-01"},{"company_uuid":"9b37429c-e540-40fb-86b3-738ca9af65c7","active_employees":0,"active_contractors":1,"initial_invoice_period":"2023-05"}]}},"description":"Representation of a partners invoice data","properties":{"active_companies":{"type":"array","description":"The list of companies that are active within the invoice period","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."}}}}}},"Information-Request":{"type":"object","x-examples":{"example":{"uuid":"704c1291-274d-4552-aa5d-e7031023c2e5","company_uuid":"3ac84ba3-87b3-40be-8523-d185dc243a6c","type":"account_protection","status":"pending_response","blocking_payroll":false,"required_questions":[]},"information_request_index_item":{"uuid":"704c1291-274d-4552-aa5d-e7031023c2e5","company_uuid":"3ac84ba3-87b3-40be-8523-d185dc243a6c","type":"company_onboarding","status":"pending_response","blocking_payroll":true,"required_questions":[{"question_uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","question_text":"How much wood can a wood chuck chuck?","response_type":"text"},{"question_uuid":"b2c3d4e5-f6a7-8901-bcde-f12345678901","question_text":"Please upload supporting documentation","response_type":"document"}]}},"description":"Representation of an information request","properties":{"uuid":{"type":"string","description":"Unique identifier of an information request"},"company_uuid":{"type":"string","description":"Unique identifier of the company to which the information requests belongs"},"type":{"description":"The type of information request","anyOf":[{"type":"string","enum":["company_onboarding","account_protection","payment_request","payment_error"]},{"type":"null"}]},"status":{"type":"string","description":"The status of the information request","enum":["pending_response","pending_review","approved"]},"blocking_payroll":{"type":"boolean","description":"If true, this information request is blocking payroll, and may require response or requires review from our Risk Ops team."},"required_questions":{"type":"array","description":"Questions the partner must answer or collect documents for","items":{"type":"object","properties":{"question_uuid":{"type":"string"},"question_text":{"type":"string"},"response_type":{"type":"string"}},"required":["question_uuid","question_text","response_type"]}}}},"Recurring-Reimbursement-List":{"type":"array","x-examples":{"success_status":[{"uuid":"04ca1051-dcec-4cb7-829c-dfbffdf4af23","employee_uuid":"73c96cc6-f8c9-4513-b3f1-4301351178d6","version":"3b8eda8460f7acabd86ceec924e0ae74","description":"Travel expenses","created_at":"2025-11-03T09:03:20.000-08:00","updated_at":"2025-11-03T09:03:20.000-08:00","amount":"100.00"},{"uuid":"e3fc7aae-5053-44bf-99e1-3636df0d1f5b","employee_uuid":"73c96cc6-f8c9-4513-b3f1-4301351178d6","version":"30c1aeb356a70e0a71275414e5f29b7e","description":"Meal allowance","created_at":"2025-11-03T09:03:20.000-08:00","updated_at":"2025-11-03T09:03:20.000-08:00","amount":"50.00"}]},"items":{"$ref":"#/components/schemas/Recurring-Reimbursement"}},"Recurring-Reimbursement":{"type":"object","x-examples":{"success_status":{"uuid":"b739f253-b028-443b-b6cf-97a555c3d493","employee_uuid":"346e1409-1c97-4524-9ebb-0c0c169e35cb","version":"cf9b64404e63d325c762aaad20ca7a39","description":"Office supplies","created_at":"2025-11-03T09:03:24.000-08:00","updated_at":"2025-11-03T09:03:24.000-08:00","amount":"75.50"}},"properties":{"uuid":{"type":"string","description":"The unique identifier of this recurring reimbursement.","readOnly":true},"employee_uuid":{"type":"string","description":"The UUID of the employee.","readOnly":true},"description":{"type":"string","description":"The description of the reimbursement."},"amount":{"type":"string","description":"The dollar amount of the reimbursement."},"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."},"created_at":{"type":"string","description":"The timestamp when this reimbursement was created.","readOnly":true},"updated_at":{"type":"string","description":"The timestamp when this reimbursement was last updated.","readOnly":true}},"required":["uuid","employee_uuid","description","amount","version"]},"Recovery-Case":{"type":"object","x-examples":{"example":{"uuid":"e83d273e-4ae9-4b61-9c71-4030c2f73093","company_uuid":"c5e3e3e9-732f-4762-849e-20b5cec9036f","status":"open","latest_error_code":"R01","original_debit_date":"2023-10-11","check_date":"2023-10-13","payroll_uuid":"210f2034-fb4a-4059-b109-6c3b5efe499d","contractor_payment_uuids":null,"amount_outstanding":10499.43,"event_total_amount":5912.07},"recovery_case_index_item":{"uuid":"e83d273e-4ae9-4b61-9c71-4030c2f73093","company_uuid":"c5e3e3e9-732f-4762-849e-20b5cec9036f","status":"open","latest_error_code":"R01","original_debit_date":"2023-10-11","check_date":"2023-10-13","payroll_uuid":"210f2034-fb4a-4059-b109-6c3b5efe499d","contractor_payment_uuids":null,"amount_outstanding":"10499.43","event_total_amount":"5912.07"}},"description":"Representation of a recovery case","properties":{"uuid":{"type":"string","description":"Unique identifier of an recovery case"},"company_uuid":{"type":"string","description":"Unique identifier of the company to which the recovery case belongs"},"status":{"type":"string","description":"Status of the recovery case","enum":["open","redebit_initiated","wire_initiated","recovered","lost"]},"latest_error_code":{"type":["string","null"],"description":"The latest bank error code for the recovery case. See [this doc](https://docs.gusto.com/embedded-payroll/docs/ach-codes-and-transaction-types) for a list of common ACH return codes."},"original_debit_date":{"type":["string","null"],"description":"Date when funds were originally debited from the company's bank account"},"check_date":{"type":"string","description":"Check date for the associated payroll or contractor payments"},"payroll_uuid":{"type":["string","null"],"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."},"contractor_payment_uuids":{"type":["array","null"],"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.","items":{"type":"string"}},"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"}},"required":["uuid"]},"Ach-Transaction":{"type":"object","x-examples":{"example":{"uuid":"123e4567-e89b-12d3-a456-426655440000","company_uuid":"456e7890-e12b-34c5-d678-901234567890","payment_event_type":"Payroll","payment_event_uuid":"789e0123-e45f-67ab-c890-123456789012","recipient_type":"Employee","recipient_uuid":"012e3456-f78d-90ab-12cd-345678901234","error_code":null,"transaction_type":"Credit employee pay","payment_status":"submitted","payment_direction":"credit","payment_event_check_date":"2023-10-02","payment_date":"2023-10-17","amount":"123.00","description":"PAY 380654"}},"description":"Representation of an ACH transaction","properties":{"uuid":{"type":"string","description":"Unique identifier of an ACH transaction"},"company_uuid":{"type":"string","description":"Unique identifier of the company to which the ACH transaction belongs"},"payment_event_type":{"type":"string","description":"The type of payment event associated with the ACH transaction","enum":["Payroll","ContractorPayment"]},"payment_event_uuid":{"type":"string","description":"Unique identifier for the payment event associated with the ACH transaction"},"recipient_type":{"description":"The type of recipient associated with the ACH transaction","anyOf":[{"type":"string","enum":["Employee","Contractor"]},{"type":"null"}]},"recipient_uuid":{"type":"string","description":"Unique identifier for the recipient associated with the ACH transaction"},"error_code":{"type":["string","null"],"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."},"transaction_type":{"type":"string","description":"The type of transaction associated with the ACH transaction"},"payment_status":{"type":"string","description":"The status of the ACH transaction","enum":["unsubmitted","submitted","successful","failed"]},"payment_direction":{"type":"string","description":"The direction of the payment","enum":["credit","debit"]},"payment_event_check_date":{"type":"string","description":"The date of the payment event check associated with the ACH transaction"},"payment_date":{"type":"string","description":"The date of the payment associated with the ACH transaction"},"amount":{"type":"string","description":"The amount of money moved by the ACH transaction. This amount is always non-negative."},"description":{"type":"string","description":"The description of the ACH transaction. Can be used to identify the ACH transaction on the recipient's bank statement."}},"required":["uuid"]},"Ach-Transaction-List":{"type":"array","items":{"$ref":"#/components/schemas/Ach-Transaction"},"x-examples":{"example":[{"uuid":"123e4567-e89b-12d3-a456-426655440000","company_uuid":"456e7890-e12b-34c5-d678-901234567890","payment_event_type":"Payroll","payment_event_uuid":"789e0123-e45f-67ab-c890-123456789012","recipient_type":"Employee","recipient_uuid":"012e3456-f78d-90ab-12cd-345678901234","error_code":null,"transaction_type":"Credit employee pay","payment_status":"submitted","payment_direction":"credit","payment_event_check_date":"2023-10-02","payment_date":"2023-10-17","amount":"123.00","description":"PAY 380654"}]}},"Wire-In-Request":{"type":"object","x-examples":{"example":{"uuid":"05ed3150-591e-4f8b-bfd5-55d478edd2d8","status":"awaiting_funds","origination_bank":"JP Morgan Chase","origination_bank_address":"1 Chase Plaza, New York, NY 10081","recipient_name":"Gusto, Inc","recipient_address":"525 20th Street, San Francisco, CA 94107","recipient_account_number":"21911761","recipient_routing_number":"123454321","additional_notes":"Additional Notes","bank_name":"JP Morgan Chase","date_sent":"2024-06-10","unique_tracking_code":"1trvxwxp57zf","payment_type":"Payroll","payment_uuid":"5faae454-e629-490b-a72a-c022c2c9e6bc","amount_sent":"1014500.00","requested_amount":"1014500.00","wire_in_deadline":"2024-06-21T18:00:00Z"}},"description":"Representation of a wire in request","properties":{"uuid":{"type":"string","description":"Unique identifier of a wire in request"},"status":{"type":"string","description":"Status of the wire in","enum":["awaiting_funds","pending_review","approved","canceled"]},"origination_bank":{"type":"string","description":"Name of bank receiving the wire in"},"origination_bank_address":{"type":"string","description":"Address of bank receiving the wire in"},"recipient_name":{"type":"string","description":"Name of the recipient of the wire In"},"recipient_address":{"type":"string","description":"Address of the recipient of the wire in"},"recipient_account_number":{"type":"string","description":"Recipient bank account number"},"recipient_routing_number":{"type":"string","description":"Recipient bank routing number"},"additional_notes":{"type":["string","null"],"description":"Notes for the wire in request"},"bank_name":{"type":["string","null"],"description":"Name of the bank initiating the wire in"},"date_sent":{"type":["string","null"],"description":"Date the wire in was sent"},"unique_tracking_code":{"type":"string","description":"Include in note with bank to track payment"},"payment_type":{"type":"string","description":"Type of payment for the wire in","enum":["Payroll","ContractorPaymentGroup"]},"payment_uuid":{"type":"string","description":"Unique identifier of the payment"},"amount_sent":{"type":["string","null"],"description":"Amount sent through wire in"},"requested_amount":{"type":"string","description":"Requested amount for the payment"},"wire_in_deadline":{"type":"string","description":"Deadline to submit the wire in"}}},"Wire-In-Request-List":{"type":"array","items":{"$ref":"#/components/schemas/Wire-In-Request"},"x-examples":{"example":[{"uuid":"c5fdae57-5483-4529-9aae-f0edceed92d4","status":"awaiting_funds","origination_bank":"JP Morgan Chase","origination_bank_address":"1 Chase Plaza, New York, NY 10081","recipient_name":"Gusto, Inc","recipient_address":"525 20th Street, San Francisco, CA 94107","recipient_account_number":"21911761","recipient_routing_number":"123454321","additional_notes":null,"bank_name":null,"date_sent":null,"unique_tracking_code":"1trvxwxp57zf","payment_type":"Payroll","payment_uuid":"5faae454-e629-490b-a72a-c022c2c9e6bc","amount_sent":null,"requested_amount":"1014500.00","wire_in_deadline":"2024-06-21T18:00:00Z"},{"uuid":"a47fc11d-8d92-4b3e-9f2a-3a23b9d8e7d1","status":"awaiting_funds","origination_bank":"JP Morgan Chase","origination_bank_address":"1 Chase Plaza, New York, NY 10081","recipient_name":"Gusto, Inc","recipient_address":"525 20th Street, San Francisco, CA 94107","recipient_account_number":"21911761","recipient_routing_number":"123454321","additional_notes":null,"bank_name":null,"date_sent":null,"unique_tracking_code":"6kfhwxq2crsm","payment_type":"ContractorPaymentGroup","payment_uuid":"8b6c3d70-9b8e-4d4d-b6a1-a1f3a6d9b2c4","amount_sent":null,"requested_amount":"15000.00","wire_in_deadline":"2024-06-21T18:00:00Z"}]}},"Wire-In-Request-Update-Request-Body":{"type":"object","properties":{"date_sent":{"type":"string","description":"The date the wire was sent","example":"2024-06-10"},"bank_name":{"type":"string","description":"Name of the bank sending the wire","example":"Chase"},"amount_sent":{"type":"string","description":"Amount of money sent","example":"314500.00"},"additional_notes":{"type":"string","description":"Additional notes","example":"Wire for 2024-06-15 payroll."}},"required":["date_sent","bank_name","amount_sent"]},"Payroll-Sync":{"type":"object","description":"Record representing the sync of time sheet data to payroll.","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the payroll sync.","example":"123e4567-e89b-12d3-a456-426655440000"},"company_uuid":{"type":"string","format":"uuid","description":"Unique identifier of the company to which the payroll sync belongs.","example":"123e4567-e89b-12d3-a456-426655440001"},"status":{"type":"string","readOnly":true,"enum":["pending","in_progress","success","failure","partial_success"],"description":"The current status of the payroll sync. READ-ONLY.\n\n## State Transitions\n```\npending ──────► in_progress ──────► success\n                            ├─────► failure\n                            └─────► partial_success\n```\n\n### Valid Transitions\n- `pending` → `in_progress`: Automatic when processing begins\n- `in_progress` → `success`: All time sheet data synced successfully\n- `in_progress` → `failure`: Sync failed entirely\n- `in_progress` → `partial_success`: Some members failed to sync\n","example":"pending"},"kind":{"type":"string","enum":["regular"],"description":"The kind of payroll sync.\n- `regular`: A regular payroll sync\n","example":"regular"},"pay_schedule_uuid":{"type":"string","format":"uuid","description":"Unique identifier of the pay schedule associated with this sync.","example":"123e4567-e89b-12d3-a456-426655440002"},"pay_period_start_date":{"type":"string","format":"date","description":"The start date of the pay period per ISO 8601 format.","example":"2025-01-01"},"pay_period_end_date":{"type":"string","format":"date","description":"The end date of the pay period per ISO 8601 format.","example":"2025-01-15"},"submitted_at":{"type":"string","format":"date-time","description":"Datetime for when the payroll sync was submitted.","example":"2025-01-16T12:00:00Z"},"completed_at":{"type":["string","null"],"format":"date-time","description":"Datetime for when the payroll sync completed. Null if the sync is still in progress.","example":"2025-01-16T13:00:00Z"},"errors":{"type":"array","description":"Errors encountered during the sync, if any. Each error follows the standard entity error format.","items":{"$ref":"#/components/schemas/Entity-Error-Object"}},"warnings":{"type":"array","description":"Warnings encountered during the sync, if any.","items":{"type":"string"}}},"x-examples":{"pending_sync":{"uuid":"123e4567-e89b-12d3-a456-426655440000","company_uuid":"123e4567-e89b-12d3-a456-426655440001","status":"pending","kind":"regular","pay_schedule_uuid":"123e4567-e89b-12d3-a456-426655440002","pay_period_start_date":"2025-01-01","pay_period_end_date":"2025-01-15","submitted_at":"2025-01-16T12:00:00Z","completed_at":null},"completed_sync":{"uuid":"123e4567-e89b-12d3-a456-426655440000","company_uuid":"123e4567-e89b-12d3-a456-426655440001","status":"success","kind":"regular","pay_schedule_uuid":"123e4567-e89b-12d3-a456-426655440002","pay_period_start_date":"2025-01-01","pay_period_end_date":"2025-01-15","submitted_at":"2025-01-16T12:00:00Z","completed_at":"2025-01-16T13:00:00Z"}}},"Payroll-Sync-Create-Request-Body":{"type":"object","required":["kind","pay_schedule_uuid","pay_period_start_date","pay_period_end_date"],"properties":{"kind":{"type":"string","enum":["regular"],"description":"The kind of payroll sync.\n- `regular`: A regular payroll sync\n","example":"regular"},"pay_schedule_uuid":{"type":"string","format":"uuid","description":"Unique identifier of the pay schedule to sync time sheets for.","example":"123e4567-e89b-12d3-a456-426614174000"},"pay_period_start_date":{"type":"string","format":"date","description":"The start date of the pay period per ISO 8601 format.","example":"2025-01-01"},"pay_period_end_date":{"type":"string","format":"date","description":"The end date of the pay period per ISO 8601 format.","example":"2025-01-15"}}},"Time-Sheet":{"type":"object","x-examples":{"example":{"uuid":"123e4567-e89b-12d3-a456-426655440000","company_uuid":"123e4567-e89b-12d3-a456-426655440000","status":"approved","time_zone":"America/Los_Angeles","entity_type":"Employee","version":"72deb67e16f7b92713c00d3582fa6c68","job_uuid":"123e4567-e89b-12d3-a456-426655440000","entity_uuid":"123e4567-e89b-12d3-a456-426655440000","shift_started_at":"2025-03-04T13:07:10Z","shift_ended_at":"2025-03-04T16:07:10Z","created_at":"2025-04-29T16:08:53Z","updated_at":"2025-04-29T16:08:53Z","metadata":{},"entries":[{"uuid":"123e4567-e89b-12d3-a456-426655440000","hours_worked":"1.000","pay_classification":"Regular"},{"uuid":"123e4567-e89b-12d3-a456-426655440000","hours_worked":"1.000","pay_classification":"Overtime"},{"uuid":"123e4567-e89b-12d3-a456-426655440000","hours_worked":"1.000","pay_classification":"Double overtime"}]}},"description":"Record representing an employee/contractor's time sheet","properties":{"uuid":{"type":"string","description":"Unique identifier of the time sheet."},"status":{"type":"string","description":"Status of the time sheet.","enum":["pending","rejected","approved"]},"company_uuid":{"type":"string","description":"Unique identifier of the company to which the time sheet belongs."},"time_zone":{"type":"string","description":"Time zone of where the time was tracked."},"entity_type":{"type":"string","description":"Type of entity associated with the time sheet.","enum":["Employee","Contractor"]},"entity_uuid":{"type":"string","description":"Unique identifier of the entity associated with the time sheet."},"version":{"type":"string","description":"The current version of the object. See the [versioning guide](https://docs.gusto.com/app-integrations/docs/idempotency) for information on how to use this field."},"job_uuid":{"type":"string","description":"Unique identifier of the job for which time was reported."},"shift_started_at":{"type":"string","format":"date-time","description":"The start time of the shift."},"shift_ended_at":{"type":"string","format":"date-time","description":"The end time of the shift. If the shift is still ongoing this field will be null."},"created_at":{"type":"string","format":"date-time","description":"Datetime for when time sheet was created."},"updated_at":{"type":"string","format":"date-time","description":"Datetime for when time sheet was updated."},"synced_to_payroll_at":{"type":["string","null"],"format":"date-time","description":"Datetime for when time sheet was synced to payroll. Null if the time sheet has not yet been synced to payroll."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"propertyNames":{"type":"string","maxLength":40},"maxProperties":50,"description":"Metadata associated with the time sheet. Key-value pairs of arbitrary data. Both keys and values must be strings."},"entries":{"type":"array","description":"Entries associated with the time sheet.","items":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier of the entry."},"hours_worked":{"type":"string","format":"float","description":"Hours worked for this pay classification. Represented as a string, e.g. \"1.500\"."},"pay_classification":{"type":"string","description":"Pay classification for the entry.","enum":["Regular","Overtime","Double overtime"]}}}}}},"Time-Sheet-Create-Body":{"type":"object","description":"Request body for creating a time sheet.","required":["entity_uuid","entity_type","time_zone","shift_started_at"],"properties":{"entity_uuid":{"type":"string","description":"Unique identifier of the entity associated with the time sheet."},"entity_type":{"type":"string","description":"Type of entity associated with the time sheet."},"job_uuid":{"type":"string","description":"Unique identifier of the job for which time is tracked."},"time_zone":{"type":"string","description":"Time zone of where the time is tracked."},"shift_started_at":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when the shift was started."},"shift_ended_at":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when the shift was ended. If the shift is still ongoing you can omit this field."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"propertyNames":{"type":"string","maxLength":40},"maxProperties":50,"description":"Metadata associated with the time sheet. Key-value pairs of arbitrary data. Both keys and values must be strings."},"entries":{"type":"array","description":"Entries associated with the time sheet.","items":{"type":"object","properties":{"hours_worked":{"type":"number","format":"float","maxDecimalPlaces":3,"minimum":0.001,"description":"Hours worked for this pay classification. Should be passed as number with up to 3 decimal places."},"pay_classification":{"type":"string","description":"Pay classification for the entry.","enum":["Regular","Overtime","Double overtime"]}}}}},"x-examples":{"Example":{"entity_uuid":"123e4567-e89b-12d3-a456-426614174000","entity_type":"Employee","job_uuid":"123e4567-e89b-12d3-a456-426614174000","time_zone":"America/New_York","shift_started_at":"2024-06-10T09:00:00Z","shift_ended_at":"2024-06-10T17:00:00Z","metadata":{"custom_field":"custom value"},"entries":[{"pay_classification":"Regular","hours_worked":1.5}]}},"x-tags":["Time Tracking"]},"Time-Sheet-Update-Body":{"type":"object","description":"Request body for updating a time sheet.","allOf":[{"$ref":"#/components/schemas/Versionable-Required"},{"type":"object","properties":{"entity_uuid":{"type":"string","description":"Unique identifier of the entity associated with the time sheet.","example":"123e4567-e89b-12d3-a456-426614174000"},"entity_type":{"type":"string","description":"Type of entity associated with the time sheet.","example":"Employee"},"job_uuid":{"type":"string","description":"Unique identifier of the job for which time was tracked. Currently is only supported for employees.","example":"123e4567-e89b-12d3-a456-426614174000"},"time_zone":{"type":"string","description":"Time zone of where the time was tracked.","example":"America/New_York"},"shift_started_at":{"type":"string","format":"date-time","description":"The start time of the shift. Timestamp should be in ISO8601","example":"2024-06-10T09:00:00Z"},"shift_ended_at":{"type":"string","format":"date-time","description":"The end time of the shift. If the shift is still ongoing this will be null.","example":"2024-06-10T17:00:00Z"},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"propertyNames":{"type":"string","maxLength":40},"maxProperties":50,"description":"Metadata associated with the time sheet. Key-value pairs of arbitrary data. Both keys and values must be strings."},"entries":{"type":"array","description":"Entries associated with the time sheet.","items":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier of the entry."},"hours_worked":{"type":"number","format":"float","maxDecimalPlaces":3,"minimum":0.001,"description":"Hours worked for this pay classification. Should be passed as number with up to 3 decimal places."},"pay_classification":{"type":"string","description":"Pay classification for the entry.","enum":["Regular","Overtime","Double overtime"]}}}}}}],"x-examples":{"Example":{"version":"72deb67e16f7b92713c00d3582fa6c68","entity_uuid":"123e4567-e89b-12d3-a456-426614174000","entity_type":"Employee","job_uuid":"123e4567-e89b-12d3-a456-426614174000","time_zone":"America/New_York","shift_started_at":"2024-06-10T09:00:00Z","shift_ended_at":"2024-06-10T17:00:00Z","metadata":{"custom_field":"custom value"},"entries":[{"uuid":"123e4567-e89b-12d3-a456-426614174000","hours_worked":1.5}]}},"x-tags":["Time Tracking"]},"Company-Suspension":{"type":"object","description":"Record representing the suspension of a company's Gusto account.","x-examples":{"switching_provider":{"uuid":"ade4528c-6cc4-4bd5-917a-9d636317e7d6","company_uuid":"3a0e3fb7-3d4b-4c7c-8ba0-9ce3c9f1f3be","effective_date":"2025-07-23","reason":"switching_provider","leaving_for":"adp","reconcile_tax_method":"refund_taxes","file_yearly_forms":false,"file_quarterly_forms":false,"comments":null,"tax_refunds":[]},"shutting_down":{"uuid":"5f04b8d0-1a41-40c6-9f5e-10b26ed89729","company_uuid":"3a0e3fb7-3d4b-4c7c-8ba0-9ce3c9f1f3be","effective_date":"2025-07-23","reason":"shutting_down","leaving_for":null,"reconcile_tax_method":"pay_taxes","file_yearly_forms":true,"file_quarterly_forms":true,"comments":null,"tax_refunds":[]}},"properties":{"uuid":{"type":"string","description":"Unique identifier for this suspension."},"company_uuid":{"type":"string","description":"Unique identifier for the company which is suspended."},"effective_date":{"type":"string","description":"Date that the suspension took effect."},"leaving_for":{"type":["string","null"],"description":"Which competitor the company is joining instead. Only required if `reason` is `'switching_provider'`."},"reason":{"type":"string","description":"Explanation for why the company's account was suspended."},"reconcile_tax_method":{"type":"string","description":"How Gusto will handle taxes already collected.","enum":["pay_taxes","refund_taxes"]},"file_quarterly_forms":{"type":"boolean","description":"Should Gusto file quarterly tax forms on behalf of the company? The correct answer can depend on why the company is suspending their account, and how taxes are being reconciled.\n"},"file_yearly_forms":{"type":"boolean","description":"Should Gusto file yearly tax forms on behalf of the company? The correct answer can depend on why the company is suspending their account, and how taxes are being reconciled.\n"},"comments":{"type":["string","null"],"description":"User-supplied comments describing why they are suspending their account."},"tax_refunds":{"type":"array","description":"Describes the taxes which are refundable to the company for this suspension. These may be refunded or paid by Gusto depending on the value in `reconcile_tax_method`.\n","items":{"type":"object","properties":{"amount":{"type":"string","description":"Dollar amount."},"description":{"type":"string","description":"What kind of tax this is."}}}}}},"Company-Suspension-List":{"type":"array","description":"List of suspension records for a company.","items":{"$ref":"#/components/schemas/Company-Suspension"},"x-examples":{"success_status":[{"uuid":"3bd0fa7c-071e-4e85-a6bf-f73a69797694","company_uuid":"3a0e3fb7-3d4b-4c7c-8ba0-9ce3c9f1f3be","effective_date":"2025-07-23","reason":"shutting_down","leaving_for":null,"reconcile_tax_method":"refund_taxes","file_yearly_forms":false,"file_quarterly_forms":false,"comments":null,"tax_refunds":[]},{"uuid":"2ad79a4e-2fbd-43ca-a77b-e9049e6cab15","company_uuid":"3a0e3fb7-3d4b-4c7c-8ba0-9ce3c9f1f3be","effective_date":"2025-07-23","reason":"switching_provider","leaving_for":"adp","reconcile_tax_method":"refund_taxes","file_yearly_forms":false,"file_quarterly_forms":false,"comments":"Company is transitioning to ADP for their payroll and HR needs","tax_refunds":[]}]}},"Company-Suspension-Creation-Errors":{"type":"object","allOf":[{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}],"x-examples":{"missing_required_fields":{"errors":[{"error_key":"reconcile_tax_method","category":"invalid_attribute_value","message":"Reconcile tax method is required"},{"error_key":"reason","category":"invalid_attribute_value","message":"Reason is required"},{"error_key":"file_yearly_forms","category":"invalid_attribute_value","message":"File yearly forms is required"}]},"gusto_com_requires_support":{"errors":[{"error_key":"leaving_for","category":"invalid_attribute_value","message":"Switching to Gusto.com must be processed by our Customer Support team"}]},"leaving_for_required":{"errors":[{"error_key":"leaving_for","category":"invalid_attribute_value","message":"Leaving for is required when switching providers"}]},"switching_provider_cannot_pay_taxes":{"errors":[{"error_key":"reconcile_tax_method","category":"invalid_attribute_value","message":"Reconcile tax method must be refund_taxes when switching to a new payroll provider"}]},"pay_taxes_requires_quarterly_filing":{"errors":[{"error_key":"file_quarterly_forms","category":"invalid_attribute_value","message":"File quarterly forms must be true when paying withheld taxes"}]}}},"Time-Off-Request":{"type":"object","description":"The representation of a time off request.","x-examples":{"success_status":{"uuid":"9145390f-0431-45ee-b8a0-6e7a8850d4cf","status":"approved","employee_note":"Vacation at Disney World!","employer_note":"But Universal has Harry Potter World...","days":{"2019-06-01":"4.000","2019-06-02":"8.000","2019-06-03":"2.000"},"request_type":"vacation","policy_type":"vacation","policy_uuid":"ae382963-06b2-4b57-9780-8feda862bb70","employee":{"uuid":"05f8663b-5944-4cfb-910e-1ee0a6df7b42","full_name":"Jessica Gusto"},"approver":{"uuid":"21d8dff4-ce09-4120-a274-3a5628bf6769","full_name":"Karen Gusto"},"initiator":{"uuid":"05f8663b-5944-4cfb-910e-1ee0a6df7b42","full_name":"Jessica Gusto"}}},"properties":{"uuid":{"type":"string","description":"The UUID of the time off request.","readOnly":true},"status":{"type":"string","description":"The status of the time off request.","enum":["pending","approved","declined","consumed"],"readOnly":true},"employee_note":{"type":"string","description":"A note about the time off request, from the employee to the employer.","readOnly":true},"employer_note":{"type":"string","description":"A note about the time off request, from the employer to the employee.","readOnly":true},"request_type":{"type":"string","description":"The type of time off request.","deprecated":true,"enum":["vacation","sick"],"readOnly":true},"policy_type":{"type":"string","description":"The type of the time off policy (e.g. vacation, sick).","readOnly":true},"policy_uuid":{"type":["string","null"],"description":"The UUID of the time off policy associated with this request.","readOnly":true},"days":{"description":"An object that represents the days in the time off request. The keys of the object are the dates, formatted as a YYYY-MM-DD string. The values of the object are the number of hours requested off for each day, formatted as a string representation of a numeric decimal to the thousands place.","type":"object","readOnly":true},"employee":{"type":"object","description":"","properties":{"uuid":{"type":"string","description":"The UUID of the employee the time off request is for.","readOnly":true},"full_name":{"type":"string","description":"The full name of the employee the time off request is for.","readOnly":true}},"readOnly":true},"initiator":{"type":["object","null"],"description":"","properties":{"uuid":{"type":"string","description":"The UUID of the employee who initiated the time off request.","readOnly":true},"full_name":{"type":"string","description":"The full name of the employee who initiated the time off request.","readOnly":true}},"readOnly":true},"approver":{"type":["object","null"],"description":"This value will be null if the request has not been approved.","properties":{"uuid":{"type":"string","description":"The UUID of the employee who approved the time off request.","readOnly":true},"full_name":{"type":"string","description":"The full name of the employee who approved the time off request.","readOnly":true}},"readOnly":true}}},"Time-Off-Request-List":{"type":"array","items":{"$ref":"#/components/schemas/Time-Off-Request"},"x-examples":{"success_status":[{"uuid":"9145390f-0431-45ee-b8a0-6e7a8850d4cf","status":"approved","employee_note":"Vacation at Disney World!","employer_note":"But Universal has Harry Potter World...","days":{"2019-06-01":"4.000","2019-06-02":"8.000","2019-06-03":"2.000"},"request_type":"vacation","policy_type":"vacation","policy_uuid":"ae382963-06b2-4b57-9780-8feda862bb70","employee":{"uuid":"05f8663b-5944-4cfb-910e-1ee0a6df7b42","full_name":"Jessica Gusto"},"approver":{"uuid":"21d8dff4-ce09-4120-a274-3a5628bf6769","full_name":"Karen Gusto"},"initiator":{"uuid":"05f8663b-5944-4cfb-910e-1ee0a6df7b42","full_name":"Jessica Gusto"}},{"uuid":"944cbbf4-8b13-4c45-babd-11ff13e17581","status":"pending","employee_note":"Coming down with the flu","employer_note":"","days":{"2019-02-01":"8.000"},"request_type":"sick","policy_type":"sick","policy_uuid":"bf493c7e-1a2d-4e5f-8c9a-3d7b6e4f2a1c","employee":{"uuid":"c2236d10-959a-4bb9-a21d-e14c6df447b6","full_name":"James Gusto"},"approver":null,"initiator":{"uuid":"c2236d10-959a-4bb9-a21d-e14c6df447b6","full_name":"James Gusto"}}]}},"Embedded-Time-Off-Request":{"type":"object","description":"The representation of a time off request.","required":["uuid","status","employee_note","employer_note","policy_type","policy_uuid","days","employee","initiator","approver"],"x-examples":{"success_status":{"uuid":"ad158cfb-99e4-4741-9db3-0bd3a267f222","status":"pending","employee_note":"Family vacation","employer_note":null,"days":{"2026-10-20":"8.000","2026-10-21":"8.000"},"policy_type":"vacation","policy_uuid":"c2d9b1bd-3f36-4c2d-a727-b2af057d6a7f","employee":{"uuid":"51924fa0-26c6-4d4c-8832-3ef0b422c67e","full_name":"Alex Johnson"},"approver":null,"initiator":{"uuid":"51924fa0-26c6-4d4c-8832-3ef0b422c67e","full_name":"Alex Johnson"}},"approved_status":{"uuid":"ad158cfb-99e4-4741-9db3-0bd3a267f222","status":"approved","employee_note":"Family vacation","employer_note":null,"days":{"2026-10-20":"8.000","2026-10-21":"8.000"},"policy_type":"vacation","policy_uuid":"c2d9b1bd-3f36-4c2d-a727-b2af057d6a7f","employee":{"uuid":"51924fa0-26c6-4d4c-8832-3ef0b422c67e","full_name":"Alex Johnson"},"approver":{"uuid":"21d8dff4-ce09-4120-a274-3a5628bf6769","full_name":"Morgan Chen"},"initiator":{"uuid":"51924fa0-26c6-4d4c-8832-3ef0b422c67e","full_name":"Alex Johnson"}},"declined_status":{"uuid":"ad158cfb-99e4-4741-9db3-0bd3a267f222","status":"declined","employee_note":"Family vacation","employer_note":"Not enough coverage","days":{"2026-10-20":"8.000","2026-10-21":"8.000"},"policy_type":"vacation","policy_uuid":"c2d9b1bd-3f36-4c2d-a727-b2af057d6a7f","employee":{"uuid":"51924fa0-26c6-4d4c-8832-3ef0b422c67e","full_name":"Alex Johnson"},"approver":null,"initiator":{"uuid":"51924fa0-26c6-4d4c-8832-3ef0b422c67e","full_name":"Alex Johnson"}}},"properties":{"uuid":{"type":"string","description":"The UUID of the time off request.","example":"ad158cfb-99e4-4741-9db3-0bd3a267f222","readOnly":true},"status":{"type":"string","description":"The status of the time off request.","example":"pending","enum":["pending","approved","declined","consumed"],"readOnly":true},"employee_note":{"type":["string","null"],"description":"A note about the time off request, from the employee to the employer.","example":"Family vacation","readOnly":true},"employer_note":{"type":["string","null"],"description":"A note about the time off request, from the employer to the employee.","example":null,"readOnly":true},"policy_type":{"type":["string","null"],"description":"The type of the time off policy (e.g. vacation, sick).","example":"vacation","readOnly":true},"policy_uuid":{"type":["string","null"],"description":"The UUID of the time off policy associated with this request.","example":"c2d9b1bd-3f36-4c2d-a727-b2af057d6a7f","readOnly":true},"days":{"description":"An object where keys are dates in YYYY-MM-DD format and values are hours as string decimals (e.g. {\"2025-01-20\": \"8.000\"}).","type":"object","additionalProperties":{"type":"string"},"example":{"2026-10-20":"8.000","2026-10-21":"8.000"},"readOnly":true},"employee":{"type":"object","description":"","properties":{"uuid":{"type":"string","description":"The UUID of the employee the time off request is for.","example":"51924fa0-26c6-4d4c-8832-3ef0b422c67e","readOnly":true},"full_name":{"type":"string","description":"The full name of the employee the time off request is for.","example":"Alex Johnson","readOnly":true}},"readOnly":true},"initiator":{"type":["object","null"],"description":"","properties":{"uuid":{"type":"string","description":"The UUID of the employee who initiated the time off request.","example":"51924fa0-26c6-4d4c-8832-3ef0b422c67e","readOnly":true},"full_name":{"type":"string","description":"The full name of the employee who initiated the time off request.","example":"Alex Johnson","readOnly":true}},"readOnly":true},"approver":{"type":["object","null"],"description":"This value will be null if the request has not been approved.","properties":{"uuid":{"type":"string","description":"The UUID of the employee who approved the time off request.","example":"21d8dff4-ce09-4120-a274-3a5628bf6769","readOnly":true},"full_name":{"type":"string","description":"The full name of the employee who approved the time off request.","example":"Morgan Chen","readOnly":true}},"readOnly":true}}},"Embedded-Time-Off-Request-List":{"type":"array","items":{"$ref":"#/components/schemas/Embedded-Time-Off-Request"},"x-examples":{"success_status":[{"uuid":"ad158cfb-99e4-4741-9db3-0bd3a267f222","status":"pending","employee_note":"Family vacation","employer_note":null,"days":{"2026-10-20":"8.000","2026-10-21":"8.000"},"policy_type":"vacation","policy_uuid":"c2d9b1bd-3f36-4c2d-a727-b2af057d6a7f","employee":{"uuid":"51924fa0-26c6-4d4c-8832-3ef0b422c67e","full_name":"Alex Johnson"},"approver":null,"initiator":{"uuid":"51924fa0-26c6-4d4c-8832-3ef0b422c67e","full_name":"Alex Johnson"}},{"uuid":"944cbbf4-8b13-4c45-babd-11ff13e17581","status":"approved","employee_note":"Feeling under the weather","employer_note":"Feel better soon!","days":{"2026-11-05":"8.000"},"policy_type":"sick","policy_uuid":"bf493c7e-1a2d-4e5f-8c9a-3d7b6e4f2a1c","employee":{"uuid":"c2236d10-959a-4bb9-a21d-e14c6df447b6","full_name":"James Rivera"},"approver":{"uuid":"21d8dff4-ce09-4120-a274-3a5628bf6769","full_name":"Morgan Chen"},"initiator":{"uuid":"c2236d10-959a-4bb9-a21d-e14c6df447b6","full_name":"James Rivera"}}]}},"Embedded-Time-Off-Request-Preview":{"type":"object","description":"Preview of the balance impact for a time off request before it is created or updated.","required":["balance_hours","this_request_hours","other_requested_hours","remaining_balance_hours","allow_negative_balance","unlimited"],"x-examples":{"success_status":{"balance_hours":"64.0","this_request_hours":"16.0","other_requested_hours":"0.0","remaining_balance_hours":"48.0","allow_negative_balance":false,"unlimited":false}},"properties":{"balance_hours":{"type":"string","nullable":true,"description":"The employee's current available balance hours for this policy. Null for unlimited policies.","example":"64.0","readOnly":true},"this_request_hours":{"type":"string","description":"The total hours for this time off request.","example":"16.0","readOnly":true},"other_requested_hours":{"type":"string","description":"Hours from other pending or approved requests for this policy.","example":"0.0","readOnly":true},"remaining_balance_hours":{"type":"string","nullable":true,"description":"The projected balance after this request is applied. Null for unlimited policies.","example":"48.0","readOnly":true},"allow_negative_balance":{"type":"boolean","description":"Whether the time off policy allows a negative balance.","example":false,"readOnly":true},"unlimited":{"type":"boolean","description":"Whether the time off policy provides unlimited time off.","example":false,"readOnly":true}}},"Embedded-Time-Off-Balance":{"type":"object","description":"Time off balance for an employee, grouped by policy.","x-examples":{"success_status":{"employee_uuid":"51924fa0-26c6-4d4c-8832-3ef0b422c67e","balances":[{"policy_uuid":"c2d9b1bd-3f36-4c2d-a727-b2af057d6a7f","balance_hours":"32.0","accrued_hours":"40.0","used_hours":"8.0","pending_hours":"0.0"}]}},"properties":{"employee_uuid":{"type":"string","description":"The UUID of the employee.","example":"51924fa0-26c6-4d4c-8832-3ef0b422c67e","readOnly":true},"balances":{"type":"array","description":"The employee's time off balances, one entry per policy.","readOnly":true,"items":{"type":"object","properties":{"policy_uuid":{"type":"string","description":"The UUID of the time off policy.","example":"c2d9b1bd-3f36-4c2d-a727-b2af057d6a7f","readOnly":true},"balance_hours":{"type":"string","description":"The employee's current available balance hours for this policy.","example":"32.0","readOnly":true},"accrued_hours":{"type":"string","description":"The total hours accrued year-to-date for this policy.","example":"40.0","readOnly":true},"used_hours":{"type":"string","description":"The total hours used year-to-date for this policy.","example":"8.0","readOnly":true},"pending_hours":{"type":["string","null"],"description":"The total hours from pending time off requests for this policy.","example":"0.0","readOnly":true}}}}}},"Embedded-Time-Off-Balance-List":{"type":"array","items":{"$ref":"#/components/schemas/Embedded-Time-Off-Balance"},"x-examples":{"success_status":[{"employee_uuid":"51924fa0-26c6-4d4c-8832-3ef0b422c67e","balances":[{"policy_uuid":"c2d9b1bd-3f36-4c2d-a727-b2af057d6a7f","balance_hours":"32.0","accrued_hours":"40.0","used_hours":"8.0","pending_hours":"0.0"}]}]}},"Contractor-Payment-Group-Preview":{"description":"Preview of a contractor payment group","type":"object","properties":{"uuid":{"type":["string","null"],"description":"The unique identifier of the contractor payment group.","readOnly":true},"company_uuid":{"type":"string","description":"The UUID of the company.","readOnly":true},"check_date":{"type":"string","description":"The check date of the contractor payment group.","readOnly":true},"debit_date":{"type":"string","description":"The debit date of the contractor payment group.","readOnly":true},"status":{"type":"string","description":"The status of the contractor payment group.  Will be `Funded` if all payments that should be funded (i.e. have `Direct Deposit` for payment method) are funded.  A group can have status `Funded` while having associated payments that have status `Unfunded`, i.e. payment with `Check` payment method.","enum":["Unfunded","Funded"],"readOnly":true},"creation_token":{"type":["string","null"],"description":"Token used to make contractor payment group creation idempotent.  Will error if attempting to create a group with a duplicate token.","readOnly":true},"partner_owned_disbursement":{"type":["boolean","null"],"description":"Whether the disbursement is partner owned.","readOnly":true},"submission_blockers":{"type":"array","description":"List of submission blockers for the contractor payment group.","readOnly":true,"items":{"$ref":"#/components/schemas/Payroll-Submission-Blocker-Type"}},"credit_blockers":{"type":"array","description":"List of credit blockers for the contractor payment group.","readOnly":true,"items":{"$ref":"#/components/schemas/Payroll-Credit-Blocker-Type"}},"totals":{"type":"object","properties":{"amount":{"type":"string","description":"The total amount for the group of contractor payments.","readOnly":true},"debit_amount":{"type":"string","description":"The total debit amount for the group of contractor payments. Sum of wage & reimbursement amount.","readOnly":true},"wage_amount":{"type":"string","description":"The total wage amount for the group of contractor payments.","readOnly":true},"reimbursement_amount":{"type":"string","description":"The total reimbursement amount for the group of contractor payments.","readOnly":true},"check_amount":{"type":"string","description":"The total check amount for the group of contractor payments.","readOnly":true}},"readOnly":true},"contractor_payments":{"type":"array","items":{"$ref":"#/components/schemas/Contractor-Payment-For-Group-Preview"}}},"x-examples":{"success":{"uuid":null,"company_uuid":"450ddadf-69da-4f37-92e5-8d78b94bffec","check_date":"2025-08-21","debit_date":"2025-08-19","status":"Unfunded","creation_token":"025e79ac-824d-4d3e-b819-8f265c3edb72","partner_owned_disbursement":null,"submission_blockers":[],"credit_blockers":[],"contractor_payments":[{"uuid":null,"contractor_uuid":"e894e72b-0aef-4856-9082-9c7826db998d","bonus":"0.0","hours":"0.0","hourly_rate":"0.0","may_cancel":true,"payment_method":"Direct Deposit","reimbursement":"750.0","status":"Unfunded","wage":"10000.0","wage_type":"Fixed","wage_total":"10000.0"}],"totals":{"amount":"10750.00","debit_amount":"10750.00","wage_amount":"10000.00","reimbursement_amount":"750.00","check_amount":"0.00"}},"With submission blockers":{"uuid":null,"company_uuid":"450ddadf-69da-4f37-92e5-8d78b94bffec","check_date":"2025-08-21","debit_date":"2025-08-19","status":"Unfunded","creation_token":"8f3ced95-ccba-4ace-ac5d-03c1080bb768","partner_owned_disbursement":null,"submission_blockers":[{"blocker_type":"fast_ach_threshold_exceeded","blocker_name":"Fast ACH Threshold Exceeded","selected_option":null,"status":"unresolved","unblock_options":[{"unblock_type":"wire_in","check_date":"2025-08-21","metadata":{"wire_in_deadline":"2025-08-21T18:00:00Z","wire_in_amount":"1000750.0"}},{"unblock_type":"move_to_four_day","check_date":"2025-08-21","metadata":{"debit_date":"2025-08-15"}}]}],"credit_blockers":[],"contractor_payments":[{"uuid":null,"contractor_uuid":"e894e72b-0aef-4856-9082-9c7826db998d","bonus":"0.0","hours":"0.0","hourly_rate":"0.0","may_cancel":true,"payment_method":"Direct Deposit","reimbursement":"750.0","status":"Unfunded","wage":"1000000.0","wage_type":"Fixed","wage_total":"1000000.0"}],"totals":{"amount":"1000750.00","debit_amount":"1000750.00","wage_amount":"1000000.00","reimbursement_amount":"750.00","check_amount":"0.00"}}}},"Contractor-Payment-Group-Partner-Disbursements":{"type":"object","description":"Partner disbursements for a contractor payment group","x-examples":{"success_status":{"contractor_payment_group_uuid":"123e4567-e89b-12d3-a456-426655440000","disbursements":[{"contractor_payment_uuid":"123e4567-e89b-12d3-a456-426655440001","contractor_uuid":"123e4567-e89b-12d3-a456-426655440002","payment_method":"Check","payment_status":"Not partner managed"},{"contractor_payment_uuid":"123e4567-e89b-12d3-a456-426655440003","contractor_uuid":"123e4567-e89b-12d3-a456-426655440004","payment_method":"Direct Deposit","payment_status":"Pending"}]}},"properties":{"contractor_payment_group_uuid":{"type":"string","description":"The UUID of the contractor payment group"},"disbursements":{"type":"array","description":"List of disbursements for the contractor payment group","items":{"type":"object","properties":{"contractor_payment_uuid":{"type":"string","description":"The UUID of the contractor payment"},"contractor_uuid":{"type":"string","description":"The UUID of the contractor"},"payment_method":{"type":"string","description":"The payment method for the disbursement","enum":["Direct Deposit","Check"]},"payment_status":{"type":"string","description":"The status of the payment","enum":["Pending","Paid","Not partner managed","Converted to check"]}}}}}},"Payroll-Partner-Disbursements":{"type":"object","description":"Partner disbursements for a payroll","x-examples":{"success_status":{"payroll_uuid":"123e4567-e89b-12d3-a456-426655440000","disbursements":[{"employee_uuid":"123e4567-e89b-12d3-a456-426655440001","payment_method":"Check","payment_status":"Not partner managed"},{"employee_uuid":"123e4567-e89b-12d3-a456-426655440002","payment_method":"Direct Deposit","payment_status":"Pending"}]}},"properties":{"payroll_uuid":{"type":"string","description":"The UUID of the payroll"},"disbursements":{"type":"array","description":"List of disbursements for the payroll","items":{"type":"object","properties":{"employee_uuid":{"type":"string","description":"The UUID of the employee"},"payment_method":{"type":"string","description":"The payment method for the disbursement","enum":["Direct Deposit","Check"]},"payment_status":{"type":"string","description":"The status of the payment","enum":["Pending","Paid","Not partner managed","Converted to check"]}}}}}},"Show-Employees":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Employee"},{"type":"object","additionalProperties":true,"properties":{"current_home_address":{"$ref":"#/components/schemas/Employee-Home-Address"},"all_home_addresses":{"type":"array","items":{"$ref":"#/components/schemas/Employee-Home-Address-History-Entry"}},"member_portal_invitation_status":{"type":["object","null"],"description":"Member portal invitation status information. Only included when the include param has the portal_invitations value set.","properties":{"status":{"type":"string","description":"The current status of the member portal invitation.","enum":["pending","sent","verified","complete","cancelled"]},"token_expired":{"type":["boolean","null"],"description":"Whether the invitation token has expired."},"welcome_email_sent_at":{"type":["string","null"],"format":"date-time","description":"The date and time when the welcome email was sent."},"last_password_resent_at":{"type":["string","null"],"format":"date-time","description":"The date and time when the password reset was last resent."}}},"partner_portal_invitation_sent":{"type":["boolean","null"],"description":"Whether an external partner portal invitation webhook has been sent for this employee. Only included when the include param has the portal_invitations value set."}}}]},"x-examples":{"success_status":[{"uuid":"d7282d99-ab6b-42f5-ba45-f4a670e886a8","first_name":"Boaty","middle_initial":null,"last_name":"Koss","email":"keena.feest@kiehn.co.uk","company_uuid":"e904cc79-818a-4da8-9d37-0be0a86fdda8","manager_uuid":null,"version":"a5cec1f1c0135feb3e76ca6ea3c46176","current_employment_status":"full_time","onboarding_status":"onboarding_completed","preferred_first_name":null,"department_uuid":null,"employee_code":"46f036","payment_method":"Direct Deposit","department":null,"terminated":false,"two_percent_shareholder":false,"onboarded":true,"historical":false,"has_ssn":true,"onboarding_documents_config":{"uuid":null,"i9_document":false},"jobs":[{"uuid":"bc875f9d-adc5-40f6-99db-ed8470bda25f","version":"863bcd01c51fcfa2468d604cffec7413","employee_uuid":"d7282d99-ab6b-42f5-ba45-f4a670e886a8","current_compensation_uuid":"2ec164d0-808b-446c-8120-8cfb500945d0","payment_unit":"Year","primary":true,"two_percent_shareholder":false,"state_wc_covered":null,"state_wc_class_code":null,"title":"","compensations":[{"uuid":"2ec164d0-808b-446c-8120-8cfb500945d0","employee_uuid":"d7282d99-ab6b-42f5-ba45-f4a670e886a8","version":"db7bfb49a4f0893432cb562311bfcad9","payment_unit":"Year","flsa_status":"Exempt","adjust_for_minimum_wage":false,"minimum_wages":[],"job_uuid":"bc875f9d-adc5-40f6-99db-ed8470bda25f","effective_date":"2025-06-09","rate":"80000.00"}],"rate":"80000.00","hire_date":"2024-06-09"}],"eligible_paid_time_off":[],"terminations":[],"garnishments":[],"date_of_birth":"2005-06-09","ssn":"","phone":null,"work_email":null,"current_home_address":{"street_1":"412 Kiera Stravenue","street_2":"Suite 391","city":"San Francisco","state":"CA","zip":"94107","country":"USA","active":true,"uiud":"sample-uuid-123231"},"all_home_addresses":[{"street_1":"412 Kiera Stravenue","street_2":"Suite 391","city":"San Francisco","state":"CA","zip":"94107","country":"USA","active":true,"uiud":"sample-uuid-123231"},{"street_1":"123 Example Rd","street_2":null,"city":"Example City","state":"EX","zip":"12345","country":"USA","active":false,"uiud":"another-sample-uuid-456789"}],"member_portal_invitation_status":{"status":"sent","token_expired":false,"welcome_email_sent_at":"2024-01-15T14:30:00Z","last_password_resent_at":null},"partner_portal_invitation_sent":true}]}},"Employee-Home-Address":{"type":"object","properties":{"street_1":{"type":["string","null"],"readOnly":false},"street_2":{"type":["string","null"],"readOnly":false},"city":{"type":["string","null"],"readOnly":false},"state":{"type":["string","null"],"readOnly":false},"zip":{"type":["string","null"],"readOnly":false},"country":{"type":["string","null"],"readOnly":false,"default":"USA"},"active":{"type":"boolean","description":"The status of the location. Inactive locations have been deleted, but may still have historical data associated with them.","readOnly":true},"uuid":{"type":"string","description":"Unique identifier for this address."}},"example":{"street_1":"412 Kiera Stravenue","street_2":"Suite 391","city":"San Francisco","state":"CA","zip":"94107","country":"USA","active":true,"uud":"sample-uuid-123231"}},"Employee-Home-Address-History-Entry":{"description":"A single entry in an employee's home-address history. Returned in the\n`all_home_addresses` array; includes the `effective_date` the address\nbecame active in addition to the shared `Employee-Home-Address` fields.\n","allOf":[{"$ref":"#/components/schemas/Employee-Home-Address"},{"type":"object","properties":{"effective_date":{"type":"string","format":"date","description":"The date the address became effective."}}}],"example":{"street_1":"412 Kiera Stravenue","street_2":"Suite 391","city":"San Francisco","state":"CA","zip":"94107","country":"USA","active":true,"uud":"sample-uuid-123231","effective_date":"2024-01-01"}},"Webhooks-Health-Check-Status":{"description":"The representation of a webhooks health check response","type":"object","x-examples":{"success_status":{"status":"healthy","last_checked_at":"2025-09-08T21:21:38.000Z"}},"properties":{"status":{"type":"string","description":"Latest health status of the webhooks system","readOnly":true,"enum":["healthy","unhealthy","unknown"]},"last_checked_at":{"type":"string","format":"date-time","readOnly":true,"description":"ISO8601 timestamp of the last successful health check with millisecond precision"}}},"Partner-Managed-Company-Migrate-Request":{"type":"object","description":"Request body is optional in API version 2026-02-01 and later. The Terms of Service signer is resolved from the authenticated payroll-admin user; the previously required `email`, `ip_address`, and `external_user_id` parameters are no longer accepted.\n","properties":{},"x-examples":{"typical":{}}},"Partner-Managed-Company-Migrate-Response":{"type":"object","properties":{"company_uuid":{"type":"string","description":"The company UUID."},"migration_status":{"type":"boolean","description":"Returns `true` when the migration completed successfully, `false` otherwise."},"errors":{"type":"array","description":"Migration blockers preventing the migration. Empty array when `migration_status` is `true`.","items":{"type":"object","properties":{"error_key":{"type":"string"},"category":{"type":"string","description":"Returns `migration_blocker` for blockers.","enum":["migration_blocker"]},"message":{"type":"string"},"metadata":{"type":"object","properties":{"key":{"type":"string","description":"Issue key (e.g., `company_suspended`, `terms_of_service`, `gusto_managed_benefits`)."}}}}}},"warnings":{"type":"array","description":"Non-blocking issues surfaced during migration (e.g., suspended company, active integrations). May be present even when `migration_status` is `true`.","items":{"type":"object","properties":{"error_key":{"type":"string"},"category":{"type":"string","description":"Returns `migration_warning` for warnings.","enum":["migration_warning"]},"message":{"type":"string"},"metadata":{"type":"object","properties":{"key":{"type":"string"}}}}}}},"x-examples":{"Example":{"company_uuid":"39abf9b9-650b-4e67-89a0-389dc6ee8a71","migration_status":true,"errors":[],"warnings":[{"error_key":"base","category":"migration_warning","message":"Company has active integrations.","metadata":{"key":"active_integrations"}}]}}},"Partner-Managed-Company-Create-Request":{"type":"object","required":["user","company"],"properties":{"user":{"type":"object","description":"Information for the user who will be the primary payroll administrator for the new company.","required":["first_name","last_name","email"],"properties":{"first_name":{"type":"string","description":"The first name 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."},"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."}}},"company":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"The legal name of the company."},"trade_name":{"type":"string","description":"The name of the company."},"ein":{"type":"string","description":"The employer identification number (EIN) of the company."},"contractor_only":{"type":"boolean","description":"Whether the company only supports contractors. Should be set to true if the company has no W-2 employees. If not passed, will default to false (i.e. the company will support both contractors and employees)."}}}},"x-examples":{"Example":{"user":{"first_name":"Frank","last_name":"Ocean","email":"frank@example.com","phone":"2345558899"},"company":{"name":"Frank's Ocean, LLC","trade_name":"Frank's Ocean","ein":"123456789","contractor_only":false}}}},"Partner-Managed-Company":{"description":"Object returned when creating a partner managed company","type":"object","properties":{"access_token":{"type":"string","description":"Access token that can be used for OAuth access to the account. Access tokens expire 2 hours after they are issued.","readOnly":true},"refresh_token":{"type":"string","description":"Refresh token that can be exchanged for a new access token.","readOnly":true},"company_uuid":{"type":"string","description":"Gusto's UUID for the company","readOnly":true},"expires_in":{"type":"integer","description":"Time of access_token expiration in seconds","readOnly":true}},"x-examples":{"Example":{"access_token":"de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54","refresh_token":"8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1","company_uuid":"d525dd21-ba6e-482c-be15-c2c7237f1364","expires_in":7200}}},"Migration-Blocker":{"description":"Migration blocker that blocks company migration","type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"error_key":{"type":"string","description":"Error key"},"category":{"type":"string","description":"Error category"},"message":{"type":"string","description":"Blocker message"},"metadata":{"type":"object","properties":{"key":{"type":"string","description":"A categorization of the migration blocker, e.g. \"migrated_company\""}}}}}}}},"Migration-Warning":{"description":"Migration warning that does not block company migration","type":"object","properties":{"warnings":{"type":"array","items":{"type":"object","properties":{"error_key":{"type":"string","description":"Error key"},"category":{"type":"string","description":"Error category"},"message":{"type":"string","description":"Warning message"},"metadata":{"type":"object","properties":{"key":{"type":"string","description":"A categorization of the migration warning, e.g. \"marijuana_related_business\""}}}}}}}},"Partner-Managed-Company-Migration-Readiness-Response":{"description":"","allOf":[{"type":"object","properties":{"ready_to_migrate":{"type":"boolean","description":"Indicates if the company is ready to be migrated."},"company_uuid":{"type":"string","description":"The company UUID"}}},{"$ref":"#/components/schemas/Migration-Blocker"},{"$ref":"#/components/schemas/Migration-Warning"}],"x-examples":{"Example":{"ready_to_migrate":false,"company_uuid":"39abf9b9-650b-4e67-89a0-389dc6ee8a71","errors":[{"error_key":"base","category":"invalid_operation","message":"The operation is already performed for this company.","metadata":{"key":"migrated_company"}}],"warnings":[]}}},"Partner-Managed-Company-Disassociate-Response":{"type":"object","description":"The company that was disassociated from the partner's embedded payroll product.","required":["company_uuid","company_name"],"properties":{"company_uuid":{"type":"string","format":"uuid","description":"The UUID of the disassociated company."},"company_name":{"type":"string","description":"The name of the disassociated company."}},"x-examples":{"Example":{"company_uuid":"39abf9b9-650b-4e67-89a0-389dc6ee8a71","company_name":"Acme LLC"}}},"Partner-Managed-Company-Accept-Terms-Of-Service-Request":{"type":"object","description":"","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."}},"x-examples":{"Example":{"ip_address":"192.168.1.2","external_user_id":"2005648946132","email":"jsmith99@gmail.com"}}},"Partner-Managed-Company-Retrieve-Terms-Of-Service-Request":{"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."}},"x-examples":{"Example":{"email":"jsmith99@gmail.com"}}},"Partner-Managed-Company-Terms-Of-Service-Response":{"description":"","type":"object","properties":{"latest_terms_accepted":{"type":"boolean","description":"Whether the latest terms have been accepted by the user."}},"x-examples":{"Example":{"latest_terms_accepted":true}}},"Provision-Create-Request-Body":{"type":"object","required":["user","company"],"properties":{"user":{"type":"object","description":"Information for the user who will be the primary payroll administrator for the new company.","required":["first_name","last_name","email"],"properties":{"first_name":{"type":"string","description":"The first name 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."},"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."}}},"company":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"The legal name of the company."},"trade_name":{"type":"string","description":"The name of the company."},"ein":{"type":"string","description":"The employer identification number (EIN) of the company."},"states":{"type":"array","description":"The states in which the company operates. States should be included by their two letter code, i.e. NY for New York. ","items":{"type":"string"}},"number_employees":{"type":"number","description":"The number of employees in the company."},"addresses":{"type":"array","uniqueItems":false,"description":"The locations for the company. This includes mailing, work, and filing addresses.","items":{"type":"object","properties":{"street_1":{"type":"string"},"street_2":{"type":["string","null"]},"city":{"type":"string"},"zip":{"type":"string"},"state":{"type":"string"},"phone":{"type":"string"},"is_primary":{"type":"string","description":"Whether or not this is a primary address for the company. If set to true, the address will be used as the mailing and filing address for the company and will be added as a work location. If set to false or not included, the address will only be added as a work location for the company. If multiple addresses are included, only one should be marked as primary."}}}}}}},"x-examples":{"Example":{"user":{"first_name":"Frank","last_name":"Ocean","email":"frank@example.com","phone":"2345558899"},"company":{"name":"Frank's Ocean, LLC","trade_name":"Frank's Ocean","tier":"complete","ein":"123456789","states":["CO","CA"],"number_employees":8,"addresses":[{"street_1":"1201 16th Street Mall","street_2":"Suite 350","city":"Denver","zip":"80202","state":"CO","phone":"2345678900","is_primary":"true"},{"street_1":"525 20th Street","city":"San Francisco","zip":"94107","state":"CA","phone":"2345678901"}]}}}},"Provision-Created":{"type":"object","properties":{"account_claim_url":{"type":"string","description":"A URL where the user should be redirected to complete their account setup inside of Gusto.","readOnly":true}},"x-examples":{"Example":{"account_claim_url":"https://app.gusto.com/claim_account/3456789"}}},"Employees-Annual-Fica-Wage-Report-Acceptance":{"type":"object","description":"Acceptance acknowledgement for an asynchronous employees annual FICA wage report. Returned with HTTP 202; poll the report status endpoint using `request_uuid`.","required":["request_uuid","company_uuid","start_year","end_year"],"properties":{"request_uuid":{"type":"string","format":"uuid","description":"The UUID of the report request. Use this to poll for report completion."},"company_uuid":{"type":"string","format":"uuid","description":"The UUID of the company."},"start_year":{"type":"integer","description":"The start year for the report."},"end_year":{"type":"integer","description":"The end year for the report."}},"x-examples":{"accepted":{"request_uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","company_uuid":"12345678-abcd-ef12-3456-7890abcdef12","start_year":2023,"end_year":2024}}},"Bulk-Report-Body":{"description":"Each `batch` item is a `custom_report` or a `general_ledger` report.","type":"object","required":["batch"],"properties":{"batch":{"type":"array","minItems":1,"maxItems":25,"description":"One report per item. Up to 25 items per batch, across any combination of companies the partner is mapped to.","items":{"$ref":"#/components/schemas/Bulk-Report-Item"}}},"example":{"batch":[{"company_uuid":"12345678-abcd-ef12-3456-7890abcdef12","report_type":"custom_report","columns":["employee_first_name"],"groupings":["employee"],"file_type":"csv","custom_name":"Q1 Payroll Export","with_totals":false,"start_date":"2026-01-01","end_date":"2026-03-31","date_filter_type":"check_date","payment_method":"check","employment_type":"exempt","employment_status":"active_full_time"},{"company_uuid":"12345678-abcd-ef12-3456-7890abcdef12","report_type":"general_ledger","payroll_uuid":"7b1d0df1-6403-4a06-8768-c1dd7d24d27a","aggregation":"default"}]},"x-tags":["Reports"]},"Bulk-Report-Item":{"description":"A single report inside a bulk batch. Required fields depend on `report_type`: `custom_report` requires `columns` and `file_type`; `general_ledger` requires `payroll_uuid` and `aggregation`.","oneOf":[{"$ref":"#/components/schemas/Bulk-Report-Custom-Report-Item"},{"$ref":"#/components/schemas/Bulk-Report-General-Ledger-Item"}],"discriminator":{"propertyName":"report_type","mapping":{"custom_report":"#/components/schemas/Bulk-Report-Custom-Report-Item","general_ledger":"#/components/schemas/Bulk-Report-General-Ledger-Item"}},"x-tags":["Reports"]},"Bulk-Report-Custom-Report-Item":{"description":"A custom report entry in a bulk batch.","type":"object","required":["company_uuid","report_type","columns","file_type"],"properties":{"company_uuid":{"type":"string","format":"uuid","description":"UUID of the company to generate the report for. The partner must be mapped to this company.","example":"12345678-abcd-ef12-3456-7890abcdef12"},"report_type":{"type":"string","enum":["custom_report"],"description":"Identifies this batch item as a custom report.","example":"custom_report"},"columns":{"type":"array","description":"Columns to include in the report.","items":{"type":"string","enum":["additional_earnings","bank_account_account_number","bank_account_routing_number","bank_account_type","bank_account","bonus","cash_tips","check_amount","check_date","commission","date_of_birth","double_overtime_earnings","double_overtime_hours","double_overtime_rate","employee_additional_taxes","employee_benefit_contributions","employee_compensation_time_period","employee_compensation","employee_deductions","employee_department","employee_email","employee_donations","employee_federal_income_tax","employee_first_name","employee_last_name","employee_middle_initial","employee_medicare_additional_tax","employee_medicare_tax","employee_phone_number","employee_social_security_tax","employee_state_income_tax","employee_taxes","employee_uuid","employee_work_email","employer_additional_taxes","employer_benefit_contributions","employer_cost","employer_futa_tax","employer_medicare_tax","employer_social_security_tax","employer_suta_tax","employer_taxes","employment_type","employment","end_date","garnishments","gross_earnings","holiday_earnings","holiday_hours","home_address_city","home_address_state","home_address_street","home_address_zip","home_address","job_title","net_pay","one_time_reimbursements","overtime_earnings","overtime_hours","overtime_rate","paid_time_off_earnings","paid_time_off_hours","paid_time_off_rate","pay_period_end","pay_period_start","paycheck_tips","payment_method","payroll_type","payroll_uuid","preferred_first_name","recurring_reimbursements","regular_earnings","regular_hours","regular_rate","reimbursements","risk_class_code","sick_rate","sick_time_off_earnings","sick_time_off_hours","start_date","total_employer_benefit_contributions","total_time_off_earnings","total_time_off_hours","work_address_city","work_address_street","work_address_zip"]}},"groupings":{"type":"array","description":"How to group the report. If omitted, defaults are derived from the requested `columns`.","items":{"type":"string","enum":["payroll","employee","work_address","work_address_state"]}},"file_type":{"type":"string","description":"The type of file to generate.","enum":["csv","json","pdf"]},"custom_name":{"type":"string","description":"Display name for the report."},"with_totals":{"type":"boolean","description":"Whether to include subtotals and grand totals.","default":false},"date_filter_type":{"type":"string","description":"Which payroll date `start_date` and `end_date` filter against.","default":"period_end_date","enum":["period_end_date","period_start_date","check_date"]},"start_date":{"type":"string","format":"date","description":"Start date of data to filter by.","example":"2026-01-01"},"end_date":{"type":"string","format":"date","description":"End date of data to filter by.","example":"2026-03-31"},"payment_method":{"type":"string","description":"Payment method to filter by.","enum":["check","direct_deposit"]},"employment_type":{"type":"string","description":"Employee employment type to filter by.","enum":["exempt","salaried_nonexempt","nonexempt","commission_only_exempt","commission_only_nonexempt"]},"employment_status":{"type":"string","description":"Employee employment status to filter by.","enum":["active_full_time","active_part_time","active_part_time_eligible","active_variable","active_seasonal","active","dismissed"]},"employee_uuids":{"type":["array","null"],"description":"Employees to filter by.","items":{"type":"string"}},"department_uuids":{"type":"array","description":"Departments to filter by.","items":{"type":"string"}},"work_address_uuids":{"type":"array","description":"Work addresses to filter by.","items":{"type":"string"}}},"x-tags":["Reports"]},"Bulk-Report-General-Ledger-Item":{"description":"A general ledger report entry in a bulk batch.","type":"object","required":["company_uuid","report_type","payroll_uuid","aggregation"],"properties":{"company_uuid":{"type":"string","format":"uuid","description":"UUID of the company to generate the report for. The partner must be mapped to this company.","example":"12345678-abcd-ef12-3456-7890abcdef12"},"report_type":{"type":"string","enum":["general_ledger"],"description":"Identifies this batch item as a general ledger report.","example":"general_ledger"},"payroll_uuid":{"type":"string","format":"uuid","description":"The UUID of the payroll to generate the general ledger for."},"aggregation":{"type":"string","enum":["default","job","department","integration"],"description":"The breakdown of the report. Use `default` for no split."},"integration_type":{"type":["string","null"],"description":"The kind of integration set up for the company. Required when `aggregation` is `integration`; must be null otherwise."}},"x-tags":["Reports"]},"Create-Bulk-Report":{"type":"object","required":["uuid","status"],"properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the bulk report batch."},"status":{"type":"string","enum":["pending","processing","completed","failed"],"description":"The batch's processing state.\n- `pending`: accepted, not yet started\n- `processing`: reports are being generated\n- `completed`: all reports finished\n- `failed`: the batch failed before completing\n"}},"x-examples":{"pending":{"uuid":"4c3a536c-4c88-4fec-a4db-eb4112ab9c92","status":"pending"}},"x-tags":["Reports"]},"Bulk-Report":{"type":"object","required":["uuid","status","submitted_at","completed_at","submitted_items"],"properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the bulk report batch."},"status":{"type":"string","enum":["pending","processing","success","partial_success","failed"],"description":"Overall batch status. `pending`/`processing` while in progress; once finished, `success` (all reports succeeded), `partial_success` (some succeeded, some failed), or `failed` (none succeeded)."},"submitted_at":{"type":"string","format":"date-time","description":"When the batch was accepted."},"completed_at":{"type":["string","null"],"format":"date-time","description":"When the batch reached a terminal state. Null while non-terminal."},"submitted_items":{"type":"integer","description":"How many reports the partner asked for in this batch."},"partner_uuid":{"type":"string","format":"uuid","description":"UUID of the partner that owns this batch. Returned only once the batch has finished; omitted while in progress."},"processed_items":{"type":"integer","description":"How many reports succeeded. Returned only once the batch has finished; omitted while in progress."},"report_url":{"type":["string","null"],"description":"Signed S3 URL to a zip containing every successfully-generated report, valid for 10 minutes. Returned only once the batch has finished; omitted while in progress."},"companies":{"type":"array","description":"Per-company breakdown. Returned only once the batch has finished; omitted while in progress.","items":{"$ref":"#/components/schemas/Bulk-Report-Company"}}},"x-examples":{"pending":{"uuid":"4c3a536c-4c88-4fec-a4db-eb4112ab9c92","status":"processing","submitted_at":"2026-06-10T10:24:54Z","completed_at":null,"submitted_items":2},"success":{"uuid":"4c3a536c-4c88-4fec-a4db-eb4112ab9c92","status":"success","submitted_at":"2026-06-10T10:24:54Z","completed_at":"2026-06-10T10:25:08Z","submitted_items":2,"partner_uuid":"0b9deb0b-5572-4b62-bce7-9b5624b6381d","processed_items":2,"report_url":"https://reports.gusto-api.com/bulk_reports/4c3a536c-4c88-4fec-a4db-eb4112ab9c92.zip","companies":[{"company_uuid":"12345678-abcd-ef12-3456-7890abcdef12","status":"success","reports":[{"report_type":"custom_report","file_type":"csv","status":"success","error":null},{"report_type":"general_ledger","file_type":"json","status":"success","error":null}]}]}},"x-tags":["Reports"]},"Bulk-Report-Company":{"description":"Results for a single company in a bulk report batch.","type":"object","required":["company_uuid","status","reports"],"properties":{"company_uuid":{"type":"string","format":"uuid","description":"UUID of the company."},"status":{"type":"string","enum":["pending","success","partial_success","failed"],"description":"This company's overall status across its `reports`:\n- `success`: every report succeeded\n- `partial_success`: some succeeded, some failed\n- `failed`: every report failed\n- `pending`: at least one report is still being generated\n"},"reports":{"type":"array","items":{"$ref":"#/components/schemas/Bulk-Report-Item-Result"}}},"x-tags":["Reports"]},"Bulk-Report-Item-Result":{"description":"A single report's outcome.","type":"object","required":["report_type","file_type","status","error"],"properties":{"report_type":{"type":"string","enum":["custom_report","general_ledger"],"description":"Which report this entry refers to."},"file_type":{"type":"string","description":"The report's output file type."},"status":{"type":"string","enum":["pending","success","failed"],"description":"The terminal state for this individual report."},"error":{"type":["string","null"],"description":"A user-facing error message when status is `failed`. Null on success."}},"x-tags":["Reports"]},"Member-Portal-Invitation":{"type":"object","description":"The status of a member portal invitation for an employee or contractor. Returned by `GET /v1/employees/{employee_id}/member_portal_invitations` and `GET /v1/contractors/{contractor_uuid}/member_portal_invitations`.\n","required":["status","expired"],"properties":{"status":{"type":"string","enum":["pending","sent","verified","complete","cancelled"],"description":"Current status of the member portal invitation.\n- `pending`: The invitation record has been created but the invitation email has not yet been delivered.\n- `sent`: The invitation email has been delivered to the member.\n- `verified`: The member has been verified by the member portal partner.\n- `complete`: The member has fully completed their member portal registration.\n- `cancelled`: The invitation has been cancelled, either via `DELETE` on this endpoint or because it was superseded.\n","example":"sent"},"expired":{"type":"boolean","description":"Whether the invitation can no longer be acted on by the member. Returns `true` when the invitation token has expired or when the invitation has been `cancelled`. To reissue an expired invitation, call `POST` on this endpoint again — a new token will be generated and will override the prior one.\n","example":false}},"x-examples":{"sent_invitation":{"status":"sent","expired":false},"complete_invitation":{"status":"complete","expired":false},"cancelled_invitation":{"status":"cancelled","expired":true}}}},"securitySchemes":{"CompanyAccessAuth":{"type":"http","scheme":"bearer","description":"Company-level authentication"},"SystemAccessAuth":{"type":"http","scheme":"bearer","description":"System-level authentication"}}},"paths":{"/v1/companies/{company_uuid}/ach_transactions":{"get":{"summary":"Get all ACH transactions for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","required":true,"description":"The UUID of the company","schema":{"type":"string"}},{"name":"contractor_payment_uuid","in":"query","required":false,"description":"The UUID of the contractor payment","schema":{"type":"string"}},{"name":"payroll_uuid","in":"query","required":false,"description":"The UUID of the payroll","schema":{"type":"string"}},{"name":"transaction_type","in":"query","required":false,"description":"Used to filter the ACH transactions to only include those with a specific transaction type, such as \"Credit employee pay\".","schema":{"type":"string"}},{"name":"payment_direction","in":"query","required":false,"description":"Used to filter the ACH transactions to only include those with a specific payment direction, either \"credit\" or \"debit\".","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-ach-transactions","security":[{"CompanyAccessAuth":[]}],"description":"Fetches all ACH transactions for a company.\n\nscope: `ach_transactions:read`","tags":["ACH Transactions"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Ach-Transaction-List/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Ach-Transaction-List"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/companies/{company_id}/admins":{"get":{"summary":"Get all the admins at a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-admins","security":[{"CompanyAccessAuth":[]}],"description":"Returns a list of all the admins at a company\n\nscope: `company_admin:read`","tags":["Companies"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":[{"$ref":"#/components/schemas/Admin/x-examples/Example"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Admin"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create an admin for the company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_id-admins","security":[{"CompanyAccessAuth":[]}],"description":"Creates a new admin for a company.\nIf the email matches an existing user, this will create an admin account for the current user. Otherwise, this will create a new user.\n\nscope: `company_admin:write`","tags":["Companies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Admin/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Admin"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"admin_missing_required_field":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/admin_missing_required_field"}},"admin_duplicate_email":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/admin_duplicate_email"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Admin-Create-Request"}}},"required":true}}},"/v1/benefits":{"get":{"summary":"Get all supported benefits","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."}],"x-gusto-rswag":true,"operationId":"get-v1-benefits","security":[{"CompanyAccessAuth":[]}],"description":"Returns all benefits supported by Gusto. The benefit object in Gusto contains high level information about a particular benefit type and its tax considerations. When companies choose to offer a benefit, they are creating a Company Benefit object associated with a particular benefit.\n\nscope: `benefits:read`","tags":["Company Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"full_catalog":{"value":{"$ref":"#/components/schemas/Supported-Benefit-List/x-examples/full_catalog"}}},"schema":{"$ref":"#/components/schemas/Supported-Benefit-List"}}}}}}},"/v1/benefits/{benefit_id}":{"get":{"summary":"Get a supported benefit","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"benefit_id","in":"path","description":"The benefit type in Gusto.","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-benefits-benefit_id","security":[{"CompanyAccessAuth":[]}],"description":"Returns a benefit supported by Gusto. The benefit object in Gusto contains high level information about a particular benefit type and its tax considerations. When companies choose to offer a benefit, they are creating a Company Benefit object associated with a particular benefit.\n\nscope: `benefits:read`","tags":["Company Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Supported-Benefit/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Supported-Benefit"}}}}}}},"/v1/benefits/{benefit_id}/requirements":{"get":{"summary":"Get benefit fields requirements by benefit type","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"benefit_id","in":"path","description":"The benefit type in Gusto.","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-benefits-benefits_id-requirements","security":[{"CompanyAccessAuth":[]}],"description":"Returns the field requirements for a given benefit type.\n\nscope: `benefits:read`","tags":["Company Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Benefit-Type-Requirements/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Benefit-Type-Requirements"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/bulk_reports":{"post":{"summary":"Create a bulk report batch","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."}],"x-gusto-rswag":true,"operationId":"post-v1-bulk_reports","security":[{"SystemAccessAuth":[]}],"description":"Triggers asynchronous generation of up to 25 reports across companies the partner is mapped to. Each `batch` item is a `custom_report` (same parameters as [create a custom report](https://docs.gusto.com/embedded-payroll/reference/post-companies-company_uuid-reports)) or a `general_ledger` report (same parameters as [create a general ledger report](https://docs.gusto.com/embedded-payroll/reference/post-payrolls-payroll_uuid-reports-general_ledger)), keyed by `company_uuid` and `report_type`. Items are validated synchronously; if any is invalid, the entire batch is rejected.\n\nPoll the [bulk report GET endpoint](https://docs.gusto.com/embedded-payroll/reference/get-v1-bulk_reports-request_uuid) with the returned `uuid` for status and the report URL, which is valid for 10 minutes.\n\n📘 System Access Authentication\n\nThis endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)\n\nscope: `company_reports:write`","tags":["Reports"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"pending":{"value":{"$ref":"#/components/schemas/Create-Bulk-Report/x-examples/pending"}}},"schema":{"$ref":"#/components/schemas/Create-Bulk-Report"}}}},"422":{"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","content":{"application/json":{"examples":{"bulk_report_invalid_report_type":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/bulk_report_invalid_report_type"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bulk-Report-Body"}}},"required":true}}},"/v1/bulk_reports/{request_uuid}":{"get":{"summary":"Get a bulk report batch","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"request_uuid","in":"path","description":"The UUID of the bulk report batch.","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-bulk_reports-request_uuid","security":[{"SystemAccessAuth":[]}],"description":"Get a bulk report batch's status and results given the `request_uuid`. While in progress, only batch metadata is returned; once complete, it also includes a signed `report_url` (a zip of all generated reports, valid for 10 minutes) and a per-company breakdown.\n\nReports containing PHI are inaccessible with `company_reports:read:tier_2_only` data scope.\n\n📘 System Access Authentication\n\nThis endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)\n\nscope: `company_reports:read`","tags":["Reports"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"pending":{"value":{"$ref":"#/components/schemas/Bulk-Report/x-examples/pending"}},"success":{"value":{"$ref":"#/components/schemas/Bulk-Report/x-examples/success"}}},"schema":{"$ref":"#/components/schemas/Bulk-Report"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/companies/{company_id}":{"get":{"summary":"Get a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies","security":[{"CompanyAccessAuth":[]}],"description":"Get a company.\n\nThe employees:read scope is required to return home_address and non-work locations.\nThe company_admin:read scope is required to return primary_payroll_admin.\nThe signatories:read scope is required to return primary_signatory.\n\nscope: `companies:read`","tags":["Companies"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Company/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Company"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-companies","security":[{"CompanyAccessAuth":[]}],"description":"Update a company.\n\nscope: `companies:write`","tags":["Companies"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Company/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Company"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"company_cannot_enable_contractor_only":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/company_cannot_enable_contractor_only"}},"company_missing_parameter":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/company_missing_parameter"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["contractor_only"],"properties":{"contractor_only":{"type":"boolean","description":"Whether the company only supports contractors. Must be updated in order for the company to start supporting W-2 employees. Can only be updated from true to false. Note that updating this value will require additional onboarding steps to be completed in order for the company to support W-2 employees."}}}}},"required":true}}},"/v1/companies/{company_id}/attachments":{"get":{"summary":"Get List of Company Attachments","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-attachments","security":[{"CompanyAccessAuth":[]}],"description":"Retrieve a list of all the attachments uploaded by the company.\n\n### Related guides\n- [Manage company attachments](doc:manage-company-attachments)\n\nscope: `company_attachments:read`","tags":["Company Attachment"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":[{"$ref":"#/components/schemas/Company-Attachment/x-examples/success_status"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Company-Attachment"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create Company Attachment and Upload File","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-attachment","security":[{"CompanyAccessAuth":[]}],"description":"Upload a file and create a company attachment. We recommend uploading PDF files for optimal compatibility. However, the following file types are allowed: .qbb, .qbm, .gif, .jpg, .png, .pdf, .xls, .xlsx, .doc and .docx.\n\n### Related guides\n- [Manage company attachments](doc:manage-company-attachments)\n\nscope: `company_attachments:write`","tags":["Company Attachment"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Company-Attachment/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Company-Attachment"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"company_attachment_missing_document":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/company_attachment_missing_document"}},"company_attachment_invalid_category":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/company_attachment_invalid_category"}},"company_attachment_invalid_file_type":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/company_attachment_invalid_file_type"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Company-Attachment-Create-Request-Body"}}},"required":true}}},"/v1/companies/{company_id}/attachments/{company_attachment_uuid}":{"get":{"summary":"Get Company Attachment Details","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"company_attachment_uuid","in":"path","description":"The UUID of the company attachment","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-attachment","security":[{"CompanyAccessAuth":[]}],"description":"Retrieve the detail of an attachment uploaded by the company.\n\n### Related guides\n- [Manage company attachments](doc:manage-company-attachments)\n\nscope: `company_attachments:read`","tags":["Company Attachment"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Company-Attachment/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Company-Attachment"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/companies/{company_id}/attachments/{company_attachment_uuid}/download_url":{"get":{"summary":"Get a temporary url to download the Company Attachment file","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"company_attachment_uuid","in":"path","description":"The UUID of the company attachment","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-attachment-url","security":[{"CompanyAccessAuth":[]}],"description":"Retrieve a temporary url to download an attachment file uploaded by the company.\n\n### Related guides\n- [Manage company attachments](doc:manage-company-attachments)\n\nscope: `company_attachments:read`","tags":["Company Attachment"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Company-Attachment-Download-Url/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Company-Attachment-Download-Url"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/companies/{company_id}/bank_accounts":{"get":{"summary":"Get all company bank accounts","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-bank-accounts","security":[{"CompanyAccessAuth":[]}],"description":"Returns company bank accounts. Currently, we only support a single default bank account per company.\n\nscope: `company_bank_accounts:read`","tags":["Bank Accounts"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":[{"$ref":"#/components/schemas/Company-Bank-Account/x-examples/success_status"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Company-Bank-Account"}}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create a company bank account","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_id-bank-accounts","security":[{"CompanyAccessAuth":[]}],"description":"This endpoint creates a new company bank account.\n\nUpon being created, two verification deposits are automatically sent to the bank account, and the bank account's verification_status is 'awaiting_deposits'.\n\nWhen the deposits are successfully transferred, the verification_status changes to 'ready_for_verification', at which point the verify endpoint can be used to verify the bank account.\nAfter successful verification, the bank account's verification_status is 'verified'.\n\n\n>🚧 Warning\n>\n> If a default bank account exists, it will be disabled and the new bank account will replace it as the company's default funding method.\n\nscope: `company_bank_accounts:write`","tags":["Bank Accounts"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Bank account unchanged","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Company-Bank-Account/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Company-Bank-Account"}}}},"201":{"description":"created","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Company-Bank-Account/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Company-Bank-Account"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"Invalid Attribute","content":{"application/json":{"examples":{"bank_account_missing_routing":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/bank_account_missing_routing"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company-Bank-Account-Request"}}},"required":true}}},"/v1/companies/{company_id}/bank_accounts/{bank_account_id}":{"delete":{"summary":"Delete a company bank account","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"bank_account_id","in":"path","description":"The UUID of the company bank account","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-companies-company_id-bank-accounts-bank_account_id","security":[{"CompanyAccessAuth":[]}],"description":"This endpoint disables a company bank account.\n\nA bank account cannot be disabled if it is used for any unprocessed payments.\n\nscope: `company_bank_accounts:write`","tags":["Bank Accounts"],"x-gusto-integration-type":["embedded"],"responses":{"204":{"description":"successful"},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"Cannot delete bank account with unfunded payments","content":{"application/json":{"examples":{"bank_account_delete_unfunded_payments":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/bank_account_delete_unfunded_payments"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/companies/{company_id}/bank_accounts/{bank_account_uuid}/verify":{"put":{"summary":"Verify a company bank account","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"bank_account_uuid","in":"path","description":"The UUID of the company bank account","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-companies-company_id-bank-accounts-verify","security":[{"CompanyAccessAuth":[]}],"description":"Verify a company bank account by confirming the two micro-deposits sent to the bank account.\n\nNote that the order of the two deposits specified in request parameters does not matter.\nThere's a maximum of 5 verification attempts, after which we will automatically initiate a new set of micro-deposits and require the bank account to be verified with the new micro-deposits.\n\n### Bank account verification in demo\nIn the demo environment, use the `POST /v1/companies/{company_id}/bank_accounts/{bank_account_uuid}/send_test_deposits` endpoint to simulate the micro-deposits transfer and return the two amounts in the response. You can call this endpoint as many times as you wish to retrieve the values of the two micro-deposits.\n\n### Webhooks\n- `company.bank_account.verified`: Fires when the company bank account is successfully verified.\n\n### Related guides\n- [Manage company bank accounts](doc:manage-company-bank-accounts)\n- [Bank Account Events](doc:bank-account-events)\n\nscope: `company_bank_accounts:write`","tags":["Bank Accounts"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Company-Bank-Account/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Company-Bank-Account"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"bank_account_verify_incorrect_deposits":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/bank_account_verify_incorrect_deposits"}},"bank_account_verify_already_verified":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/bank_account_verify_already_verified"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company-Bank-Account-Verify-Request"}}},"required":true}}},"/v1/companies/{company_id}/company_benefits":{"get":{"summary":"Get benefits for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"active","in":"query","required":false,"description":"Whether the benefit is currently active","schema":{"type":"boolean"}},{"name":"enrollment_count","in":"query","required":false,"description":"Whether to return employee enrollment count","schema":{"type":"boolean"}},{"name":"benefit_type","in":"query","required":false,"description":"Filter by benefit type. Comma-separated list of benefit type IDs, i.e. `?benefit_type=5,105`","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-company_benefits","security":[{"CompanyAccessAuth":[]}],"description":"Company benefits represent the benefits that a company is offering to employees. This ties together a particular supported benefit with the company-specific information for the offering of that benefit.\n\nNote that company benefits can be deactivated only when no employees are enrolled.\n\nBenefits containing PHI are only visible to applications with the `company_benefits:read:phi` scope.\n\nscope: `company_benefits:read`","tags":["Company Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":[{"$ref":"#/components/schemas/Company-Benefit/x-examples/Example"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Company-Benefit"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create a company benefit","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_id-company_benefits","security":[{"CompanyAccessAuth":[]}],"description":"Company benefits represent the benefits that a company is offering to employees. This ties together a particular supported benefit with the company-specific information for the offering of that benefit.\n\nNote that company benefits can be deactivated only when no employees are enrolled.\n\nWhen the application has the `company_benefits:write:benefit_type_limited` data scope, the application can only create company benefits for benefit types that are permitted for the application.\n\nscope: `company_benefits:write`","tags":["Company Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Company-Benefit/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Company-Benefit"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"company_benefit_missing_benefit_type":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/company_benefit_missing_benefit_type"}},"company_benefit_invalid_benefit_type":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/company_benefit_invalid_benefit_type"}},"company_benefit_missing_description":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/company_benefit_missing_description"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company-Benefit-Create-Request"}}},"required":true}}},"/v1/company_benefits/{company_benefit_id}":{"get":{"summary":"Get a company benefit","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_benefit_id","in":"path","description":"The UUID of the company benefit","required":true,"schema":{"type":"string"}},{"name":"with_employee_benefits","in":"query","required":false,"description":"Whether to return employee benefits associated with the benefit","schema":{"type":"boolean"}},{"name":"include","in":"query","required":false,"schema":{"type":"string","enum":["all_benefits"]},"description":"Available options:\n- all_benefits: If with_employee_benefits=true, include all effective dated benefits for each employee instead of only the current benefits."}],"x-gusto-rswag":true,"operationId":"get-v1-company_benefits-company_benefit_id","security":[{"CompanyAccessAuth":[]}],"description":"Company benefits represent the benefits that a company is offering to employees. This ties together a particular supported benefit with the company-specific information for the offering of that benefit.\n\nNote that company benefits can be deactivated only when no employees are enrolled.\n\nWhen with_employee_benefits parameter with true value is passed, employee_benefits:read scope is required to return employee_benefits.\n\nscope: `company_benefits:read`","tags":["Company Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Company-Benefit-With-Employee-Benefits/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Company-Benefit-With-Employee-Benefits"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update a company benefit","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_benefit_id","in":"path","description":"The UUID of the company benefit","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-company_benefits-company_benefit_id","security":[{"CompanyAccessAuth":[]}],"description":"Company benefits represent the benefits that a company is offering to employees. This ties together a particular supported benefit with the company-specific information for the offering of that benefit.\n\nNote that company benefits can be deactivated only when no employees are enrolled.\n\nWhen the application has the `company_benefits:write:benefit_type_limited` data scope, the application can only update company benefits for benefit types that are permitted for the application.\n\nscope: `company_benefits:write`","tags":["Company Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Company-Benefit/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Company-Benefit"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"company_benefit_cannot_disable":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/company_benefit_cannot_disable"}},"company_benefit_cannot_change_type":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/company_benefit_cannot_change_type"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company-Benefit-Update-Request"}}},"required":true}},"delete":{"summary":"Delete a company benefit","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_benefit_id","in":"path","description":"The UUID of the company benefit","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-company_benefits-company_benefit_id","security":[{"CompanyAccessAuth":[]}],"description":"The following must be true in order to delete a company benefit\n\n  - There are no employee benefits associated with the company benefit\n  - There are no payroll items associated with the company benefit\n  - The benefit is not managed by a Partner or by Gusto (type must be 'External')\n\nWhen the application has the `company_benefits:write:benefit_type_limited` data scope, the application can only delete company benefits for benefit types that are permitted for the application.\n\nscope: `company_benefits:write`","tags":["Company Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"204":{"description":"No Content"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"company_benefit_has_employees":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/company_benefit_has_employees"}},"company_benefit_partnered":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/company_benefit_partnered"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/company_benefits/{company_benefit_id}/contribution_exclusions":{"get":{"summary":"Get contribution exclusions for a company benefit","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_benefit_id","in":"path","description":"The UUID of the company benefit","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-company_benefits-company_benefit_id-contribution_exclusions","security":[{"CompanyAccessAuth":[]}],"description":"Returns all contributions for a given company benefit and whether they are excluded or not.\n\nCurrently this endpoint only works for 401-k and Roth 401-k benefit types.\n\nscope: `company_benefits:read`","tags":["Company Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"typical_exclusions":{"value":[{"$ref":"#/components/schemas/Contribution-Exclusion/x-examples/exclusion_bonus"},{"$ref":"#/components/schemas/Contribution-Exclusion/x-examples/exclusion_cash_tips"},{"$ref":"#/components/schemas/Contribution-Exclusion/x-examples/exclusion_commission"},{"$ref":"#/components/schemas/Contribution-Exclusion/x-examples/exclusion_regular"},{"$ref":"#/components/schemas/Contribution-Exclusion/x-examples/exclusion_imputed"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Contribution-Exclusion"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update contribution exclusions for a company benefit","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_benefit_id","in":"path","description":"The UUID of the company benefit","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-company_benefits-company_benefit_id-contribution_exclusions","security":[{"CompanyAccessAuth":[]}],"description":"Updates contribution exclusions for a given company benefit.\n\nCurrently this endpoint only works for 401-k and Roth 401-k benefit types.\n\nscope: `company_benefits:write`","tags":["Company Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"typical_exclusions":{"value":[{"$ref":"#/components/schemas/Contribution-Exclusion/x-examples/exclusion_bonus"},{"$ref":"#/components/schemas/Contribution-Exclusion/x-examples/exclusion_cash_tips"},{"$ref":"#/components/schemas/Contribution-Exclusion/x-examples/exclusion_commission"},{"$ref":"#/components/schemas/Contribution-Exclusion/x-examples/exclusion_regular"},{"$ref":"#/components/schemas/Contribution-Exclusion/x-examples/exclusion_imputed"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Contribution-Exclusion"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"company_benefit_invalid_contribution_exclusions":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/company_benefit_invalid_contribution_exclusions"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contribution-Exclusion-Update-Request"}}},"required":true}}},"/v1/company_benefits/{company_benefit_id}/employee_benefits":{"get":{"summary":"Get all employee benefits for a company benefit","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_benefit_id","in":"path","description":"The UUID of the company benefit","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}},{"name":"include","in":"query","required":false,"schema":{"type":"string","enum":["all_benefits"]},"description":"Available options:\n- all_benefits: Include all effective dated benefits for each employee instead of only the current benefits."}],"x-gusto-rswag":true,"operationId":"get-v1-company_benefits-company_benefit_id-employee_benefits","security":[{"CompanyAccessAuth":[]}],"description":"Employee benefits represent an employee enrolled in a particular company benefit. It includes information specific to that employee's enrollment.\n\nReturns an array of all employee benefits enrolled for this company benefit.\n\nBenefits containing PHI are only visible to applications with the `employee_benefits:read:phi` scope.\n\nscope: `employee_benefits:read`","tags":["Company Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":[{"$ref":"#/components/schemas/Employee-Benefit/x-examples/Example"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Employee-Benefit"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Bulk update employee benefits for a company benefit","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_benefit_id","in":"path","description":"The UUID of the company benefit","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-company_benefits-company_benefit_id-employee_benefits","security":[{"CompanyAccessAuth":[]}],"description":"Employee benefits represent an employee enrolled in a particular company benefit. It includes information specific to that employee's enrollment.\n\nCreate or update(if the employee is already enrolled in the company benefit previously) an employee benefit for the company benefit.\n\nBenefits containing PHI are only visible to applications with the `employee_benefits:read:phi` scope.\n\nWhen the application has the `employee_benefits:write:benefit_type_limited` data scope, the application can only create or update employee benefits for benefit types that are permitted for the application.\n\nscope: `employee_benefits:write`","tags":["Company Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":[{"$ref":"#/components/schemas/Employee-Benefit/x-examples/Example"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Employee-Benefit"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"employee_benefits_invalid_parameter":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/employee_benefits_invalid_parameter"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Employee-Benefit-Bulk-Update-Request"}}},"required":true}}},"/v1/company_benefits/{company_benefit_id}/summary":{"get":{"summary":"Get company benefit summary by company benefit id.","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_benefit_id","in":"path","description":"The UUID of the company benefit","required":true,"schema":{"type":"string"}},{"name":"start_date","in":"query","required":false,"description":"The start date for which to retrieve company benefit summary","example":"2022-01-01","schema":{"type":"string"}},{"name":"end_date","in":"query","required":false,"description":"The end date for which to retrieve company benefit summary. If left empty, defaults to today's date.","example":"2022-12-31","schema":{"type":"string"}},{"name":"detailed","in":"query","required":false,"description":"Display employee payroll item summary","schema":{"type":"boolean"}}],"x-gusto-rswag":true,"operationId":"get-v1-benefits-company_benefit_id-summary","security":[{"CompanyAccessAuth":[]}],"description":"Returns summary benefit data for the requested company benefit id.\n\nBenefits containing PHI are only visible to applications with the `company_benefits:read:phi` scope.\n\nscope: `company_benefits:read`","tags":["Company Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Benefit summary response","content":{"application/json":{"examples":{"typical_summary":{"value":{"$ref":"#/components/schemas/Benefit-Summary/x-examples/typical_summary"}}},"schema":{"$ref":"#/components/schemas/Benefit-Summary"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/companies/{company_id}/custom_fields":{"get":{"summary":"Get the custom fields of a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-custom_fields","security":[{"CompanyAccessAuth":[]}],"description":"Returns a list of the custom fields of the company. Useful when you need to know the schema of custom fields for an entire company.\n\nscope: `companies:read`","tags":["Companies"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Company-Custom-Field-List/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Company-Custom-Field-List"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/companies/{company_id}/forms":{"get":{"summary":"Get all company forms","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","pattern":"^(created_at|name|year|quarter|draft|document_content_type)(:(asc|desc))?(,(created_at|name|year|quarter|draft|document_content_type)(:(asc|desc))?)*$","example":"created_at:asc"},"description":"Sort by one or more fields. Options: created_at, name, year, quarter, draft, document_content_type. Append `:asc` or `:desc` to specify direction (e.g., `created_at:asc`). Defaults to ascending."},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-company-forms","security":[{"CompanyAccessAuth":[]}],"description":"Get a list of all company's forms\n\n### Related guides\n- [Company Forms](doc:company-form)\n\nscope: `company_forms:read`","tags":["Company Forms"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":[{"$ref":"#/components/schemas/Form/x-examples/Example"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Form"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/forms/{form_id}":{"get":{"summary":"Get a company form","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"form_id","in":"path","description":"The UUID of the form","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-company-form","security":[{"CompanyAccessAuth":[]}],"description":"Get a company form\n\nscope: `company_forms:read`","tags":["Company Forms"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Form/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Form"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/forms/{form_id}/pdf":{"get":{"summary":"Get a company form pdf","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"form_id","in":"path","description":"The UUID of the form","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-company-form-pdf","security":[{"CompanyAccessAuth":[]}],"description":"Get the link to the form PDF\n\nscope: `company_forms:read`","tags":["Company Forms"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Form-Pdf/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Form-Pdf"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/forms/{form_id}/sign":{"put":{"summary":"Sign a company form","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"form_id","in":"path","description":"The UUID of the form","required":true,"schema":{"type":"string"}},{"name":"x-gusto-client-ip","in":"header","required":false,"description":"Optional header to supply the IP address. This can be used to supply the IP address for signature endpoints instead of the signed_by_ip_address parameter.","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-company-form-sign","security":[{"CompanyAccessAuth":[]}],"description":"Sign a company form. Company forms must be signed by the company signatory.\n\nscope: `company_forms:sign`","tags":["Company Forms"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Form/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Form"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"form_already_signed":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/form_already_signed"}},"form_no_signature_required":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/form_no_signature_required"}},"form_invalid_ip_address":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/form_invalid_ip_address"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signature_text":{"type":"string","description":"The signature"},"agree":{"type":"boolean","description":"Whether you agree to sign electronically"},"signed_by_ip_address":{"type":"string","description":"The IP address of the signatory who signed the form. Both IPv4 AND IPv6 are supported. You must provide the IP address with either this parameter OR you can leave out this parameter and set the IP address in the request header using the `x-gusto-client-ip` header instead."}},"required":["signature_text","agree"]}}},"required":true}}},"/v1/companies/{company_id}/industry_selection":{"get":{"summary":"Get a company industry selection","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-company-industry","security":[{"CompanyAccessAuth":[]}],"description":"Returns the industry classification for a company, including NAICS code, SIC codes, and industry title.\n\nscope: `companies:read`","tags":["Industry Selection"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Industry/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Industry"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update a company industry selection","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-company-industry","security":[{"CompanyAccessAuth":[]}],"description":"Update the industry classification for a company by passing in a [NAICS code](https://www.naics.com).\n\nOptionally provide an industry title and [SIC codes](https://siccode.com/). If you do not provide SIC codes,\nwe will use the NAICS code to perform an internal lookup.\n\nOur UI leverages [Middesk API](https://docs.middesk.com/reference/introduction) to determine industry\nclassification codes.\n\nscope: `companies:write`","tags":["Industry Selection"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Industry/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Industry"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"company_industry_selection_naics_code_required":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/company_industry_selection_naics_code_required"}},"company_industry_selection_naics_code_invalid":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/company_industry_selection_naics_code_invalid"}},"company_industry_selection_sics_codes_invalid":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/company_industry_selection_sics_codes_invalid"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company-Industry-Selection-Required-Body"}}},"required":true}}},"/v1/companies/{company_uuid}/notifications":{"get":{"summary":"Get notifications for company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company for which you would like to return notifications","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["open","expired","resolved"]}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-company-notifications","security":[{"CompanyAccessAuth":[]}],"description":"Returns all notifications relevant for the given company.\n\nscope: `notifications:read`","tags":["Notifications"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Notifications-List/x-examples/success_status"}},"with_transactional_mailer_notification":{"value":{"$ref":"#/components/schemas/Notifications-List/x-examples/with_transactional_mailer_notification"}}},"schema":{"$ref":"#/components/schemas/Notifications-List"}}}}}}},"/v1/companies/{company_uuid}/onboarding_status":{"get":{"summary":"Get company onboarding status","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","example":"7b1d0df1-6403-4a06-8768-c1dd7d24d27a","required":true,"schema":{"type":"string"}},{"name":"additional_steps","in":"query","required":false,"example":"external_payroll","description":"Comma-delimited string of additional onboarding steps to include. Currently only supports the value \"external_payroll\".","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-company-onboarding-status","security":[{"CompanyAccessAuth":[]}],"description":"Retrieves a company's onboarding status, including whether onboarding is complete and the list of\nrequired onboarding steps with their respective completion state.\n\nscope: `company_onboarding_status:read`","tags":["Companies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Company-Onboarding-Status/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Company-Onboarding-Status"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/companies/{company_uuid}/finish_onboarding":{"put":{"summary":"Finish company onboarding","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","example":"7b1d0df1-6403-4a06-8768-c1dd7d24d27a","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-company-finish-onboarding","security":[{"CompanyAccessAuth":[]}],"description":"Finalize a company's onboarding process.\n\n### Approve a company in demo\n\nAfter a company is finished onboarding, Gusto requires an additional step to review and approve that company.\nThe company onboarding status is \"onboarding_completed\": false, until the API call is made to finish company\nonboarding. In production environments, this step is required for risk-analysis purposes.\n\nWe provide the endpoint `PUT '/v1/companies/{company_uuid}/approve'` to facilitate company approvals in the demo environment.\n\n```shell\nPUT '/v1/companies/89771af8-b964-472e-8064-554dfbcb56d9/approve'\n\n# Response: Company object, with company_status: 'Approved'\n```\n\nscope: `companies:write`","tags":["Companies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Company-Onboarding-Status/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Company-Onboarding-Status"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"finish_onboarding_incomplete":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/finish_onboarding_incomplete"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/companies/{company_uuid}/payment_configs":{"get":{"summary":"Get a company's payment configs","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-company-payment-configs","security":[{"CompanyAccessAuth":[]}],"description":"Get payment speed configurations for the company: payment speed (1-day, 2-day, or 4-day ACH), fast payment limit, partner-owned disbursement setting, and earned fast ACH blockers when applicable. 1-day is only available to partners that opt in.\n\n### Related guides\n- [Payroll Processing Speeds](doc:2-day-vs-4-day)\n\nscope: `company_payment_configs:read`","tags":["Payment Configs"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"typical_payment_config":{"value":{"$ref":"#/components/schemas/Payment-Configs/x-examples/typical_payment_config"}}},"schema":{"$ref":"#/components/schemas/Payment-Configs"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update a company's payment configs","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-company-payment-configs","security":[{"CompanyAccessAuth":[]}],"description":"Update payment speed, fast payment limit, and/or partner-owned disbursement for a company.\n\nAt least one of `payment_speed`, `fast_payment_limit`, or `partner_owned_disbursement` is required.\n1-day payment speed is only applicable to partners that opt in. 1-day is not allowed when AutoPilot is enabled.\n\n### Related guides\n- [Payroll Processing Speeds](doc:2-day-vs-4-day)\n\nscope: `company_payment_configs:write`","tags":["Payment Configs"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"typical_payment_config":{"value":{"$ref":"#/components/schemas/Payment-Configs/x-examples/typical_payment_config"}}},"schema":{"$ref":"#/components/schemas/Payment-Configs"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"payment_configs_missing_parameter":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/payment_configs_missing_parameter"}},"payment_configs_invalid_fast_payment_limit":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/payment_configs_invalid_fast_payment_limit"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment-Configs-Update-Request"}}},"required":true}}},"/v1/companies/{company_uuid}/suspensions":{"get":{"summary":"Get suspensions for this company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","required":true,"description":"The UUID of the company","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-companies-company_uuid-suspensions","security":[{"CompanyAccessAuth":[]}],"description":"Get existing suspension records for this company. A company may have multiple suspension records if they have suspended their Gusto account more than once.\n\n>📘 To check if company is already suspended\n>\n> To determine if a company is _currently_ suspended, use the `is_suspended` and `company_status` fields in the [Get a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies) endpoint.\n\nscope: `company_suspensions:read`","tags":["Companies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Company-Suspension-List/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Company-Suspension-List"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Suspend a company's account","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","required":true,"description":"The UUID of the company","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-companies-company_uuid-suspensions","security":[{"CompanyAccessAuth":[]}],"description":"Use this endpoint to suspend a company. After suspension, company will no longer be able to run payroll but will retain access to their information, such as retrieving employee info or retrieving past payrolls.\n\nscope: `company_suspensions:write`","tags":["Companies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"examples":{"switching_provider":{"value":{"$ref":"#/components/schemas/Company-Suspension/x-examples/switching_provider"}},"shutting_down":{"value":{"$ref":"#/components/schemas/Company-Suspension/x-examples/shutting_down"}}},"schema":{"$ref":"#/components/schemas/Company-Suspension"}}}},"422":{"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","content":{"application/json":{"examples":{"missing_required_fields":{"value":{"$ref":"#/components/schemas/Company-Suspension-Creation-Errors/x-examples/missing_required_fields"}},"gusto_com_requires_support":{"value":{"$ref":"#/components/schemas/Company-Suspension-Creation-Errors/x-examples/gusto_com_requires_support"}},"leaving_for_required":{"value":{"$ref":"#/components/schemas/Company-Suspension-Creation-Errors/x-examples/leaving_for_required"}}},"schema":{"$ref":"#/components/schemas/Company-Suspension-Creation-Errors"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["file_quarterly_forms","file_yearly_forms","reconcile_tax_method","reason"],"properties":{"file_quarterly_forms":{"type":"boolean","description":"Should Gusto file quarterly tax forms on behalf of the company? The correct answer can depend on why the company is suspending their account, and how taxes are being reconciled."},"file_yearly_forms":{"type":"boolean","description":"Should Gusto file yearly tax forms on behalf of the company? The correct answer can depend on why the company is suspending their account, and how taxes are being reconciled."},"reconcile_tax_method":{"type":"string","enum":["pay_taxes","refund_taxes"],"description":"How Gusto will handle taxes already collected."},"comments":{"type":"string","description":"User-supplied comments describing why they are suspending their account. Required if the user is leaving for another provider and selects \"other\" instead of a defined provider."},"reason":{"type":"string","enum":["switching_provider","shutting_down","acquired","no_more_employees","changing_ein_or_entity_type"],"description":"Explanation for why the company is suspending their account.\n\n> 🚧 FEIN or entity type changes require Customer Support\n> If a company is switching FEIN or changing their entity type, this change must be performed by Gusto Customer Support and cannot be performed via the API at this time.\n"},"leaving_for":{"type":"string","enum":["accountant","adp","adp_total_source","bamboo_hr","bank_or_financial_institution","check","deel","gusto_com","homebase","insperity","intuit_or_quickbooks","justworks","manual","namely","onpay","other","oyster","patriot","paychex","paycom","paylocity","remote","rippling","square","surepayroll","trinet","velocity_global","zenefits"],"description":"The competitor the company is switching to. Required if `reason` is `'switching_provider'`.\n\n> 🚧 Switching to Gusto requires Customer Support\n> If `'gusto_com'` is selected, this change must be completed by Gusto Customer Support and cannot be performed via the API. This endpoint will return a 422 error in that case.\n"}}}}},"required":true}}},"/v1/companies/{company_uuid}/tax_requirements":{"get":{"summary":"Get all tax requirements for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","required":true,"description":"The UUID of the company","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_uuid-tax_requirements","security":[{"CompanyAccessAuth":[]}],"description":"Retrieves all states for which a company has tax requirements, along with a boolean indicating whether tax setup\nis complete for each state. Use this to determine which states still need tax setup during company onboarding.\n\nscope: `company_tax_requirements:read`","tags":["Tax Requirements"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Tax-Requirement-States-List/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Tax-Requirement-States-List"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/companies/{company_uuid}/tax_requirements/{state}":{"get":{"summary":"Get tax requirements for a state","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","required":true,"description":"The UUID of the company","schema":{"type":"string"}},{"name":"state","in":"path","required":true,"description":"The two-letter state abbreviation","example":"CA","schema":{"type":"string"}},{"name":"scheduling","in":"query","required":false,"description":"When true, return \"new\" requirement sets with valid `effective_from` dates that are available to save new effective-dated values.","schema":{"type":"boolean"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_uuid-tax_requirements-state","security":[{"CompanyAccessAuth":[]}],"description":"Retrieves the detailed tax requirements for a specific state. The response includes requirement sets grouped by\ncategory (e.g., registrations, tax rates, deposit schedules), each containing individual requirements with their\ncurrent values, labels, and metadata describing the expected input format.\n\nUse this to build dynamic UIs for tax setup or to read the current tax configuration for a state.\n\nscope: `company_tax_requirements:read`","tags":["Tax Requirements"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"tax-requirements-state-ga-example":{"value":{"$ref":"#/components/schemas/Tax-Requirements-State/x-examples/tax-requirements-state-ga-example"}},"tax-requirements-metadata-select":{"value":{"$ref":"#/components/schemas/Tax-Requirements-State/x-examples/tax-requirements-metadata-select"}},"tax-requirements-metadata-radio":{"value":{"$ref":"#/components/schemas/Tax-Requirements-State/x-examples/tax-requirements-metadata-radio"}},"tax-requirements-metadata-account-number":{"value":{"$ref":"#/components/schemas/Tax-Requirements-State/x-examples/tax-requirements-metadata-account-number"}},"tax-requirements-metadata-tax-rate":{"value":{"$ref":"#/components/schemas/Tax-Requirements-State/x-examples/tax-requirements-metadata-tax-rate"}}},"schema":{"$ref":"#/components/schemas/Tax-Requirements-State"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update tax requirements for a state","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","required":true,"description":"The UUID of the company","schema":{"type":"string"}},{"name":"state","in":"path","required":true,"description":"The two-letter state abbreviation","example":"CA","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-companies-company_uuid-tax_requirements-state","security":[{"CompanyAccessAuth":[]}],"description":"Updates the tax requirement answers for a specific state. Submit answers to the requirement questions returned\nby [GET /v1/companies/{company_uuid}/tax_requirements/{state}](ref:get-v1-companies-company_uuid-tax_requirements-state).\n\n### Prerequisites\n\n1. Retrieve current requirements via [GET /v1/companies/{company_uuid}/tax_requirements/{state}](ref:get-v1-companies-company_uuid-tax_requirements-state)\n2. Ensure that each requirement set that you're updating includes the correct `key`, `state`, and `effective_from` values from the GET response\n\nscope: `company_tax_requirements:write`","tags":["Tax Requirements"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}},"tax_requirements_invalid_requirement_key":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/tax_requirements_invalid_requirement_key"}},"tax_requirements_invalid_value_type":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/tax_requirements_invalid_value_type"}},"tax_requirements_domain_validation_failure":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/tax_requirements_domain_validation_failure"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"requirement_sets":{"$ref":"#/components/schemas/Tax-Requirement-Set-Update"}}}}},"required":true}}},"/v1/companies/{company_id}/federal_tax_details":{"get":{"summary":"Get a company's federal tax details","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","example":"7b1d0df1-6403-4a06-8768-c1dd7d24d27a","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-federal_tax_details","security":[{"CompanyAccessAuth":[]}],"description":"Retrieves a company's federal tax details including EIN verification status, tax payer type, filing form, and other federal tax configuration.\n\nscope: `company_federal_taxes:read`","tags":["Federal Tax Details"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Success":{"value":{"$ref":"#/components/schemas/Federal-Tax-Details/x-examples/Success"}}},"schema":{"$ref":"#/components/schemas/Federal-Tax-Details"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update a company's federal tax details","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","example":"7b1d0df1-6403-4a06-8768-c1dd7d24d27a","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-companies-company_id-federal_tax_details","security":[{"CompanyAccessAuth":[]}],"description":"Updates a company's federal tax details including EIN, legal name, tax payer type, filing form, and S-Corp\ntaxation status. This information is required to onboard a company for use with Gusto Embedded Payroll.\n\n### Prerequisites\nBefore calling this endpoint, retrieve the current federal tax details and `version` via [GET /v1/companies/{company_id}/federal_tax_details](ref:get-v1-companies-company_id-federal_tax_details)\n\n### Webhooks\n- `company.updated`: Fires when federal tax details for a company are successfully updated\n\n**Setup:** [POST /v1/webhook_subscriptions](ref:post-v1-webhook-subscription) with `subscription_types`: `[\"Company\"]`\n\nscope: `company_federal_taxes:write`","tags":["Federal Tax Details"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Success":{"value":{"$ref":"#/components/schemas/Federal-Tax-Details/x-examples/Success"}}},"schema":{"$ref":"#/components/schemas/Federal-Tax-Details"}}}},"403":{"description":"Forbidden","content":{"application/json":{"examples":{"company_auto_archived":{"value":{"$ref":"#/components/schemas/Forbidden-Error-Object/x-examples/company_auto_archived"}}},"schema":{"$ref":"#/components/schemas/Forbidden-Error-Object"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"409":{"description":"Conflict","content":{"application/json":{"examples":{"invalid_version":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_version"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"federal_tax_invalid_ein":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/federal_tax_invalid_ein"}},"federal_tax_ein_cannot_change":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/federal_tax_ein_cannot_change"}},"federal_tax_legal_name_cannot_change":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/federal_tax_legal_name_cannot_change"}},"ein_collision":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/ein_collision"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Federal-Tax-Details-Update"}}},"required":true}}},"/v1/jobs/{job_id}/compensations":{"get":{"summary":"Get compensations for a job","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"job_id","in":"path","description":"The UUID of the job","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}},{"name":"include","in":"query","required":false,"schema":{"type":"string","enum":["all_compensations"]},"description":"Available options:\n- all_compensations: Include all effective dated compensations for each job instead of only the current compensation\n"}],"x-gusto-rswag":true,"operationId":"get-v1-jobs-job_id-compensations","security":[{"CompanyAccessAuth":[]}],"description":"Compensations contain information on how much is paid out for a job. Jobs may have many compensations, but only one that is active. The current compensation is the one with the most recent `effective_date`.\n\n*Note: Currently the API does not support creating multiple compensations per job - creating a compensation with the same job_uuid as another will fail with a relevant error.*\n\nUse `flsa_status` to determine if an employee is eligible for overtime\nBy default the API returns only the current compensation - use the `include` parameter to return all compensations.\n\nscope: `compensations:read`","tags":["Jobs and Compensations"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":[{"$ref":"#/components/schemas/Compensation/x-examples/success_status"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Compensation"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create a compensation","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"job_id","in":"path","description":"The UUID of the job","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-compensations-compensation_id","security":[{"CompanyAccessAuth":[]}],"description":"Compensations contain information on how much is paid out for a job. Jobs may have many compensations, but only one that is active. The current compensation is the one with the most recent `effective_date`.\n\n### Prerequisites\nBefore calling this endpoint:\n1. A [job](ref:post-v1-jobs-job_id) must exist for the employee\n\n### Webhooks\n- `employee_job_compensation.created`: Fires when a compensation is successfully created\n\nscope: `compensations:write`","tags":["Jobs and Compensations"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"201":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Compensation/x-examples/success_status"}},"minimum_wage_adjusted":{"value":{"$ref":"#/components/schemas/Compensation/x-examples/minimum_wage_adjusted"}}},"schema":{"$ref":"#/components/schemas/Compensation"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"compensation_invalid_rate":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/compensation_invalid_rate"}},"compensation_invalid_payment_unit":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/compensation_invalid_payment_unit"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Compensations-Request-Body"}}},"required":true}}},"/v1/compensations/{compensation_id}":{"get":{"summary":"Get a compensation","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"compensation_id","in":"path","description":"The UUID of the compensation","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-compensations-compensation_id","security":[{"CompanyAccessAuth":[]}],"description":"Compensations contain information on how much is paid out for a job. Jobs may have many compensations, but only one that is active. The current compensation is the one with the most recent `effective_date`.\n\nscope: `compensations:read`","tags":["Jobs and Compensations"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Compensation/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Compensation"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update a compensation","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"compensation_id","in":"path","description":"The UUID of the compensation","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-compensations-compensation_id","security":[{"CompanyAccessAuth":[]}],"description":"Compensations contain information on how much is paid out for a job. Jobs may have many compensations, but only one that is active. The current compensation is the one with the most recent `effective_date`.\n\n### Webhooks\n- `employee_job_compensation.updated`: Fires when a compensation is successfully updated\n\nscope: `compensations:write`","tags":["Jobs and Compensations"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Compensation/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Compensation"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"compensation_invalid_rate":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/compensation_invalid_rate"}},"compensation_invalid_payment_unit":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/compensation_invalid_payment_unit"}},"compensation_already_processed":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/compensation_already_processed"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Compensations-Update-Request-Body"}}},"required":true}},"delete":{"summary":"Delete a compensation","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"compensation_id","in":"path","description":"The UUID of the compensation","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-compensations-compensation_id","security":[{"CompanyAccessAuth":[]}],"description":"Compensations contain information on how much is paid out for a job. Jobs may have many compensations, but only one that is active. The current compensation is the one with the most recent `effective_date`. This endpoint deletes a compensation for a job that hasn't been processed on payroll.\n\n### Webhooks\n- `employee_job_compensation.destroyed`: Fires when a compensation is successfully deleted\n\nscope: `compensations:write`","tags":["Jobs and Compensations"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"204":{"description":"No Content"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"compensation_already_processed":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/compensation_already_processed"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/contractors/{contractor_uuid}/bank_accounts":{"get":{"summary":"Get all contractor bank accounts","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","description":"The UUID of the contractor","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-contractors-contractor_uuid-bank_accounts","security":[{"CompanyAccessAuth":[]}],"description":"Returns all contractor bank accounts.\n\nscope: `contractor_payment_methods:read`","tags":["Contractor Payment Method"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Contractor-Bank-Account-List/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Contractor-Bank-Account-List"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create a contractor bank account","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","description":"The UUID of the contractor","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-contractors-contractor_uuid-bank_accounts","security":[{"CompanyAccessAuth":[]}],"description":"Creates a contractor bank account.\n\nNote: We currently only support one bank account per contractor. Using this endpoint on a contractor who already has a bank account will just replace it.\n\nscope: `contractor_payment_methods:write`","tags":["Contractor Payment Method"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"Example response","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Contractor-Bank-Account/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Contractor-Bank-Account"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"contractor_bank_account_invalid_account_number":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_bank_account_invalid_account_number"}},"contractor_bank_account_invalid_account_type":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_bank_account_invalid_account_type"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contractor-Bank-Account-Create-Request-Body"}}},"required":true}}},"/v1/contractors/{contractor_uuid}/forms":{"get":{"summary":"Get all contractor forms","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","description":"The UUID of the contractor","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-contractor-forms","security":[{"CompanyAccessAuth":[]}],"description":"Get a list of all contractor's forms\n\nscope: `contractor_forms:read`","tags":["Contractor Forms"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":[{"$ref":"#/components/schemas/Form_1099/x-examples/Example"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Form_1099"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/contractors/{contractor_uuid}/forms/{form_id}":{"get":{"summary":"Get a contractor form","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","description":"The UUID of the contractor","required":true,"schema":{"type":"string"}},{"name":"form_id","in":"path","description":"The UUID of the form","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-contractor-form","security":[{"CompanyAccessAuth":[]}],"description":"Get a contractor form\n\nscope: `contractor_forms:read`","tags":["Contractor Forms"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Form_1099/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Form_1099"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/contractors/{contractor_uuid}/forms/{form_id}/pdf":{"get":{"summary":"Get the contractor form pdf","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","description":"The UUID of the contractor","required":true,"schema":{"type":"string"}},{"name":"form_id","in":"path","description":"The UUID of the form","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-contractor-form-pdf","security":[{"CompanyAccessAuth":[]}],"description":"Get the link to the form PDF\n\nscope: `contractor_forms:read`","tags":["Contractor Forms"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Form-Pdf/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Form-Pdf"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/contractors/{contractor_uuid}/address":{"get":{"summary":"Get a contractor address","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","description":"The UUID of the contractor","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-contractors-contractor_uuid-address","security":[{"CompanyAccessAuth":[]}],"tags":["Contractors"],"x-gusto-integration-type":["embedded"],"description":"The address of a contractor is used to determine certain tax information about them. Addresses are geocoded on create and update to ensure validity.\n\nscope: `contractors:read`","responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Contractor-Address/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Contractor-Address"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Create or update a contractor's address","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","description":"The UUID of the contractor","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-contractors-contractor_uuid-address","security":[{"CompanyAccessAuth":[]}],"tags":["Contractors"],"x-gusto-integration-type":["embedded"],"description":"The address of a contractor is used to determine certain tax information about them. Addresses are geocoded on create and update to ensure validity.\n\n> 🚧 Contractors can only have one address.\n>\n> When a contractor is created, an address is created for them by default. Updating the address will replace the existing address.\n\nscope: `contractors:write`","responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Contractor-Address/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Contractor-Address"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"contractor_address_invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_address_invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contractor-Address-Update-Body"}}},"required":true}}},"/v1/companies/{company_id}/contractors/payment_details":{"get":{"summary":"List contractor payment details","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company. This identifies the company whose contractor payment details you want to retrieve.","required":true,"schema":{"type":"string"}},{"name":"contractor_uuid","in":"query","required":false,"description":"Optional filter to get payment details for a specific contractor. When provided, the response will only include payment details for this contractor.","schema":{"type":"string"}},{"name":"contractor_payment_group_uuid","in":"query","required":false,"description":"Optional filter to get payment details for contractors in a specific payment group. When provided, the response will only include payment details for contractors in this group.","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-contractors-payment_details","security":[{"CompanyAccessAuth":[]}],"description":"Get payment details for contractors in a company. This endpoint returns a list of all contractors\nassociated with the specified company, including their payment methods and bank account details\nif they are paid via direct deposit.\n\nFor contractors paid by direct deposit, the response includes their bank account information\nwith sensitive data masked for security. The payment details also include information about\nhow their payments are split if they have multiple bank accounts configured.\n\nFor contractors paid by check, only the basic payment method information is returned.\n\n### Response Details\n- For direct deposit contractors:\n  - Bank account details (masked)\n  - Payment splits configuration\n  - Routing numbers\n  - Account types\n- For check payments:\n  - Basic payment method designation\n\n### Common Use Cases\n- Fetching contractor payment information for payroll processing\n- Verifying contractor payment methods\n- Reviewing payment split configurations\n\n`encrypted_account_number` is available only with the additional scope `contractor_payment_methods:read:account_numbers`.\n\nscope: `contractor_payment_methods:read`","tags":["Contractors"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Contractor-Payment-Details-List/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Contractor-Payment-Details-List"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/companies/{company_id}/contractor_payment_groups/preview":{"post":{"summary":"Preview a contractor payment group","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","required":true,"description":"The UUID of the company","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_id-contractor_payment_groups-preview","security":[{"CompanyAccessAuth":[]}],"description":"Preview a group of contractor payments. Request will validate inputs and return preview of the contractor payment group including the expected `debit_date`. The `uuid` field will be null in the response.\n\nThe returned `creation_token` is a required parameter in order to create the contractor payment group.\n\nscope: `payrolls:read`","tags":["Contractor Payment Groups"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Full contractor payment group object with null uuid","content":{"application/json":{"examples":{"success":{"value":{"$ref":"#/components/schemas/Contractor-Payment-Group-Preview/x-examples/success"}},"With submission blockers":{"value":{"$ref":"#/components/schemas/Contractor-Payment-Group-Preview/x-examples/With%20submission%20blockers"}}},"schema":{"$ref":"#/components/schemas/Contractor-Payment-Group-Preview"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided ID/UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"basic":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/basic"}},"resource":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/resource"}},"nested":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/nested"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["contractor_payments"],"properties":{"contractor_payments":{"type":"array","items":{"type":"object","properties":{"contractor_uuid":{"type":"string","description":"The contractor receiving the payment"},"payment_method":{"type":"string","enum":["Direct Deposit","Check","Historical Payment"],"default":"Direct Deposit"},"wage":{"type":"string","format":"float","description":"If the contractor is on a fixed wage, this is the fixed wage payment for the contractor, regardless of hours worked","example":"5000.0"},"hours":{"type":"string","format":"float","example":"40.0","description":"If the contractor is on an hourly wage, this is the number of hours that the contractor worked for the payment"},"bonus":{"type":"string","format":"float","example":"500.0","description":"If the contractor is on an hourly wage, this is the bonus the contractor earned"},"reimbursement":{"type":"string","format":"float","example":"20.0","description":"Reimbursed wages for the contractor"},"invoice_number":{"type":"string","maxLength":25,"example":"INV-001","description":"An optional invoice number to associate with this contractor payment. This will be visible to the contractor on their paystub."},"memo":{"type":"string","example":"Payment for consulting services","description":"An optional note or memo for this contractor payment. This will be visible to the contractor on their paystub."}}}},"check_date":{"type":"string","format":"date","description":"Date when payments should be processed"}}}}},"required":true}}},"/v1/contractor_payment_groups/{contractor_payment_group_uuid}/fund":{"put":{"summary":"Fund a contractor payment group [DEMO]","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_payment_group_uuid","in":"path","required":true,"description":"The UUID of the contractor payment group","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-contractor_payment_groups-contractor_payment_group_id-fund","security":[{"CompanyAccessAuth":[]}],"description":"> 🚧 Demo action\n> This action is only available in the Demo environment\n\nSimulate funding a contractor payment group. Funding only occurs automatically in the production environment when bank transactions are generated. Use this action in the demo environment to transition a contractor payment group's `status` from `Unfunded` to `Funded`. A `Funded` status is required for generating a contractor payment receipt.\n\nscope: `payrolls:run`","tags":["Contractor Payment Groups"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Full contractor payment group object","content":{"application/json":{"examples":{"success":{"value":{"$ref":"#/components/schemas/Contractor-Payment-Group/x-examples/success"}}},"schema":{"$ref":"#/components/schemas/Contractor-Payment-Group"}}}},"404":{"description":"Not Found\n\nThe requested contractor payment group does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"basic":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/basic"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/companies/{company_id}/contractor_payment_groups":{"get":{"summary":"Get contractor payment groups for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","required":true,"description":"The UUID of the company","schema":{"type":"string"}},{"name":"start_date","in":"query","required":false,"description":"The time period for which to retrieve contractor payment groups. Defaults to 6 months ago.","example":"2020-01-01","schema":{"type":"string"}},{"name":"end_date","in":"query","required":false,"description":"The time period for which to retrieve contractor payment groups. Defaults to today's date.","example":"2020-12-31","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-contractor_payment_groups","security":[{"CompanyAccessAuth":[]}],"description":"Returns a list of minimal contractor payment groups within a given time period, including totals but not associated contractor payments.\n\nscope: `payrolls:read`","tags":["Contractor Payment Groups"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"List of Contractor Payment Groups","content":{"application/json":{"examples":{"success":{"value":[{"$ref":"#/components/schemas/Contractor-Payment-Group-With-Blockers/x-examples/success"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Contractor-Payment-Group-With-Blockers"}}}}},"404":{"description":"Not Found\n\nThe requested company does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create a contractor payment group","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","required":true,"description":"The UUID of the company","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_id-contractor_payment_groups","security":[{"CompanyAccessAuth":[]}],"description":"Pay a group of contractors. Information needed depends on the contractor's wage type (hourly vs fixed)\n\nscope: `payrolls:run`","tags":["Contractor Payment Groups"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"Full contractor payment group object","content":{"application/json":{"examples":{"success":{"value":{"$ref":"#/components/schemas/Contractor-Payment-Group/x-examples/success"}},"With submission blockers":{"value":{"$ref":"#/components/schemas/Contractor-Payment-Group/x-examples/With%20submission%20blockers"}}},"schema":{"$ref":"#/components/schemas/Contractor-Payment-Group"}}}},"404":{"description":"Not Found\n\nThe requested company does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"basic":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/basic"}},"resource":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/resource"}},"nested":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/nested"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["check_date","contractor_payments","creation_token"],"properties":{"check_date":{"type":"string","format":"date","description":"The payment check date","example":"2020-01-01"},"creation_token":{"type":"string","description":"A token used to make contractor payment group creation idempotent. The string must be unique for each group you intend to create.","example":"1d532d13-8f61-4a57-ad3c-b5fac1c6e05e"},"submission_blockers":{"type":"array","description":"Optional array of submission blockers with selected unblock options. Returned from the preview endpoint and can be submitted with selected_option to resolve blockers.","items":{"type":"object","properties":{"blocker_type":{"type":"string","description":"The type of blocker that is blocking the payment submission"},"selected_option":{"type":["string","null"],"description":"The unblock option selected to resolve the submission blocker"},"message":{"type":"string","description":"Optional message related to the blocker"},"options":{"type":"array","description":"Optional array of additional options for the blocker","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of option"},"message":{"type":"string","description":"Message for the option"}}}}}}},"contractor_payments":{"type":"array","items":{"type":"object","properties":{"contractor_uuid":{"type":"string","description":"The contractor receiving the payment"},"payment_method":{"type":"string","enum":["Direct Deposit","Check","Historical Payment"],"default":"Direct Deposit"},"wage":{"type":"string","format":"float","description":"If the contractor is on a fixed wage, this is the fixed wage payment for the contractor, regardless of hours worked","example":"5000.0"},"hours":{"type":"string","format":"float","example":"40.0","description":"If the contractor is on an hourly wage, this is the number of hours that the contractor worked for the payment"},"bonus":{"type":"string","format":"float","example":"500.0","description":"If the contractor is on an hourly wage, this is the bonus the contractor earned"},"reimbursement":{"type":"string","format":"float","example":"20.0","description":"Reimbursed wages for the contractor"},"invoice_number":{"type":"string","maxLength":25,"example":"INV-001","description":"An optional invoice number to associate with this contractor payment. This will be visible to the contractor on their paystub."},"memo":{"type":"string","example":"Payment for consulting services","description":"An optional note or memo for this contractor payment. This will be visible to the contractor on their paystub."}}}}}}}},"required":true}}},"/v1/contractor_payment_groups/{contractor_payment_group_uuid}":{"get":{"summary":"Get a contractor payment group","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_payment_group_uuid","in":"path","required":true,"description":"The UUID of the contractor payment group","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-contractor_payment_groups-contractor_payment_group_id","security":[{"CompanyAccessAuth":[]}],"description":"Returns a contractor payment group with all associated contractor payments.\n\nscope: `payrolls:read`","tags":["Contractor Payment Groups"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"examples":{"success":{"value":{"$ref":"#/components/schemas/Contractor-Payment-Group/x-examples/success"}},"With submission blockers":{"value":{"$ref":"#/components/schemas/Contractor-Payment-Group/x-examples/With%20submission%20blockers"}}},"schema":{"$ref":"#/components/schemas/Contractor-Payment-Group"}}}},"404":{"description":"Not Found\n\nThe requested contractor payment group does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"delete":{"summary":"Cancel a contractor payment group","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_payment_group_uuid","in":"path","required":true,"description":"The UUID of the contractor payment group","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-contractor_payment_groups-contractor_payment_group_id","security":[{"CompanyAccessAuth":[]}],"description":"Cancels a contractor payment group and all associated contractor payments. All contractor payments must be cancellable, unfunded.\n\nscope: `payrolls:run`","tags":["Contractor Payment Groups"],"x-gusto-integration-type":["embedded"],"responses":{"204":{"description":"Successfully cancelled"},"404":{"description":"Not Found\n\nThe requested contractor payment group does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"Unprocessable Entity\n\nThis may happen when trying to cancel a payment group that is not in a cancellable state, such as one that has already been funded or processed.\n","content":{"application/json":{"examples":{"basic":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/basic"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/contractor_payment_groups/{id}/partner_disbursements":{"get":{"summary":"Get partner disbursements for a contractor payment group","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"id","in":"path","required":true,"description":"The UUID of the contractor payment group","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-contractor_payment_groups-id-partner_disbursements","security":[{"CompanyAccessAuth":[]}],"description":"Get partner disbursements for a specific contractor payment group.\n\nscope: `partner_disbursements:read`","tags":["Contractor Payment Groups"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Contractor-Payment-Group-Partner-Disbursements/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Contractor-Payment-Group-Partner-Disbursements"}}}},"404":{"description":"Not Found\n\nThe requested contractor payment group does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"patch":{"summary":"Update partner disbursements for a contractor payment group","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"id","in":"path","required":true,"description":"The UUID of the contractor payment group","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"patch-v1-contractor_payment_groups-id-partner_disbursements","security":[{"CompanyAccessAuth":[]}],"description":"Update partner disbursements for a specific contractor payment group.\n\nscope: `partner_disbursements:write`","tags":["Contractor Payment Groups"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Contractor-Payment-Group-Partner-Disbursements/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Contractor-Payment-Group-Partner-Disbursements"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"mixed_disbursement_errors":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/mixed_disbursement_errors"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"disbursements":{"type":"array","items":{"type":"object","properties":{"contractor_payment_uuid":{"type":"string","description":"UUID of the contractor payment","example":"9f8e7d6c-5b4a-3928-1c2d-3e4f5a6b7c8d"},"payment_method":{"type":"string","enum":["Direct Deposit","Check"],"description":"Payment method for the contractor"},"payment_status":{"type":"string","enum":["Pending","Paid","Not partner managed","Converted to check"],"description":"Status of the payment disbursement"}},"required":["contractor_payment_uuid"]}}},"required":["disbursements"]}}}}}},"/v1/contractors/{contractor_uuid}/payment_method":{"get":{"summary":"Get a contractor's payment method","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","description":"The UUID of the contractor","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-contractors-contractor_uuid-payment_method","security":[{"CompanyAccessAuth":[]}],"description":"Fetches a contractor's payment method. A contractor payment method\ndescribes how the payment should be split across the contractor's associated\nbank accounts.\n\nscope: `contractor_payment_methods:read`","tags":["Contractor Payment Method"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"check_method":{"value":{"$ref":"#/components/schemas/Contractor-Payment-Method/x-examples/check_method"}}},"schema":{"$ref":"#/components/schemas/Contractor-Payment-Method"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update a contractor's payment method","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","description":"The UUID of the contractor","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-contractors-contractor_id-payment_method","security":[{"CompanyAccessAuth":[]}],"description":"Updates a contractor's payment method. Note that creating a contractor\nbank account will also update the contractor's payment method.\n\nscope: `contractor_payment_methods:write`","tags":["Contractor Payment Method"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"check_method":{"value":{"$ref":"#/components/schemas/Contractor-Payment-Method/x-examples/check_method"}}},"schema":{"$ref":"#/components/schemas/Contractor-Payment-Method"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"409":{"description":"Conflict","content":{"application/json":{"examples":{"invalid_version":{"value":{"$ref":"#/components/schemas/Conflict-Error-Object/x-examples/invalid_version"}}},"schema":{"$ref":"#/components/schemas/Conflict-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"contractor_payment_method_invalid_type":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_payment_method_invalid_type"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["version","type"],"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.","example":"63859768485e218ccf8a449bb60f14ed"},"type":{"type":"string","enum":["Direct Deposit","Check"],"description":"The payment method type. If type is Direct Deposit, the contractor is required to have a bank account. See [Bank account endpoint](./post-v1-contractors-contractor_uuid-bank_accounts)."}}}}},"required":true}}},"/v1/contractors/{contractor_uuid}/payments":{"get":{"summary":"Get contractor payments","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","required":true,"description":"The UUID of the contractor","schema":{"type":"string"}},{"name":"sort_by","in":"query","required":false,"description":"Sort the results. Format: `field` or `field:direction` where `field` is `check_date` or `created_at` and `direction` is `asc` or `desc`.","example":"check_date:desc","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-contractors-contractor_uuid-payments","security":[{"CompanyAccessAuth":[]}],"description":"Returns a paginated list of payments for a single contractor.\n\nResults are sortable by `check_date` or `created_at`. Append `:asc` or `:desc` to control direction (e.g., `check_date:desc`).\n\nscope: `contractor_pay_stubs:read`","tags":["Contractor Payments"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"A JSON array of contractor payments","content":{"application/json":{"examples":{"success_status":{"value":[{"$ref":"#/components/schemas/Contractor-Payment-Listing/x-examples/success_status"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Contractor-Payment-Listing"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"invalid_sort_by":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_sort_by"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/companies/{company_id}/contractor_payments":{"get":{"summary":"Get contractor payments for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","required":true,"description":"The UUID of the company","schema":{"type":"string"}},{"name":"start_date","in":"query","required":true,"description":"The time period for which to retrieve contractor payments","example":"2020-01-01","schema":{"type":"string"}},{"name":"end_date","in":"query","required":true,"description":"The time period for which to retrieve contractor payments. If left empty, defaults to today's date.","example":"2020-12-31","schema":{"type":"string"}},{"name":"contractor_uuid","in":"query","required":false,"description":"The UUID of the contractor. When specified, will load all payments for that contractor.","schema":{"type":"string"}},{"name":"group_by_date","in":"query","required":false,"description":"Display contractor payments results group by check date if set to true.","schema":{"type":"boolean"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-contractor_payments","security":[{"CompanyAccessAuth":[]}],"description":"Returns an object containing individual contractor payments, within a given time period, including totals.\n\nResults are returned in reverse chronological order (newest first).\n\nscope: `payrolls:read`","tags":["Contractor Payments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"A JSON object containing contractor payments information","content":{"application/json":{"examples":{"by_contractor":{"value":{"$ref":"#/components/schemas/Contractor-Payment-Summary/x-examples/success_status"}},"by_dates":{"value":{"$ref":"#/components/schemas/Contractor-Payment-Summary-By-Dates/x-examples/success_status"}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/Contractor-Payment-Summary"},{"$ref":"#/components/schemas/Contractor-Payment-Summary-By-Dates"}]}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided ID/UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create a contractor payment","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","required":true,"description":"The UUID of the company","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_id-contractor_payments","security":[{"CompanyAccessAuth":[]}],"description":"Pay a contractor. Information needed depends on the contractor's wage type (hourly vs fixed)\n\nscope: `payrolls:run`","tags":["Contractor Payments"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Contractor-Payment/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Contractor-Payment"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided ID/UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"contractor_payment_invalid_wage":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_payment_invalid_wage"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contractor-Payment-Body"}}},"required":true}}},"/v1/companies/{company_id}/contractor_payments/{contractor_payment_id}":{"get":{"summary":"Get a single contractor payment","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","required":true,"description":"The UUID of the company","schema":{"type":"string"}},{"name":"contractor_payment_id","in":"path","required":true,"description":"The UUID of the contractor payment","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-contractor_payment-contractor-payment","security":[{"CompanyAccessAuth":[]}],"description":"Returns a single contractor payment.\n\nscope: `payrolls:read`","tags":["Contractor Payments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Contractor-Payment/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Contractor-Payment"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided ID/UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"delete":{"summary":"Cancel a contractor payment","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","required":true,"description":"The UUID of the company","schema":{"type":"string"}},{"name":"contractor_payment_id","in":"path","required":true,"description":"The UUID of the contractor payment","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-companies-company_id-contractor_payment-contractor-payment","security":[{"CompanyAccessAuth":[]}],"description":"Cancels and deletes a contractor payment. If the contractor payment has already started processing (\"may_cancel\": true), the payment cannot be cancelled.\n\nscope: `payrolls:run`","tags":["Contractor Payments"],"x-gusto-integration-type":["embedded"],"responses":{"204":{"description":"No Content"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided ID/UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"contractor_payment_cannot_cancel":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_payment_cannot_cancel"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/companies/{company_uuid}/contractor_payments/preview":{"get":{"summary":"Preview contractor payment debit date","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","required":true,"description":"The UUID of the company","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-companies-company_uuid-contractor_payments-preview","security":[{"CompanyAccessAuth":[]}],"description":"Returns a debit_date dependent on the ACH payment speed of the company.\n\nIf the payment method is Check or Historical payment, the debit_date will be the same as the check_date.\n\nscope: `payrolls:read`","tags":["Contractor Payments"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Contractor-Payments-Preview/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Contractor-Payments-Preview"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"contractor_payments_preview_no_payments":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_payments_preview_no_payments"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contractor-Payments-Preview-Body"}}},"required":true}}},"/v1/contractor_payments/{contractor_payment_uuid}/receipt":{"get":{"summary":"Get a single contractor payment receipt","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_payment_uuid","in":"path","required":true,"description":"The UUID of the contractor payment","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-contractor_payments-contractor_payment_uuid-receipt","security":[{"CompanyAccessAuth":[]}],"description":"Returns a contractor payment receipt.\n\nNotes:\n* Receipts are only available for direct deposit payments and are only available once those payments have been funded.\n* Payroll Receipt requests for payrolls which do not have receipts available (e.g. payment by check) will return a 404 status.\n* Hour and dollar amounts are returned as string representations of numeric decimals.\n* Dollar amounts are represented to the cent.\n* If no data has yet be inserted for a given field, it defaults to “0.00” (for fixed amounts).\n\nscope: `payrolls:read`","tags":["Contractor Payments"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Contractor-Payment-Receipt/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Contractor-Payment-Receipt"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/contractor_payments/{contractor_payment_uuid}/fund":{"put":{"summary":"Fund a contractor payment [DEMO]","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_payment_uuid","in":"path","required":true,"description":"The UUID of the contractor payment","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-contractor_payments-contractor_payment_uuid-fund","security":[{"CompanyAccessAuth":[]}],"description":"> 🚧 Demo action\n>\n> This action is only available in the Demo environment\n\nSimulate funding a contractor payment. Funding only occurs automatically in the production environment when bank transactions are generated. Use this action in the demo environment to transition a contractor payment's `status` from `Unfunded` to `Funded`. A `Funded` status is required for generating a contractor payment receipt.\n\nscope: `payrolls:run`","tags":["Contractor Payments"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Contractor-Payment/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Contractor-Payment"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"contractor_payment_should_not_be_funded":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_payment_should_not_be_funded"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/contractor_payments/{contractor_payment_id}/pdf":{"get":{"summary":"Get a contractor payment PDF","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_payment_id","in":"path","required":true,"description":"The UUID of the contractor payment","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-contractor_payments-contractor_payment_id-pdf","security":[{"CompanyAccessAuth":[]}],"description":"Get a PDF document for a single contractor payment.\n\nscope: `payrolls:read`","tags":["Contractor Payments"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"A PDF document of the contractor payment"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided ID/UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/contractors/{contractor_uuid}/rehire":{"post":{"summary":"Schedule a contractor rehire","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","required":true,"description":"The UUID of the contractor","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-contractors-contractor_uuid-rehire","security":[{"CompanyAccessAuth":[]}],"description":"## Purpose\nSchedules a contractor rehire for a given date. Creates a new employment record for the contractor.\n\n## Prerequisites\nBefore calling this endpoint:\n1. The contractor must be inactive (previously dismissed)\n2. The contractor must not already have an upcoming employment\n\n## Related webhooks\n- `contractor.reactivated`: Fires when the contractor becomes active again (on or after start_date)\n\nscope: `contractors:write`","tags":["Contractors"],"x-gusto-integration-type":["embedded"],"responses":{"204":{"description":"no content"},"422":{"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","content":{"application/json":{"examples":{"contractor_rehire_start_date_required":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_rehire_start_date_required"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start_date":{"type":"string","format":"date","description":"The rehire date","example":"2025-07-01"}},"required":["start_date"]}}}}},"delete":{"summary":"Cancel a pending contractor rehire","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","required":true,"description":"The UUID of the contractor","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-contractors-contractor_uuid-rehire","security":[{"CompanyAccessAuth":[]}],"description":"## Purpose\nCancels a pending contractor rehire. For future-dated rehires, cancellation is available anytime before the date.\nFor past-dated rehires, cancellation is only available within the 2-day grace period.\n\n## Prerequisites\nBefore calling this endpoint:\n- The contractor must have a pending rehire (upcoming employment)\n\n## Related webhooks\n- `contractor.deactivated`: Fires when the contractor returns to inactive state after cancellation\n\nscope: `contractors:write`","tags":["Contractors"],"x-gusto-integration-type":["embedded"],"responses":{"204":{"description":"no content"},"422":{"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","content":{"application/json":{"examples":{"contractor_rehire_no_pending":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_rehire_no_pending"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/contractors/{contractor_uuid}/termination":{"post":{"summary":"Schedule a contractor termination","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","required":true,"description":"The UUID of the contractor","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-contractors-contractor_uuid-termination","security":[{"CompanyAccessAuth":[]}],"description":"## Purpose\nSchedules a contractor dismissal for a given date. Supports both immediate (past dates) and future-dated dismissals.\n\n## Prerequisites\nBefore calling this endpoint:\n1. The contractor must be active (no existing pending dismissal)\n2. The contractor must have a current employment\n\n## Related webhooks\n- `contractor.deactivated`: Fires when the contractor becomes inactive (on or after end_date)\n\nscope: `contractors:write`","tags":["Contractors"],"x-gusto-integration-type":["embedded"],"responses":{"204":{"description":"no content"},"422":{"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","content":{"application/json":{"examples":{"contractor_termination_end_date_required":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_termination_end_date_required"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"end_date":{"type":"string","format":"date","description":"The date of dismissal","example":"2025-06-15"}},"required":["end_date"]}}}}},"delete":{"summary":"Cancel a pending contractor termination","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","required":true,"description":"The UUID of the contractor","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-contractors-contractor_uuid-termination","security":[{"CompanyAccessAuth":[]}],"description":"## Purpose\nCancels a pending contractor dismissal. For future-dated dismissals, cancellation is available anytime before the date.\nFor past-dated dismissals, cancellation is only available within the 2-day grace period.\n\n## Prerequisites\nBefore calling this endpoint:\n- The contractor must have a pending dismissal (scheduled or within the grace period)\n\n## Related webhooks\n- `contractor.reactivated`: Fires when the contractor becomes active again after cancellation\n\nscope: `contractors:write`","tags":["Contractors"],"x-gusto-integration-type":["embedded"],"responses":{"204":{"description":"no content"},"422":{"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","content":{"application/json":{"examples":{"contractor_termination_no_pending_dismissal":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_termination_no_pending_dismissal"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/contractors/{contractor_uuid}":{"get":{"summary":"Get a contractor","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","description":"The UUID of the contractor","required":true,"schema":{"type":"string"}},{"name":"include","in":"query","explode":false,"required":false,"schema":{"type":"array","items":{"type":"string","enum":["company_name","portal_invitations"],"x-enumDescriptions":{"company_name":"Include the name of the company that the contractor is associated with","portal_invitations":"Include portal invitation status information, including member portal invitation details and partner portal invitation status"}}},"description":"Include the requested attribute(s) in each contractor response. Multiple options are comma separated."}],"x-gusto-rswag":true,"operationId":"get-v1-contractors-contractor_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Get a contractor.\n\nscope: `contractors:read`","tags":["Contractors"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"Individual Contractor":{"value":{"$ref":"#/components/schemas/Contractor/x-examples/Individual%20Contractor"}},"Business Contractor":{"value":{"$ref":"#/components/schemas/Contractor/x-examples/Business%20Contractor"}}},"schema":{"$ref":"#/components/schemas/Contractor"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update a contractor","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","description":"The UUID of the contractor","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-contractors-contractor_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Update a contractor.\n\n> 🚧 Warning\n>\n> Watch out when changing a contractor's type (when the contractor is finished onboarding). Specifically, changing contractor type can be dangerous since Gusto won't recognize and file two separate 1099s if they simply change from business to individual\n\nscope: `contractors:write`","tags":["Contractors"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"Individual Contractor":{"value":{"$ref":"#/components/schemas/Contractor/x-examples/Individual%20Contractor"}},"Business Contractor":{"value":{"$ref":"#/components/schemas/Contractor/x-examples/Business%20Contractor"}}},"schema":{"$ref":"#/components/schemas/Contractor"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"409":{"description":"Conflict","content":{"application/json":{"examples":{"invalid_version":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_version"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"basic":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/basic"}},"resource":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/resource"}},"nested":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/nested"}},"contractor_is_active_pending_dismissal":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_is_active_pending_dismissal"}},"contractor_is_active_pending_dismissal_uncancelable":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_is_active_pending_dismissal_uncancelable"}},"contractor_is_active_pending_rehire":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_is_active_pending_rehire"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contractor-Update-Request-Body"}}},"required":true}},"delete":{"summary":"Delete a contractor","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","description":"The UUID of the contractor","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-contractors-contractor_uuid","security":[{"CompanyAccessAuth":[]}],"description":"A contractor can only be deleted when there are no contractor payments.\n\nscope: `contractors:manage`","tags":["Contractors"],"x-gusto-integration-type":["embedded"],"responses":{"204":{"description":"No Content"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"basic":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/basic"}},"resource":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/resource"}},"nested":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/nested"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/companies/{company_uuid}/contractors":{"get":{"summary":"Get contractors of a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","required":true,"description":"The UUID of the company","schema":{"type":"string"}},{"name":"search_term","in":"query","required":false,"description":"A string to search for in the object's names","schema":{"type":"string"}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","pattern":"^(created_at|type|onboarding_status|name)(:(asc|desc))?(,(created_at|type|onboarding_status|name)(:(asc|desc))?)*$","example":"created_at:asc"},"description":"Sort by one or more fields. Options: created_at, type, onboarding_status, name. Append `:asc` or `:desc` to specify direction (e.g., `created_at:asc`). Defaults to ascending."},{"name":"onboarded","in":"query","required":false,"description":"Filters contractors by those who have completed onboarding","schema":{"type":"boolean"}},{"name":"onboarded_active","in":"query","required":false,"description":"Filters contractors who are ready to work (onboarded AND active today)","schema":{"type":"boolean"}},{"name":"terminated","in":"query","required":false,"description":"Filters contractors by those who have been or are scheduled to be dismissed","schema":{"type":"boolean"}},{"name":"terminated_today","in":"query","required":false,"description":"Filters contractors by those who have been dismissed and whose dismissal is in effect today (excludes active and scheduled to be dismissed)","schema":{"type":"boolean"}},{"name":"include","in":"query","explode":false,"required":false,"schema":{"type":"array","items":{"type":"string","enum":["company_name","portal_invitations"],"x-enumDescriptions":{"company_name":"Include the name of the company that the contractor is associated with","portal_invitations":"Include portal invitation status information, including member portal invitation details and partner portal invitation status"}}},"description":"Include the requested attribute(s) in each contractor response. Multiple options are comma separated."},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_uuid-contractors","security":[{"CompanyAccessAuth":[]}],"description":"Get all contractors, active and inactive, individual and business, for a company.\n\nscope: `contractors:read`","tags":["Contractors"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"Example":{"value":[{"$ref":"#/components/schemas/Contractor/x-examples/Individual%20Contractor"},{"$ref":"#/components/schemas/Contractor/x-examples/Business%20Contractor"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Contractor"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create a contractor","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","required":true,"description":"The UUID of the company","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_uuid-contractors","security":[{"CompanyAccessAuth":[]}],"description":"Create an individual or business contractor.\n\nscope: `contractors:manage`","tags":["Contractors"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"201":{"description":"Successful","content":{"application/json":{"examples":{"Individual Contractor":{"value":{"$ref":"#/components/schemas/Contractor/x-examples/Individual%20Contractor"}},"Business Contractor":{"value":{"$ref":"#/components/schemas/Contractor/x-examples/Business%20Contractor"}}},"schema":{"$ref":"#/components/schemas/Contractor"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"basic":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/basic"}},"resource":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/resource"}},"nested":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/nested"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contractor-Create-Request-Body"}}},"required":true}}},"/v1/contractors/{contractor_uuid}/onboarding_status":{"get":{"summary":"Get the contractor's onboarding status","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","description":"The UUID of the contractor","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-contractors-contractor_uuid-onboarding_status","security":[{"CompanyAccessAuth":[]}],"description":"Retrieves a contractor's onboarding status. The data returned helps inform the required onboarding steps and respective completion status.\n\n## onboarding_status\n\n### Admin-facilitated onboarding\n| onboarding_status | Description |\n|:------------------|------------:|\n| `admin_onboarding_incomplete` | Admin needs to enter basic information about the contractor. |\n| `admin_onboarding_review` | All information has been completed and admin needs to confirm onboarding. |\n| `onboarding_completed` | Contractor has been fully onboarded and verified. |\n\n### Contractor self-onboarding\n\n| onboarding_status | Description |\n| --- | ----------- |\n| `admin_onboarding_incomplete` | Admin needs to enter basic information about the contractor. |\n| `self_onboarding_not_invited` | Admin has the intention to invite the contractor to self-onboard (e.g., marking a checkbox), but the system has not yet sent the invitation. |\n| `self_onboarding_invited` | Contractor has been sent an invitation to self-onboard. |\n| `self_onboarding_started` | Contractor has started the self-onboarding process. |\n| `self_onboarding_review` | Admin needs to review contractors's entered information and confirm onboarding. |\n| `onboarding_completed` | Contractor has been fully onboarded and verified. |\n\n## onboarding_steps\n\n| onboarding_steps | Requirement(s) to be completed |\n|:-----------------|-------------------------------:|\n| `basic_details` | Add individual contractor's first name, last name, social security number or Business name and EIN depending on the contractor type |\n| `add_address` | Add contractor address. |\n| `compensation_details` | Add contractor compensation. |\n| `payment_details` | (optional) Set up contractor's direct deposit or set to check. |\n| `sign_documents` | Contractor forms (e.g., W9) are generated & signed. |\n| `file_new_hire_report` | Contractor new hire report is generated. |\n\nscope: `contractors:read`","tags":["Contractors"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Contractor-Onboarding-Status/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Contractor-Onboarding-Status"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Change the contractor's onboarding status","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","description":"The UUID of the contractor","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-contractors-contractor_uuid-onboarding_status","security":[{"CompanyAccessAuth":[]}],"description":"Updates a contractor's onboarding status.\n\nBelow is a list of valid onboarding status changes depending on the intended action to be performed on behalf of the contractor.\n\n| Action | current onboarding_status | new onboarding_status |\n|:------------------|:------------:|----------:|\n| Mark a contractor as self-onboarding | `admin_onboarding_incomplete` | `self_onboarding_not_invited` |\n| Invite a contractor to self-onboard | `admin_onboarding_incomplete` or `self_onboarding_not_invited` | `self_onboarding_invited` |\n| Cancel a contractor's self-onboarding | `self_onboarding_invited` or `self_onboarding_not_invited` | `admin_onboarding_incomplete` |\n| Review a contractor's self-onboarded info | `self_onboarding_started` | `self_onboarding_review` |\n| Finish a contractor's onboarding | `admin_onboarding_review` or `self_onboarding_review` | `onboarding_completed` |\n\nscope: `contractors:write`","tags":["Contractors"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Contractor-Onboarding-Status/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Contractor-Onboarding-Status"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"contractor_already_onboarded":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_already_onboarded"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contractor-Onboarding-Status-Update-Request-Body"}}},"required":true}}},"/v1/departments/{department_uuid}":{"get":{"summary":"Get a department","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"department_uuid","in":"path","description":"The UUID of the department","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-department","security":[{"CompanyAccessAuth":[]}],"description":"Get a department given the UUID\n\nscope: `departments:read`","tags":["Departments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Department/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Department"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update a department","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"department_uuid","in":"path","description":"The UUID of the department","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-departments","security":[{"CompanyAccessAuth":[]}],"description":"Update a department\n\nscope: `departments:write`","tags":["Departments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Department/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Department"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"409":{"description":"Conflict","content":{"application/json":{"examples":{"invalid_version":{"value":{"$ref":"#/components/schemas/Conflict-Error-Object/x-examples/invalid_version"}}},"schema":{"$ref":"#/components/schemas/Conflict-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"department_duplicate_title":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/department_duplicate_title"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Department-Update-Request-Body"}}},"required":true}},"delete":{"summary":"Delete a department","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"department_uuid","in":"path","description":"The UUID of the department","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-department","security":[{"CompanyAccessAuth":[]}],"description":"Delete a department. You cannot delete a department until all employees and contractors have been removed.\n\nscope: `departments:write`","tags":["Departments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"204":{"description":"No Content"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"department_has_active_members":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/department_has_active_members"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/departments/{department_uuid}/add":{"put":{"summary":"Add people to a department","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"department_uuid","in":"path","description":"The UUID of the department","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-add-people-to-department","security":[{"CompanyAccessAuth":[]}],"description":"Add employees and contractors to a department\n\nscope: `departments:write`","tags":["Departments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Department/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Department"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"department_invalid_employees":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/department_invalid_employees"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Department-People-Request-Body"}}},"required":true}}},"/v1/departments/{department_uuid}/remove":{"put":{"summary":"Remove people from a department","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"department_uuid","in":"path","description":"The UUID of the department","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-remove-people-from-department","security":[{"CompanyAccessAuth":[]}],"description":"Remove employees and contractors from a department\n\nscope: `departments:write`","tags":["Departments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Department/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Department"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"department_invalid_employees":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/department_invalid_employees"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Department-People-Request-Body"}}},"required":true}}},"/v1/companies/{company_uuid}/departments":{"get":{"summary":"Get all departments of a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-companies-departments","security":[{"CompanyAccessAuth":[]}],"description":"Get all of the departments for a given company with the employees and contractors assigned to that department.\n\nscope: `departments:read`","tags":["Departments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Department-List/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Department-List"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create a department","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-departments","security":[{"CompanyAccessAuth":[]}],"description":"Create a department\n\nscope: `departments:write`","tags":["Departments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"example_created":{"value":{"$ref":"#/components/schemas/Department/x-examples/example_created"}}},"schema":{"$ref":"#/components/schemas/Department"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"department_duplicate_title":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/department_duplicate_title"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Department-Create-Request-Body"}}},"required":true}}},"/v1/contractors/{contractor_uuid}/documents":{"get":{"summary":"Get all contractor documents","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","description":"The UUID of the contractor","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-contractor-documents","security":[{"CompanyAccessAuth":[]}],"description":"Get a list of all contractor's documents\n\nscope: `contractor_documents:read`","tags":["Contractor Documents"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":[{"$ref":"#/components/schemas/Document/x-examples/Example"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Document"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/documents/{document_uuid}":{"get":{"summary":"Get a contractor document","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"document_uuid","in":"path","description":"The UUID of the document","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-contractor-document","security":[{"CompanyAccessAuth":[]}],"description":"Get a contractor document.\n\nscope: `contractor_documents:read`","tags":["Contractor Documents"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Document/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Document"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"contractor_document_unsupported_form_type":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_document_unsupported_form_type"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/documents/{document_uuid}/pdf":{"get":{"summary":"Get the contractor document pdf","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"document_uuid","in":"path","description":"The UUID of the document","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-contractor-document-pdf","security":[{"CompanyAccessAuth":[]}],"description":"Get the contractor document pdf.\n\nscope: `contractor_documents:read`","tags":["Contractor Documents"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Document-Pdf/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Document-Pdf"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"contractor_document_unsupported_form_type":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_document_unsupported_form_type"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/documents/{document_uuid}/sign":{"put":{"summary":"Sign a contractor document","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"document_uuid","in":"path","description":"The UUID of the document","required":true,"schema":{"type":"string"}},{"name":"x-gusto-client-ip","in":"header","required":false,"description":"Optional header to supply the IP address. This can be used to supply the IP address for signature endpoints instead of the signed_by_ip_address parameter.","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-contractor-document-sign","security":[{"CompanyAccessAuth":[]}],"description":"Sign a contractor document.\n\nscope: `contractor_documents:write`","tags":["Contractor Documents"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Document-Signed/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Document-Signed"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"contractor_document_sign_missing_agree":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_document_sign_missing_agree"}},"contractor_document_sign_invalid_ip_address":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_document_sign_invalid_ip_address"}},"contractor_document_sign_missing_fields":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_document_sign_missing_fields"}},"contractor_document_sign_already_signed":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_document_sign_already_signed"}},"contractor_document_unsupported_form_type":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/contractor_document_unsupported_form_type"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fields":{"type":"array","description":"List of fields and the values they will be set to.","items":{"type":"object","properties":{"key":{"type":"string","description":"Unique identifier of the field"},"value":{"type":"string","description":"Value for the field"}}}},"agree":{"type":"boolean","description":"Whether you agree to sign electronically"},"signed_by_ip_address":{"type":"string","description":"The IP address of the signatory who signed the form. You must provide the IP address with either this parameter OR you can leave out this parameter and set the IP address in the request header using the `x-gusto-client-ip` header instead."}},"required":["fields","agree"]}}},"required":true}}},"/v1/companies/{company_id}/earning_types":{"get":{"summary":"Get all earning types for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-earning_types","security":[{"CompanyAccessAuth":[]}],"description":"A payroll item in Gusto is associated to an earning type to name the type of earning described by the payroll item.\n\n#### Default Earning Type\nCertain earning types are special because they have tax considerations. Those earning types are mostly the same for every company depending on its legal structure (LLC, Corporation, etc.)\n\n#### Custom Earning Type\nCustom earning types are all the other earning types added specifically for a company.\n\nscope: `payrolls:read`","tags":["Earning Types"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"success":{"value":{"$ref":"#/components/schemas/Earning-Type-List/x-examples/success"}}},"schema":{"$ref":"#/components/schemas/Earning-Type-List"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create a custom earning type","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_id-earning_types","security":[{"CompanyAccessAuth":[]}],"description":"Create a custom earning type.\n\nIf an inactive earning type exists with the same name, this will reactivate it instead of creating a new one.\n\nscope: `payrolls:write`","tags":["Earning Types"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"201":{"description":"Success","content":{"application/json":{"examples":{"custom_earning_type":{"value":{"$ref":"#/components/schemas/Earning-Type/x-examples/custom_earning_type"}}},"schema":{"$ref":"#/components/schemas/Earning-Type"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"earning_type_missing_name":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/earning_type_missing_name"}},"earning_type_duplicate_name":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/earning_type_duplicate_name"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","default":"Gym Membership","description":"The name of the custom earning type."}}}}},"required":true}}},"/v1/companies/{company_id}/earning_types/{earning_type_uuid}":{"put":{"summary":"Update an earning type","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"earning_type_uuid","in":"path","description":"The UUID of the earning type","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-companies-company_id-earning_types-earning_type_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Update an earning type.\n\nscope: `payrolls:write`","tags":["Earning Types"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"success":{"value":{"$ref":"#/components/schemas/Earning-Type/x-examples/success"}}},"schema":{"$ref":"#/components/schemas/Earning-Type"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"earning_type_duplicate_name":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/earning_type_duplicate_name"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The name of the custom earning type."}}}}},"required":true}},"delete":{"summary":"Deactivate an earning type","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"earning_type_uuid","in":"path","description":"The UUID of the earning type","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-companies-company_id-earning_types-earning_type_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Deactivate an earning type.\n\nscope: `payrolls:write`","tags":["Earning Types"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"204":{"description":"No Content"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/employees/{employee_id}/bank_accounts":{"get":{"summary":"List employee bank accounts","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_id-bank_accounts","security":[{"CompanyAccessAuth":[]}],"description":"Returns all employee bank accounts.\n\nscope: `employee_payment_methods:read`","tags":["Employee Payment Method"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":[{"$ref":"#/components/schemas/Employee-Bank-Account/x-examples/Example"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Employee-Bank-Account"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create an employee bank account","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-employees-employee_id-bank_accounts","security":[{"CompanyAccessAuth":[]}],"description":"Creates an employee bank account. An employee can have multiple bank accounts. Note that creating an employee bank account will also update the employee's payment method.\n\nscope: `employee_payment_methods:write`","tags":["Employee Payment Method"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Employee-Bank-Account/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Employee-Bank-Account"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"employee_bank_account_missing_name":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/employee_bank_account_missing_name"}},"employee_bank_account_invalid_account_number":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/employee_bank_account_invalid_account_number"}},"employee_bank_account_duplicate":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/employee_bank_account_duplicate"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Employee-Bank-Account-Request"}}},"required":true}}},"/v1/employees/{employee_id}/bank_accounts/{bank_account_uuid}":{"put":{"summary":"Update an employee bank account","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}},{"name":"bank_account_uuid","in":"path","description":"The UUID of the bank account","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-employees-employee_id-bank_accounts","security":[{"CompanyAccessAuth":[]}],"description":"Updates an employee bank account.\n\nscope: `employee_payment_methods:write`","tags":["Employee Payment Method"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Employee-Bank-Account/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Employee-Bank-Account"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"employee_bank_account_invalid_account_number":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/employee_bank_account_invalid_account_number"}},"employee_bank_account_invalid_routing_on_update":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/employee_bank_account_invalid_routing_on_update"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Employee-Bank-Account-Request"}}},"required":true}},"delete":{"summary":"Delete an employee bank account","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}},{"name":"bank_account_uuid","in":"path","description":"The UUID of the bank account","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-employees-employee_id-bank_accounts-bank_account_id","security":[{"CompanyAccessAuth":[]}],"description":"Deletes an employee bank account. To update an employee's bank account details, delete the bank account first and create a new one.\n\nscope: `employee_payment_methods:write`","tags":["Employee Payment Method"],"x-gusto-integration-type":["embedded"],"responses":{"204":{"description":"No Content"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"employee_bank_account_destroy_invalid":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/employee_bank_account_destroy_invalid"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/employees/{employee_id}/employee_benefits":{"get":{"summary":"Get all benefits for an employee","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}},{"name":"include","in":"query","required":false,"schema":{"type":"string","enum":["all_benefits"]},"description":"Available options:\n- all_benefits: Include all effective dated benefits for each employee instead of only the current benefits."}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_id-employee_benefits","security":[{"CompanyAccessAuth":[]}],"description":"Employee benefits represent an employee enrolled in a particular company benefit. It includes information specific to that employee’s enrollment.\n\nReturns an array of all employee benefits for this employee\n\nBenefits containing PHI are only visible to applications with the `employee_benefits:read:phi` scope.\n\nscope: `employee_benefits:read`","tags":["Employee Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":[{"$ref":"#/components/schemas/Employee-Benefit/x-examples/Example"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Employee-Benefit"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create an employee benefit","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-employees-employee_id-employee_benefits","security":[{"CompanyAccessAuth":[]}],"description":"Employee benefits represent an employee enrolled in a particular company benefit. It includes information specific to that employee's enrollment.\n\nWhen the application has the `employee_benefits:write:benefit_type_limited` data scope, the application can only create employee benefits for benefit types that are permitted for the application.\n\nscope: `employee_benefits:write`","tags":["Employee Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"201":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Employee-Benefit/x-examples/Example"}},"Tiered Example":{"value":{"$ref":"#/components/schemas/Employee-Benefit/x-examples/Tiered%20Example"}}},"schema":{"$ref":"#/components/schemas/Employee-Benefit"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"employee_benefit_negative_company_contribution":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/employee_benefit_negative_company_contribution"}},"employee_benefit_active_requires_contribution_or_deduction":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/employee_benefit_active_requires_contribution_or_deduction"}},"employee_benefit_invalid_effective_date":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/employee_benefit_invalid_effective_date"}},"employee_benefit_simple_ira_elective_mismatch":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/employee_benefit_simple_ira_elective_mismatch"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Employee-Benefit-Create-Request"}}},"required":true}}},"/v1/employee_benefits/{employee_benefit_id}":{"get":{"summary":"Get an employee benefit","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_benefit_id","in":"path","description":"The UUID of the employee benefit.","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-employee_benefits-employee_benefit_id","security":[{"CompanyAccessAuth":[]}],"description":"Employee benefits represent an employee enrolled in a particular company benefit. It includes information specific to that employee’s enrollment.\n\nBenefits containing PHI are only visible to applications with the `employee_benefits:read:phi` scope.\n\nscope: `employee_benefits:read`","tags":["Employee Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Employee-Benefit/x-examples/Example"}},"Tiered Example":{"value":{"$ref":"#/components/schemas/Employee-Benefit/x-examples/Tiered%20Example"}}},"schema":{"$ref":"#/components/schemas/Employee-Benefit"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update an employee benefit","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_benefit_id","in":"path","description":"The UUID of the employee benefit.","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-employee_benefits-employee_benefit_id","security":[{"CompanyAccessAuth":[]}],"description":"Employee benefits represent an employee enrolled in a particular company benefit. It includes information specific to that employee's enrollment.\n\nWhen the application has the `employee_benefits:write:benefit_type_limited` data scope, the application can only update employee benefits for benefit types that are permitted for the application.\n\nscope: `employee_benefits:write`","tags":["Employee Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Employee-Benefit/x-examples/Example"}},"Tiered Example":{"value":{"$ref":"#/components/schemas/Employee-Benefit/x-examples/Tiered%20Example"}}},"schema":{"$ref":"#/components/schemas/Employee-Benefit"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"employee_benefit_negative_company_contribution":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/employee_benefit_negative_company_contribution"}},"employee_benefit_active_requires_contribution_or_deduction":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/employee_benefit_active_requires_contribution_or_deduction"}},"employee_benefit_coverage_amount_only_for_gtl":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/employee_benefit_coverage_amount_only_for_gtl"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Employee-Benefit-Update-Request"}}},"required":true}},"delete":{"summary":"Delete an employee benefit","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_benefit_id","in":"path","description":"The UUID of the employee benefit.","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-employee_benefits-employee_benefit_id","security":[{"CompanyAccessAuth":[]}],"description":"Employee benefits represent an employee enrolled in a particular company benefit. It includes information specific to that employee's enrollment.\n\nWhen the application has the `employee_benefits:write:benefit_type_limited` data scope, the application can only delete employee benefits for benefit types that are permitted for the application.\n\nscope: `employee_benefits:write`","tags":["Employee Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"204":{"description":"No Content"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"employee_benefit_destroy_invalid":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/employee_benefit_destroy_invalid"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/employees/{employee_id}/custom_fields":{"get":{"summary":"Get an employee's custom fields","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_id-custom_fields","security":[{"CompanyAccessAuth":[]}],"description":"Returns a list of the employee's custom fields.\n\nscope: `employees:read`","tags":["Employees"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Employee-Custom-Field-List/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Employee-Custom-Field-List"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/employees/{employee_uuid}/federal_taxes":{"get":{"summary":"Get federal taxes for an employee","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_uuid","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_id-federal_taxes","security":[{"CompanyAccessAuth":[]}],"description":"Returns federal tax information for an employee. The response structure varies based on the w4_data_type (pre_2020_w4 or rev_2020_w4).\n\nscope: `employee_federal_taxes:read`","tags":["Employee Tax Setup"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"rev_2020_w4":{"value":{"$ref":"#/components/schemas/Employee-Federal-Tax/x-examples/rev_2020_w4"}}},"schema":{"$ref":"#/components/schemas/Employee-Federal-Tax"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update federal taxes for an employee","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_uuid","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-employees-employee_id-federal_taxes","security":[{"CompanyAccessAuth":[]}],"description":"Updates federal tax (W4) information for an employee. Only rev_2020_w4 format is accepted for updates.\n\nscope: `employee_federal_taxes:write`","tags":["Employee Tax Setup"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"rev_2020_w4_married_two_jobs":{"value":{"$ref":"#/components/schemas/Employee-Federal-Tax/x-examples/rev_2020_w4_married_two_jobs"}}},"schema":{"$ref":"#/components/schemas/Employee-Federal-Tax"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"409":{"description":"Conflict","content":{"application/json":{"examples":{"invalid_version":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_version"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["version","w4_data_type","filing_status"],"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.","example":"56a489ce86ed6c1b0f0cecc4050a0b01"},"w4_data_type":{"type":"string","enum":["rev_2020_w4"],"description":"The version of the W4 form. Only rev_2020_w4 is accepted for updates."},"filing_status":{"type":"string","enum":["Single","Married","Head of Household","Exempt from withholding"],"description":"Determines which tax return form an individual will use. One of: Single, Married, Head of Household, Exempt from withholding.","example":"Single"},"two_jobs":{"type":"boolean","description":"If there are only two jobs (e.g., you and your spouse each have a job), set to true."},"dependents_amount":{"type":"number","description":"Amount for dependents; a dependent entitles the taxpayer to claim a dependency exemption."},"other_income":{"type":"number","description":"Other income amount."},"deductions":{"type":"number","description":"Deductions other than the standard deduction to reduce withholding."},"extra_withholding":{"type":"number","description":"Additional amount to be withheld from each paycheck."},"federal_withholding_allowance":{"type":"integer","description":"Only applicable when w4_data_type is 'pre_2020_w4' (pre-2020 W4 forms are deprecated for updates)."},"additional_withholding":{"type":"number","description":"Only applicable when w4_data_type is 'pre_2020_w4' (pre-2020 W4 forms are deprecated for updates)."}}}}},"required":true}}},"/v1/employees/{employee_id}/forms":{"get":{"summary":"Get all employee forms","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-employee-forms","security":[{"CompanyAccessAuth":[]}],"description":"Get a list of all employee's forms\n\nscope: `employee_forms:read`","tags":["Employee Forms"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"employee_form":{"value":[{"$ref":"#/components/schemas/Form/x-examples/employee_form"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Form"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/employees/{employee_id}/forms/{form_id}":{"get":{"summary":"Get an employee form","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}},{"name":"form_id","in":"path","description":"The UUID of the form","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-employee-form","security":[{"CompanyAccessAuth":[]}],"description":"Get an employee form\n\nscope: `employee_forms:read`","tags":["Employee Forms"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"employee_form":{"value":{"$ref":"#/components/schemas/Form/x-examples/employee_form"}}},"schema":{"$ref":"#/components/schemas/Form"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/employees/{employee_id}/forms/{form_id}/pdf":{"get":{"summary":"Get the employee form pdf","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}},{"name":"form_id","in":"path","description":"The UUID of the form","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-employee-form-pdf","security":[{"CompanyAccessAuth":[]}],"description":"Get the link to the employee form PDF\n\nscope: `employee_forms:read`","tags":["Employee Forms"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Form-Pdf/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Form-Pdf"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/employees/{employee_id}/forms/{form_id}/sign":{"put":{"summary":"Sign an employee form","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}},{"name":"form_id","in":"path","description":"The UUID of the form","required":true,"schema":{"type":"string"}},{"name":"x-gusto-client-ip","in":"header","required":false,"description":"Optional header to supply the IP address. This can be used to supply the IP address for signature endpoints instead of the signed_by_ip_address parameter.","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-employee-form-sign","security":[{"CompanyAccessAuth":[]}],"description":"Sign an employee form.\n\nThe optional preparer attributes are only valid for I-9 form. When a preparer is used, the\nfirst name, last name, street address, city, state, and zip for that preparer are all required.\n\nscope: `employee_forms:sign`","tags":["Employee Forms"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"employee_form":{"value":{"$ref":"#/components/schemas/Form/x-examples/employee_form"}}},"schema":{"$ref":"#/components/schemas/Form"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"form_already_signed":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/form_already_signed"}},"form_no_signature_required":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/form_no_signature_required"}},"form_invalid_ip_address":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/form_invalid_ip_address"}},"form_preparer_not_supported":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/form_preparer_not_supported"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signature_text":{"type":"string","description":"The signature"},"agree":{"type":"boolean","description":"Whether you agree to sign electronically"},"signed_by_ip_address":{"type":"string","description":"The IP address of the signatory who signed the form. Both IPv4 AND IPv6 are supported. You must provide the IP address with either this parameter OR you can leave out this parameter and set the IP address in the request header using the `x-gusto-client-ip` header instead."},"preparer":{"type":"boolean","description":"Whether there is a preparer"},"preparer_first_name":{"type":"string"},"preparer_last_name":{"type":"string"},"preparer_street_1":{"type":"string"},"preparer_street_2":{"type":"string"},"preparer_city":{"type":"string"},"preparer_state":{"type":"string"},"preparer_zip":{"type":"string"},"preparer_agree":{"type":"string","description":"Whether preparer agrees to sign electronically"},"preparer2":{"type":"boolean","description":"Whether there is a 2nd preparer"},"preparer2_first_name":{"type":"string"},"preparer2_last_name":{"type":"string"},"preparer2_street_1":{"type":"string"},"preparer2_street_2":{"type":"string"},"preparer2_city":{"type":"string"},"preparer2_state":{"type":"string"},"preparer2_zip":{"type":"string"},"preparer2_agree":{"type":"string","description":"Whether 2nd preparer agrees to sign electronically"},"preparer3":{"type":"boolean","description":"Whether there is a 3rd preparer"},"preparer3_first_name":{"type":"string"},"preparer3_last_name":{"type":"string"},"preparer3_street_1":{"type":"string"},"preparer3_street_2":{"type":"string"},"preparer3_city":{"type":"string"},"preparer3_state":{"type":"string"},"preparer3_zip":{"type":"string"},"preparer3_agree":{"type":"string","description":"Whether 3rd preparer agrees to sign electronically"},"preparer4":{"type":"boolean","description":"Whether there is a 4th preparer"},"preparer4_first_name":{"type":"string"},"preparer4_last_name":{"type":"string"},"preparer4_street_1":{"type":"string"},"preparer4_street_2":{"type":"string"},"preparer4_city":{"type":"string"},"preparer4_state":{"type":"string"},"preparer4_zip":{"type":"string"},"preparer4_agree":{"type":"string","description":"Whether 4th preparer agrees to sign electronically"}},"required":["signature_text","agree"]}}},"required":true}}},"/v1/companies/{company_id}/employees/payment_details":{"get":{"summary":"Get employee payment details for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"employee_uuid","in":"query","required":false,"description":"The UUID of a specific employee to fetch payment details for.","schema":{"type":"string"}},{"name":"payroll_uuid","in":"query","required":false,"description":"The UUID of a specific payroll to fetch payment details for employees on that payroll.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-employees-payment_details","security":[{"CompanyAccessAuth":[]}],"description":"Fetches payment details for employees in a given company. Results are paginated.\n\nUse the `employee_uuid` query parameter to filter for a single employee.\nUse the `payroll_uuid` query parameter to filter for employees on a specific payroll.\nProviding both `employee_uuid` and `payroll_uuid` will result in a 422 error.\nAn empty array is returned if the company has no employees or if no employees match the filter criteria.\n\nThe `encrypted_account_number` in the `splits` array is only visible if the `employee_payment_methods:read:account_number` scope is present.\n\nscope: `employee_payment_methods:read`","tags":["Employees"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"A list of employee payment details.","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee-Payment-Details-List/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee-Payment-Details-List"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"employee_payment_details_invalid_filter_combination":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/employee_payment_details_invalid_filter_combination"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/employees/{employee_id}/payment_method":{"get":{"summary":"Get payment method for an employee","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_id-payment_method","security":[{"CompanyAccessAuth":[]}],"description":"Returns the payment method for an employee (e.g. Check or Direct Deposit with split configuration).\n\nscope: `employee_payment_methods:read`","tags":["Employee Payment Method"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"direct_deposit_percentage":{"value":{"$ref":"#/components/schemas/Employee-Payment-Method/x-examples/direct_deposit_percentage"}}},"schema":{"$ref":"#/components/schemas/Employee-Payment-Method"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update payment method for an employee","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-employees-employee_id-payment_method","security":[{"CompanyAccessAuth":[]}],"description":"Updates the payment method for an employee. Can set to Check or Direct Deposit with split configuration.\n\nscope: `employee_payment_methods:write`","tags":["Employee Payment Method"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"direct_deposit_percentage":{"value":{"$ref":"#/components/schemas/Employee-Payment-Method/x-examples/direct_deposit_percentage"}}},"schema":{"$ref":"#/components/schemas/Employee-Payment-Method"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"409":{"description":"Conflict","content":{"application/json":{"examples":{"invalid_version":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_version"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["version","type"],"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.","example":"63859768485e218ccf8a449bb60f14ed"},"type":{"type":"string","enum":["Check","Direct Deposit"],"description":"The payment method type. If type is Check, split_by and splits do not need to be populated. If type is Direct Deposit, split_by and splits are required."},"split_by":{"anyOf":[{"type":"string","enum":["Percentage","Amount"]},{"type":"null"}],"description":"How the payment will be split. If Percentage, split amounts must add up to exactly 100. If Amount, values are in cents and the last split amount must be null to capture the remainder."},"splits":{"type":["array","null"],"description":"Array of payment splits. Required when type is Direct Deposit.","items":{"type":"object","properties":{"uuid":{"type":"string","description":"The bank account UUID."},"name":{"type":"string","description":"The bank account name."},"priority":{"type":"integer","description":"Order of priority for each payment split; priority 1 is the first account paid. Must be unique and sequential."},"split_amount":{"type":["number","null"],"description":"If split_by is Amount, value is in cents (e.g., 500 for $5.00) and exactly one account must have null to capture the remainder. If split_by is Percentage, value is the percentage (e.g., 60 for 60%)."}}}}}}}},"required":true}}},"/v1/employees/{employee_id}/rehire":{"get":{"summary":"Get an employee rehire","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_id-rehire","security":[{"CompanyAccessAuth":[]}],"description":"Retrieve an employee's rehire, which contains information on when the employee returns to work.\n\nscope: `employments:read`","tags":["Employee Employments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Rehire/x-examples/example"}},"active_rehire":{"value":{"$ref":"#/components/schemas/Rehire/x-examples/active_rehire"}}},"schema":{"$ref":"#/components/schemas/Rehire"}}}},"204":{"description":"No Content"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create an employee rehire","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-employees-employee_id-rehire","security":[{"CompanyAccessAuth":[]}],"description":"Rehire is created whenever an employee is scheduled to return to the company.\n\nscope: `employments:write`","tags":["Employee Employments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"created":{"value":{"$ref":"#/components/schemas/Rehire/x-examples/created"}}},"schema":{"$ref":"#/components/schemas/Rehire"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"rehire_not_terminated":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/rehire_not_terminated"}},"rehire_missing_required_fields":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/rehire_missing_required_fields"}},"rehire_invalid_work_location":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/rehire_invalid_work_location"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rehire-Body"}}},"required":true}},"put":{"summary":"Update an employee rehire","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-employees-employee_id-rehire","security":[{"CompanyAccessAuth":[]}],"description":"Update an employee's rehire.\n\nscope: `employments:write`","tags":["Employee Employments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"created":{"value":{"$ref":"#/components/schemas/Rehire/x-examples/created"}}},"schema":{"$ref":"#/components/schemas/Rehire"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"rehire_no_future_employment":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/rehire_no_future_employment"}},"rehire_missing_required_fields":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/rehire_missing_required_fields"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rehire-Update-Request-Body"}}},"required":true}},"delete":{"summary":"Delete an employee rehire","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-employees-employee_id-rehire","security":[{"CompanyAccessAuth":[]}],"description":"Delete an employee rehire. An employee rehire cannot be deleted if it's active (past effective date).\n\nscope: `employments:write`","tags":["Employee Employments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"204":{"description":"No Content"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"rehire_delete_already_effective":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/rehire_delete_already_effective"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/employees/{employee_uuid}/section603_high_earner_statuses":{"get":{"summary":"Get all Section 603 high earner statuses for an employee","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_uuid","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_uuid-section603_high_earner_statuses","security":[{"CompanyAccessAuth":[]}],"description":"Get all Section 603 high earner statuses for an employee across all years.\n\nSection 603 of the SECURE 2.0 Act applies to employees aged 50 or older whose prior-year FICA wages exceed the IRS threshold.\nThese employees are classified as high earners, and their catch-up contributions to pre-tax retirement benefits must be designated as post-tax contributions.\n\nscope: `employee_benefits:read`","tags":["Employee Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful - with records","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee-Section603-High-Earner-Status-List/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee-Section603-High-Earner-Status-List"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create a Section 603 high earner status","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_uuid","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-employees-employee_uuid-section603_high_earner_statuses","security":[{"CompanyAccessAuth":[]}],"description":"Create a Section 603 high earner status for an employee for a specific year.\n\nSection 603 of the SECURE 2.0 Act applies to employees aged 50 or older whose prior-year FICA wages exceed the IRS threshold.\nThese employees are classified as high earners, and their catch-up contributions to pre-tax retirement benefits must be designated as post-tax contributions.\n\nscope: `employee_benefits:write`","tags":["Employee Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"201":{"description":"created","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee-Section603-High-Earner-Status/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee-Section603-High-Earner-Status"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"409":{"description":"conflict - record already exists","content":{"application/json":{"examples":{"conflict":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/conflict"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}},"422":{"description":"unprocessable entity - invalid is_high_earner","content":{"application/json":{"examples":{"invalid_parameter":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_parameter"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Employee-Section603-High-Earner-Status-Create-Request"}}},"required":true}}},"/v1/employees/{employee_uuid}/section603_high_earner_statuses/{effective_year}":{"get":{"summary":"Get a Section 603 high earner status for a specific year","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_uuid","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}},{"name":"effective_year","in":"path","description":"The effective year for the Section 603 status","required":true,"schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_uuid-section603_high_earner_statuses-effective_year","security":[{"CompanyAccessAuth":[]}],"description":"Get a Section 603 high earner status for an employee for a specific year.\n\nSection 603 of the SECURE 2.0 Act applies to employees aged 50 or older whose prior-year FICA wages exceed the IRS threshold.\nThese employees are classified as high earners, and their catch-up contributions to pre-tax retirement benefits must be designated as post-tax contributions.\n\nscope: `employee_benefits:read`","tags":["Employee Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee-Section603-High-Earner-Status/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee-Section603-High-Earner-Status"}}}},"404":{"description":"Not Found - employee does not exist","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"unprocessable entity - invalid effective_year","content":{"application/json":{"examples":{"invalid_parameter":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_parameter"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}},"patch":{"summary":"Update a Section 603 high earner status","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_uuid","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}},{"name":"effective_year","in":"path","description":"The effective year for the Section 603 status","required":true,"schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"patch-v1-employees-employee_uuid-section603_high_earner_statuses-effective_year","security":[{"CompanyAccessAuth":[]}],"description":"Update a Section 603 high earner status for an employee for a specific year.\n\nSection 603 of the SECURE 2.0 Act applies to employees aged 50 or older whose prior-year FICA wages exceed the IRS threshold.\nThese employees are classified as high earners, and their catch-up contributions to pre-tax retirement benefits must be designated as post-tax contributions.\n\nscope: `employee_benefits:write`","tags":["Employee Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee-Section603-High-Earner-Status/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee-Section603-High-Earner-Status"}}}},"404":{"description":"Not Found - employee does not exist","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"unprocessable entity - invalid is_high_earner","content":{"application/json":{"examples":{"invalid_parameter":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_parameter"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Employee-Section603-High-Earner-Status-Update-Request"}}},"required":true}}},"/v1/employees/{employee_uuid}/state_taxes":{"get":{"summary":"Get an employee's state taxes","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_uuid","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_id-state_taxes","security":[{"CompanyAccessAuth":[]}],"description":"Get attributes relevant for an employee's state taxes.\n\nThe data required to correctly calculate an employee's state taxes varies by both home and work location. This API returns information about each question that must be answered grouped by state. Mostly commonly, an employee lives and works in the same state and will only have questions for a single state. The response contains metadata about each question, the type of answer expected, and the current answer stored in Gusto for that question.\n\nAnswers are represented by an array. Today, this array can only be empty or contain exactly one element, but is designed to allow for forward compatibility with effective-dated fields. The `valid_from` and `valid_up_to` fields are optional and currently ignored.\n\n## About filing new hire reports\nPayroll Admins are responsible for filing a new hire report for each Employee. The `file_new_hire_report` question will only be listed if:\n- the `employee.onboarding_status` is one of the following:\n  - `admin_onboarding_incomplete`\n  - `self_onboarding_awaiting_admin_review`\n- that employee's work state requires filing a new hire report\n\nscope: `employee_state_taxes:read`","tags":["Employee Tax Setup"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee-State-Taxes-List/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee-State-Taxes-List"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update an employee's state taxes","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_uuid","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-employees-employee_id-state_taxes","security":[{"CompanyAccessAuth":[]}],"description":"Update attributes relevant for an employee's state taxes.\n\nAs described for the GET endpoint, the answers must be supplied in the effective-dated format, but currently only a single answer will be accepted. The `valid_from` and `valid_up_to` fields are optional and currently ignored.\n\nscope: `employee_state_taxes:write`","tags":["Employee Tax Setup"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee-State-Taxes-List/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee-State-Taxes-List"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Employee-State-Taxes-Request"}}},"required":true}}},"/v1/employees/{employee_uuid}/time_off_activities":{"get":{"summary":"Get employee time off activities","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_uuid","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}},{"name":"time_off_type","in":"query","required":true,"description":"The time off type name you want to query data for. ex: 'sick' or 'vacation'","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-version-employees-time_off_activities","security":[{"CompanyAccessAuth":[]}],"description":"Get employee time off activities.\n\nscope: `employee_time_off_activities:read`","tags":["Employees"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Time-Off-Activity-List/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Time-Off-Activity-List"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"time_off_activity_invalid_type":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/time_off_activity_invalid_type"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/companies/{company_id}/reports/employees_annual_fica_wage":{"post":{"summary":"Create an employees annual FICA wage report","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","required":true,"description":"The UUID of the company","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_id-reports-employees_annual_fica_wage","security":[{"CompanyAccessAuth":[]}],"description":"Generates a report containing annual FICA (Federal Insurance Contributions Act) wage data for all employees in a company over a specified year range.\n\nThis report provides detailed wage information subject to Social Security and Medicare taxes, useful for benefits integrations that need to verify employee earnings for compliance and benefit calculations.\n\nThe report is generated asynchronously. After making this request, you will receive a `request_uuid` which can be used to poll the [Get a report](ref:get-v1-reports-request_uuid) endpoint to check the status and retrieve the report when complete.\n\nscope: `company_reports:write`","tags":["Reports"],"x-gusto-integration-type":["embedded"],"responses":{"202":{"description":"accepted","content":{"application/json":{"examples":{"accepted":{"value":{"$ref":"#/components/schemas/Employees-Annual-Fica-Wage-Report-Acceptance/x-examples/accepted"}}},"schema":{"$ref":"#/components/schemas/Employees-Annual-Fica-Wage-Report-Acceptance"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"unprocessable entity - start year before minimum","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["start_year","end_year"],"properties":{"start_year":{"type":"integer","description":"The start year for the report (must be 2011 or later)","example":2023},"end_year":{"type":"integer","description":"The end year for the report (must be the current year or earlier, and must be >= start_year)","example":2024}}}}},"required":true}}},"/v1/employees/{employee_id}":{"get":{"summary":"Get an employee","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}},{"name":"include","in":"query","explode":false,"required":false,"schema":{"type":"array","items":{"type":"string","enum":["all_compensations","all_home_addresses","company_name","current_home_address","custom_fields","portal_invitations"],"x-enumDescriptions":{"all_compensations":"Include all effective dated compensations for each job instead of only the current compensation. Requires `compensations:read` scope.","all_home_addresses":"Include all home addresses that have been associated to this employee","company_name":"Include the name of the company that the employee is associated with","current_home_address":"Include the employee's current home address","custom_fields":"Include employees' custom fields","portal_invitations":"Include portal invitation status information, including member portal invitation details and partner portal invitation status"}}},"description":"Include the requested attribute(s) in each employee response. Multiple options are comma separated."}],"x-gusto-rswag":true,"operationId":"get-v1-employees","security":[{"CompanyAccessAuth":[]}],"description":"Get an employee.\n\nNote: Compensation data (pay rate, payment unit, and related fields) represents sensitive employee pay information. When retrieving employee job data, these fields (`rate`, `payment_unit`, `current_compensation_uuid`, `compensations`) are only returned when the `compensations:read` scope is included. This allows you to access employee and job metadata without exposing pay rates.\n\nscope: `employees:read`","tags":["Employees"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update an employee.","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-employees","security":[{"CompanyAccessAuth":[]}],"description":"Update an employee.\n\nscope: `employees:write`","tags":["Employees"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"409":{"description":"invalid version","content":{"application/json":{"examples":{"invalid_version":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_version"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}},"422":{"description":"invalid attributes","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Versionable-Required"},{"type":"object","properties":{"first_name":{"type":"string","example":"Weezy"},"middle_initial":{"type":["string","null"],"example":"F"},"last_name":{"type":"string","example":"Baby"},"email":{"type":"string","example":"tunechi@cashmoneyrecords.com"},"work_email":{"type":"string","example":"new.partner.work@example.com"},"date_of_birth":{"type":"string","example":"1991-01-31"},"ssn":{"type":"string","pattern":"[0-9]{9}","example":"824920233"},"preferred_first_name":{"type":["string","null"]},"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."}}}]}}},"required":true}},"delete":{"summary":"Delete an onboarding employee","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-employee","security":[{"CompanyAccessAuth":[]}],"description":"Use this endpoint to delete an employee who is in onboarding. Deleting\nan onboarded employee is not allowed and will return a 422 response. Please check out the Terminations api\nif you need to terminate an onboarded employee.\n\nscope: `employees:manage`","tags":["Employees"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"204":{"description":"successful"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"cannot delete onboarded employee","content":{"application/json":{"examples":{"onboarded_employee":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/onboarded_employee"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/companies/{company_id}/employees":{"get":{"summary":"Get employees of a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","required":true,"description":"The UUID of the company","schema":{"type":"string"}},{"name":"location_uuid","in":"query","required":false,"description":"Filter employees by a specific primary work location","schema":{"type":"string"}},{"name":"payroll_uuid","in":"query","required":false,"description":"Filter employees by a specific payroll","schema":{"type":"string"}},{"name":"search_term","in":"query","required":false,"description":"A string to search for in the object's names","schema":{"type":"string"}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","pattern":"^(created_at|name|onboarding_status)(:(asc|desc))?(,(created_at|name|onboarding_status)(:(asc|desc))?)*$","example":"created_at:asc"},"description":"Sort employees by a given field. Cannot be used with search_term. Append `:asc` or `:desc` to specify direction (e.g., `name:desc`). Defaults to ascending."},{"name":"include","in":"query","explode":false,"required":false,"schema":{"type":"array","items":{"type":"string","enum":["all_compensations","all_home_addresses","company_name","current_home_address","custom_fields","portal_invitations"],"x-enumDescriptions":{"all_compensations":"Include all effective dated compensations for each job instead of only the current compensation. Requires `compensations:read` scope.","all_home_addresses":"Include all home addresses that have been associated to this employee","company_name":"Include the name of the company that the employee is associated with","current_home_address":"Include the employee's current home address","custom_fields":"Include employees' custom fields","portal_invitations":"Include portal invitation status information, including member portal invitation details and partner portal invitation status"}}},"description":"Include the requested attribute(s) in each employee response. Multiple options are comma separated."},{"name":"onboarded","in":"query","required":false,"description":"Filters employees by those who have completed onboarding","schema":{"type":"boolean"}},{"name":"onboarded_active","in":"query","required":false,"description":"Filters employees who are ready to work (onboarded AND active today)","schema":{"type":"boolean"}},{"name":"terminated","in":"query","required":false,"description":"Filters employees by those who have been or are scheduled to be terminated","schema":{"type":"boolean"}},{"name":"terminated_today","in":"query","required":false,"description":"Filters employees by those who have been terminated and whose termination is in effect today (excludes active and scheduled to be terminated)","schema":{"type":"boolean"}},{"name":"uuids","in":"query","explode":false,"schema":{"type":"array","items":{"type":"string"}},"required":false,"description":"Optional subset of employees to fetch."},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-employees","security":[{"CompanyAccessAuth":[]}],"description":"Get all of the employees, onboarding, active and terminated, for a given company.\n\nNote: Compensation data (pay rate, payment unit, and related fields) represents sensitive employee pay information. When retrieving employee job data, these fields (`rate`, `payment_unit`, `current_compensation_uuid`, `compensations`) are only returned when the `compensations:read` scope is included. This allows you to access employee and job metadata without exposing pay rates.\n\nscope: `employees:read`","tags":["Employees"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Show-Employees/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Show-Employees"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create an employee","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","required":true,"description":"Company ID","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-employees","security":[{"CompanyAccessAuth":[]}],"description":"Create an employee.\n\nscope: `employees:manage`","tags":["Employees"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"201":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"invalid attributes","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}},"employee_create_self_onboarding_missing_email":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/employee_create_self_onboarding_missing_email"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["first_name","last_name"],"properties":{"first_name":{"type":"string"},"middle_initial":{"type":"string"},"last_name":{"type":"string"},"email":{"type":["string","null"],"format":"email","description":"The employee's personal email address. Required if self_onboarding is true."},"work_email":{"type":"string","format":"email","description":"The employee's work email address."},"date_of_birth":{"type":"string","format":"date"},"ssn":{"type":"string","pattern":"[0-9]{9}"},"preferred_first_name":{"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"}}}}}}}},"/v1/employees/{employee_id}/onboarding_status":{"get":{"summary":"Get the employee's onboarding status","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_id-onboarding_status","security":[{"CompanyAccessAuth":[]}],"description":"# Description\nRetrieves an employee's onboarding status. The data returned helps inform the required onboarding steps and respective completion status.\n\n\n## onboarding_status\n\n### Admin-facilitated onboarding\n| onboarding_status | Description |\n|:------------------|------------:|\n| `admin_onboarding_incomplete` | Admin needs to complete the full employee-onboarding. |\n| `onboarding_completed` | Employee has been fully onboarded and verified. |\n\n### Employee self-onboarding\n| onboarding_status | Description |\n|:------------------|------------:|\n| `admin_onboarding_incomplete` | Admin needs to enter basic information about the employee. |\n| `self_onboarding_pending_invite` | Admin has the intention to invite the employee to self-onboard (e.g., marking a checkbox), but the system has not yet sent the invitation. |\n| `self_onboarding_invited` | Employee has been sent an invitation to self-onboard. |\n| `self_onboarding_invited_started` | Employee has started the self-onboarding process. |\n| `self_onboarding_invited_overdue` | Employee's start date has passed, and employee has still not completed self-onboarding. |\n| `self_onboarding_completed_by_employee` | Employee has completed entering in their information. The status should be updated via API to \"self_onboarding_awaiting_admin_review\" from here, once the Admin has started reviewing. |\n| `self_onboarding_awaiting_admin_review` | Admin has started to verify the employee's information. |\n| `onboarding_completed` | Employee has been fully onboarded and verified. |\n\n## onboarding_steps\n\n| onboarding_steps | Requirement(s) to be completed |\n|:-----------------|-------------------------------:|\n| `personal_details` | Add employee's first name, last name, email, date of birth, social security number |\n| `compensation_details` | Associate employee to a job & compensation. |\n| `add_work_address` | Add employee work address. |\n| `add_home_address` | Add employee home address. |\n| `federal_tax_setup` | Set up federal tax withholdings. |\n| `state_tax_setup` | Set up state tax withholdings. |\n| `direct_deposit_setup` | (optional) Set up employee's direct deposit. |\n| `employee_form_signing` | Employee forms (e.g., W4, direct deposit authorization) are generated & signed. |\n| `file_new_hire_report` | File a new hire report for this employee. |\n| `admin_review` | Admin reviews & confirms employee details (only required for Employee self-onboarding) |\n\nscope: `employees:read`","tags":["Employees"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee-Onboarding-Status/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee-Onboarding-Status"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update the employee's onboarding status","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-employees-employee_id-onboarding_status","security":[{"CompanyAccessAuth":[]}],"description":"Updates an employee's onboarding status.\nBelow is a list of valid onboarding status changes depending on the intended action to be performed on behalf of the employee.\n\n| Action | current onboarding_status | new onboarding_status |\n|:------------------|:------------:|----------:|\n| Mark an employee as self-onboarding | `admin_onboarding_incomplete` | `self_onboarding_pending_invite` |\n| Invite an employee to self-onboard | `admin_onboarding_incomplete` or `self_onboarding_pending_invite` | `self_onboarding_invited` |\n| Cancel an employee's self-onboarding | `self_onboarding_invited` or `self_onboarding_pending_invite` | `admin_onboarding_incomplete` |\n| Review an employee's self-onboarded info | `self_onboarding_completed_by_employee` | `self_onboarding_awaiting_admin_review` |\n| Finish an employee's onboarding | `admin_onboarding_incomplete` or `self_onboarding_awaiting_admin_review` | `onboarding_completed` |\n\nscope: `employees:manage`","tags":["Employees"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee-Onboarding-Status/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee-Onboarding-Status"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"invalid status transition","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["onboarding_status"],"properties":{"onboarding_status":{"type":"string","description":"Onboarding status value","enum":["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","onboarding_completed"]}}}}},"required":true}}},"/v1/employees/{employee_id}/onboarding_documents_config":{"put":{"summary":"Update employee onboarding documents config","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","required":true,"description":"The UUID of the employee","example":"7b1d0df1-6403-4a06-8768-c1dd7d24d27a","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-employees-employee_id-onboarding_documents_config","security":[{"CompanyAccessAuth":[]}],"description":"Indicate whether to include the Form I-9 for an employee during the onboarding process.\nIf included, the employee will be prompted to complete Form I-9 as part of their onboarding.\n\n## Related guides\n- [Employee onboarding](doc:employee-onboarding)\n\nscope: `employees:manage`","tags":["Employees"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"config_with_i9":{"value":{"$ref":"#/components/schemas/Employee-Onboarding-Document/x-examples/config_with_i9"}}},"schema":{"$ref":"#/components/schemas/Employee-Onboarding-Document"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Employee-Onboarding-Documents-Config-Request"}}}}}},"/v1/employees/{employee_id}/employment_history":{"get":{"summary":"Get employment history for an employee","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_id-employment_history","security":[{"CompanyAccessAuth":[]}],"description":"Retrieve the employment history for a given employee, which includes termination and rehire.\n\nscope: `employments:read`","tags":["Employee Employments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employment-History-List/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employment-History-List"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/events":{"get":{"summary":"Get all events","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"starting_after_uuid","in":"query","required":false,"description":"A cursor for pagination. Returns all events occuring after the specified UUID (exclusive). Events are sorted according to the provided sort_order param.","schema":{"type":"string"}},{"name":"resource_uuid","in":"query","required":false,"description":"The UUID of the company. If not specified, will return all events for all companies.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Limits the number of objects returned in a single response, between 1 and 100. The default is 25","schema":{"type":"string"}},{"name":"event_type","in":"query","required":false,"description":"A string containing the exact event name (e.g. `employee.created`), or use a wildcard match to filter for a group of events (e.g. `employee.*`, `*.created`, `notification.*.created` etc.)","schema":{"type":"string"}},{"name":"sort_order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"]},"description":"A string indicating whether to sort resulting events in ascending (asc) or descending (desc) chronological order. Events are sorted by their `timestamp`. Defaults to asc if left empty."}],"x-gusto-rswag":true,"operationId":"get-events","security":[{"SystemAccessAuth":[]}],"description":"Fetch all events, going back up to 30 days, that your partner application has the required scopes for. Note that a partner does NOT have to have verified webhook subscriptions in order to utilize this endpoint.\n\n📘 System Access Authentication\n\nThis endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)\n\nscope: `events:read`","tags":["Events"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Event-List/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Event-List"}}}},"422":{"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","content":{"application/json":{"examples":{"starting_after_uuid_invalid":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/starting_after_uuid_invalid"}},"resource_uuid_invalid":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/resource_uuid_invalid"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/companies/{company_uuid}/external_payrolls":{"get":{"summary":"Get external payrolls for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-company-external-payrolls","security":[{"CompanyAccessAuth":[]}],"tags":["External Payrolls"],"x-gusto-integration-type":["embedded"],"description":"Get external payrolls for a company.\n\nscope: `external_payrolls:read`","responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":[{"$ref":"#/components/schemas/External-Payroll-Basic/x-examples/Example"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/External-Payroll-Basic"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create an external payroll for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-external-payroll","security":[{"CompanyAccessAuth":[]}],"tags":["External Payrolls"],"x-gusto-integration-type":["embedded"],"description":"Creates a new external payroll for a company.\n\nscope: `external_payrolls:write`","responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/External-Payroll/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/External-Payroll"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"external_payroll_missing_check_date":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/external_payroll_missing_check_date"}},"external_payroll_missing_payment_period_dates":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/external_payroll_missing_payment_period_dates"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/External-Payroll-Create-Request"}}},"required":true}}},"/v1/companies/{company_uuid}/external_payrolls/tax_liabilities":{"get":{"summary":"Get tax liabilities","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-tax-liabilities","security":[{"CompanyAccessAuth":[]}],"tags":["External Payrolls"],"x-gusto-integration-type":["embedded"],"description":"Get tax liabilities from aggregate external payrolls for a company.\n\nscope: `external_payrolls:read`","responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":[{"$ref":"#/components/schemas/Tax-Liabilities-Selections/x-examples/Example"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Tax-Liabilities-Selections"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update tax liabilities","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-tax-liabilities","security":[{"CompanyAccessAuth":[]}],"tags":["External Payrolls"],"x-gusto-integration-type":["embedded"],"description":"Update tax liabilities for a company.\n\nscope: `external_payrolls:write`","responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":[{"$ref":"#/components/schemas/Tax-Liabilities-Selections/x-examples/Example"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Tax-Liabilities-Selections"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"invalid_tax_liability_selection":{"value":[{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_tax_liability_selection"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tax-Liability-Selections-Request"}}},"required":true}}},"/v1/companies/{company_uuid}/external_payrolls/tax_liabilities/finish":{"put":{"summary":"Finalize tax liabilities options and convert into processed payrolls","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-tax-liabilities-finish","security":[{"CompanyAccessAuth":[]}],"tags":["External Payrolls"],"x-gusto-integration-type":["embedded"],"description":"Finalizes tax liabilities for a company. All external payrolls edit action will be disabled.\n\n### Asynchronous processing\nThis endpoint triggers an asynchronous operation. The external payrolls will be processed in the background after finalization.\n\nscope: `external_payrolls:write`","responses":{"202":{"description":"Accepted"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"external_payroll_invalid_tax_liability_selections":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/external_payroll_invalid_tax_liability_selections"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/companies/{company_uuid}/external_payrolls/{external_payroll_id}":{"get":{"summary":"Get an external payroll","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"external_payroll_id","in":"path","description":"The UUID of the external payroll","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-external-payroll","security":[{"CompanyAccessAuth":[]}],"tags":["External Payrolls"],"x-gusto-integration-type":["embedded"],"description":"Get an external payroll for a given company.\n\nscope: `external_payrolls:read`","responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/External-Payroll/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/External-Payroll"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update an external payroll","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"external_payroll_id","in":"path","description":"The UUID of the external payroll","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-external-payroll","security":[{"CompanyAccessAuth":[]}],"tags":["External Payrolls"],"x-gusto-integration-type":["embedded"],"description":"Update an external payroll with a list of external payroll items.\n\nscope: `external_payrolls:write`","responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/External-Payroll/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/External-Payroll"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"external_payroll_invalid_payroll_item":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/external_payroll_invalid_payroll_item"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/External-Payroll-Update-Request"}}},"required":true}},"delete":{"summary":"Delete an external payroll","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"external_payroll_id","in":"path","description":"The UUID of the external payroll","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-external-payroll","security":[{"CompanyAccessAuth":[]}],"tags":["External Payrolls"],"x-gusto-integration-type":["embedded"],"description":"Delete an external payroll.\n\nscope: `external_payrolls:write`","responses":{"204":{"description":"No Content"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"external_payrolls_locked":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/external_payrolls_locked"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/companies/{company_uuid}/external_payrolls/{external_payroll_id}/calculate_taxes":{"get":{"summary":"Get tax suggestions for an external payroll","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"external_payroll_id","in":"path","description":"The UUID of the external payroll","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-external-payroll-calculate-taxes","security":[{"CompanyAccessAuth":[]}],"tags":["External Payrolls"],"x-gusto-integration-type":["embedded"],"description":"Get tax suggestions for an external payroll. Earnings and/or benefits data must be saved prior to the calculation in order to retrieve accurate tax calculation.\n\nscope: `external_payrolls:read`","responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":[{"$ref":"#/components/schemas/External-Payroll-Tax-Suggestions/x-examples/Example"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/External-Payroll-Tax-Suggestions"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"external_payroll_net_pay_less_than_zero":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/external_payroll_net_pay_less_than_zero"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/companies/{company_uuid}/flows":{"post":{"summary":"Create a flow","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-company-flows","security":[{"CompanyAccessAuth":[]}],"description":"Generate a link to access a pre-built workflow in Gusto white-label UI. For security, all generated flows will expire within 1 hour of inactivity or 24 hours from creation time, whichever comes first.\n\nYou can see a list of all possible flow types in our [Flow Types](https://docs.gusto.com/embedded-payroll/docs/flow-types) guide.\n\nYou can also mix and match flow_types in the same category to create custom flows suitable for your needs.\n\nFor instance, to create a custom onboarding flow that only includes `add_addresses`, `add_employees`, and `sign_all_forms` steps, simply stitch those flow_types together into a comma delimited string:\n\n```json\n{\n  \"flow_type\": \"add_addresses,add_employees,sign_all_forms\"\n}\n```\n\nPlease be mindful of data dependencies in each step to achieve the best user experience.\n\nFor more information and in-depth guides review the [Getting Started](https://docs.gusto.com/embedded-payroll/docs/flows-getting-started) guide for flows.\n\nscope: `flows:write`","tags":["Flows"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Flow/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Flow"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"flow_invalid_entity":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/flow_invalid_entity"}},"flow_nested_options_errors":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/flow_nested_options_errors"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Create-Flow-Request"}}},"required":true}}},"/v1/employees/{employee_id}/garnishments":{"get":{"summary":"Get garnishments for an employee","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_id-garnishments","security":[{"CompanyAccessAuth":[]}],"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.\n\nscope: `garnishments:read`","tags":["Garnishments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Garnishment-List":{"value":{"$ref":"#/components/schemas/Garnishment/x-examples/Garnishment-List"}}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Garnishment"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create a garnishment","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-employees-employee_id-garnishments","security":[{"CompanyAccessAuth":[]}],"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.\n\nscope: `garnishments:write`","tags":["Garnishments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"201":{"description":"Example response","content":{"application/json":{"examples":{"Create-Example":{"value":{"$ref":"#/components/schemas/Garnishment/x-examples/Create-Example"}},"Child-Support-Example":{"value":{"$ref":"#/components/schemas/Garnishment/x-examples/Child-Support-Example"}}},"schema":{"$ref":"#/components/schemas/Garnishment"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"garnishment_invalid_amount":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/garnishment_invalid_amount"}},"garnishment_pay_period_exceeds_annual":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/garnishment_pay_period_exceeds_annual"}},"garnishment_child_support_invalid_fips":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/garnishment_child_support_invalid_fips"}},"garnishment_child_support_missing_fields":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/garnishment_child_support_missing_fields"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Garnishment-Request"}}},"required":true}}},"/v1/garnishments/child_support":{"get":{"summary":"Get child support garnishment data","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."}],"x-gusto-rswag":true,"operationId":"get-v1-garnishments-child_support","security":[{"CompanyAccessAuth":[]}],"description":"Agency data and requirements to be used for creating child support garnishments\n\nscope: `garnishments:read`","tags":["Garnishments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Child-Support-Data/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Child-Support-Data"}}}}}}},"/v1/garnishments/{garnishment_id}":{"get":{"summary":"Get a garnishment","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"garnishment_id","in":"path","description":"The UUID of the garnishment","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-garnishments-garnishment_id","security":[{"CompanyAccessAuth":[]}],"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.\n\nscope: `garnishments:read`","tags":["Garnishments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Garnishment/x-examples/Example"}},"Child-Support-Example":{"value":{"$ref":"#/components/schemas/Garnishment/x-examples/Child-Support-Example"}}},"schema":{"$ref":"#/components/schemas/Garnishment"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update a garnishment","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"garnishment_id","in":"path","description":"The UUID of the garnishment","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-garnishments-garnishment_id","security":[{"CompanyAccessAuth":[]}],"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.\n\nscope: `garnishments:write`","tags":["Garnishments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Garnishment/x-examples/Example"}},"Child-Support-Example":{"value":{"$ref":"#/components/schemas/Garnishment/x-examples/Child-Support-Example"}}},"schema":{"$ref":"#/components/schemas/Garnishment"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"garnishment_invalid_amount":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/garnishment_invalid_amount"}},"garnishment_type_cannot_change":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/garnishment_type_cannot_change"}},"garnishment_child_support_invalid_fips":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/garnishment_child_support_invalid_fips"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Update-Garnishment-Request"}}},"required":true}}},"/v1/payrolls/{payroll_uuid}/generated_documents/printable_payroll_checks":{"post":{"summary":"Generate printable payroll checks (pdf)","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"payroll_uuid","in":"path","required":true,"description":"The UUID of the payroll","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-payrolls-payroll_uuid-generated_documents-printable_payroll_checks","security":[{"CompanyAccessAuth":[]}],"description":"This endpoint initiates the generation of employee checks for the payroll specified by payroll_uuid. A generation status and corresponding request_uuid will be returned. Use the generated document GET endpoint with document_type: `printable_payroll_checks` and request_uuid to poll the check generation process and retrieve the generated check URL upon completion.\n\nscope: `generated_documents:write`","tags":["Payrolls"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Payroll-Check/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Payroll-Check"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"printable_payroll_checks_invalid_printing_format":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/printable_payroll_checks_invalid_printing_format"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Printable-Payroll-Checks-Body"}}},"required":true}}},"/v1/generated_documents/{document_type}/{request_uuid}":{"get":{"summary":"Get a generated document","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"document_type","in":"path","required":true,"schema":{"type":"string","enum":["printable_payroll_checks"]},"description":"The type of document being generated"},{"name":"request_uuid","in":"path","required":true,"description":"The UUID of the request to generate a document. Generate document endpoints return request_uuids to be used with the GET generated document endpoint.","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-generated_documents-document_type-request_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Get a document given the request_uuid. The response will include the generation request's status and urls to the document. A list of urls is returned as certain document types require several urls.\n\nscope: `generated_documents:read`","tags":["Generated Documents"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Generated-Document/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Generated-Document"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/companies/{company_uuid}/historical_employees":{"post":{"summary":"Create a historical employee","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","required":true,"description":"The UUID of the company that will employ this historical record.","example":"7b1d0df1-6403-4a06-8768-c1dd7d24d27a","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-historical_employees","security":[{"CompanyAccessAuth":[]}],"description":"Create a historical employee, an employee that was previously dismissed from the company in the current year.\n\nscope: `employees:manage`","tags":["Employees"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Historical-Employee-Body"}}},"required":true}}},"/v1/companies/{company_uuid}/historical_employees/{historical_employee_uuid}":{"put":{"summary":"Update a historical employee","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","required":true,"description":"The UUID of the company that will employ this historical record.","example":"7b1d0df1-6403-4a06-8768-c1dd7d24d27a","schema":{"type":"string"}},{"name":"historical_employee_uuid","in":"path","required":true,"description":"The UUID of the historical employee returned from create or list responses.","example":"a2b3c4d-5e6f-7890-abcd-ef1234567890","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-historical_employees","security":[{"CompanyAccessAuth":[]}],"description":"Update a historical employee, an employee that was previously dismissed from the company in the current year.\n\nscope: `employees:manage employees:write`","tags":["Employees"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Versionable-Required"},{"$ref":"#/components/schemas/Historical-Employee-Body"}]}}},"required":true}}},"/v1/companies/{company_uuid}/holiday_pay_policy":{"get":{"summary":"Get a company's holiday pay policy","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_uuid-holiday_pay_policy","security":[{"CompanyAccessAuth":[]}],"description":"Get a company's holiday pay policy\n\nscope: `holiday_pay_policies:read`","tags":["Holiday Pay Policies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Holiday-Pay-Policy/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Holiday-Pay-Policy"}}}},"204":{"description":"no policy exists"},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create a holiday pay policy for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_uuid-holiday_pay_policy","security":[{"CompanyAccessAuth":[]}],"description":"Create a holiday pay policy for a company\n\nscope: `holiday_pay_policies:write`","tags":["Holiday Pay Policies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Holiday-Pay-Policy/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Holiday-Pay-Policy"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"company already has a policy","content":{"application/json":{"examples":{"holiday_pay_policy_already_exists":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/holiday_pay_policy_already_exists"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Holiday-Pay-Policy-Request"}}}}},"put":{"summary":"Update a company's holiday pay policy","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-companies-company_uuid-holiday_pay_policy","security":[{"CompanyAccessAuth":[]}],"description":"Update a company's holiday pay policy\n\nscope: `holiday_pay_policies:write`","tags":["Holiday Pay Policies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Holiday-Pay-Policy/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Holiday-Pay-Policy"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"no policy exists","content":{"application/json":{"examples":{"holiday_pay_policy_not_exists":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/holiday_pay_policy_not_exists"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Versionable-Required"},{"$ref":"#/components/schemas/Holiday-Pay-Policy-Request"}]}}},"required":true}},"delete":{"summary":"Delete a company's holiday pay policy","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-companies-company_uuid-holiday_pay_policy","security":[{"CompanyAccessAuth":[]}],"description":"Delete a company's holiday pay policy\n\nscope: `holiday_pay_policies:write`","tags":["Holiday Pay Policies"],"x-gusto-integration-type":["embedded"],"responses":{"204":{"description":"successful"},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"no policy exists","content":{"application/json":{"examples":{"holiday_pay_policy_not_exists":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/holiday_pay_policy_not_exists"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/companies/{company_uuid}/holiday_pay_policy/add":{"put":{"summary":"Add employees to a company's holiday pay policy","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-companies-company_uuid-holiday_pay_policy-add","security":[{"CompanyAccessAuth":[]}],"description":"Add employees to a company's holiday pay policy\n\nscope: `holiday_pay_policies:write`","tags":["Holiday Pay Policies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Holiday-Pay-Policy/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Holiday-Pay-Policy"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"no policy exists","content":{"application/json":{"examples":{"holiday_pay_policy_not_exists":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/holiday_pay_policy_not_exists"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Versionable-Required"},{"type":"object","required":["employees"],"properties":{"employees":{"type":"array","description":"An array of employee objects, each containing an employee_uuid.","items":{"type":"object","properties":{"uuid":{"type":"string"}}}}}}]}}},"required":true}}},"/v1/companies/{company_uuid}/holiday_pay_policy/remove":{"put":{"summary":"Remove employees from a company's holiday pay policy","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-companies-company_uuid-holiday_pay_policy-remove","security":[{"CompanyAccessAuth":[]}],"description":"Remove employees from a company's holiday pay policy\n\nscope: `holiday_pay_policies:write`","tags":["Holiday Pay Policies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Holiday-Pay-Policy/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Holiday-Pay-Policy"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"no policy exists","content":{"application/json":{"examples":{"holiday_pay_policy_not_exists":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/holiday_pay_policy_not_exists"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Versionable-Required"},{"type":"object","required":["employees"],"properties":{"employees":{"type":"array","description":"An array of employee objects, each containing an employee_uuid.","items":{"type":"object","properties":{"uuid":{"type":"string"}}}}}}]}}},"required":true}}},"/v1/employees/{employee_id}/home_addresses":{"get":{"summary":"Get an employee's home addresses","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_id-home_addresses","security":[{"CompanyAccessAuth":[]}],"description":"The home address of an employee is used to determine certain tax information about them. Addresses are geocoded on create and update to ensure validity.\n\nSupports home address effective dating and courtesy withholding.\n\nscope: `employees:read`","tags":["Employee Addresses"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee-Address-List/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee-Address-List"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create an employee's home address","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-employees-employee_id-home_addresses","security":[{"CompanyAccessAuth":[]}],"description":"The home address of an employee is used to determine certain tax information about them. Addresses are geocoded on create and update to ensure validity.\n\nSupports home address effective dating and courtesy withholding.\n\nscope: `employees:write`","tags":["Employee Addresses"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"201":{"description":"created","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee-Address/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee-Address"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"street_1":{"type":"string","example":"300 3rd Street"},"street_2":{"type":["string","null"]},"city":{"type":"string","example":"San Francisco"},"state":{"type":"string","example":"CA"},"zip":{"type":"string","example":"94107"},"effective_date":{"type":["string","null"],"format":"date","example":"2022-01-31"},"courtesy_withholding":{"type":"boolean"}}}}},"required":true}}},"/v1/home_addresses/{home_address_uuid}":{"get":{"summary":"Get an employee's home address","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"home_address_uuid","in":"path","description":"The UUID of the home address","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-home_addresses-home_address_uuid","security":[{"CompanyAccessAuth":[]}],"description":"The home address of an employee is used to determine certain tax information about them. Addresses are geocoded on create and update to ensure validity.\n\nSupports home address effective dating and courtesy withholding.\n\nscope: `employees:read`","tags":["Employee Addresses"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee-Address/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee-Address"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update an employee's home address","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"home_address_uuid","in":"path","description":"The UUID of the home address","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-home_addresses-home_address_uuid","security":[{"CompanyAccessAuth":[]}],"description":"The home address of an employee is used to determine certain tax information about them. Addresses are geocoded on create and update to ensure validity.\n\nSupports home address effective dating and courtesy withholding.\n\nscope: `employees:write`","tags":["Employee Addresses"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee-Address/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee-Address"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Versionable-Required"},{"type":"object","properties":{"street_1":{"type":"string"},"street_2":{"type":["string","null"]},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"},"effective_date":{"type":["string","null"],"format":"date"},"courtesy_withholding":{"type":"boolean"}}}]}}},"required":true}},"delete":{"summary":"Delete an employee's home address","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"home_address_uuid","in":"path","description":"The UUID of the home address","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-home_addresses-home_address_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Used for deleting an employee's home address. Cannot delete the employee's active home address.\n\nscope: `employees:write`","tags":["Employee Addresses"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"204":{"description":"successful"},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/employees/{employee_id}/i9_authorization":{"get":{"summary":"Get an employee's I-9 authorization","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_id-i9_authorization","security":[{"CompanyAccessAuth":[]}],"description":"An employee's I-9 authorization stores information about an employee's authorization status and I-9 signatures, information required to fill out the Form I-9 for employment eligibility verification.\n\n**NOTE:** The `form_uuid` in responses from this endpoint can be used to retrieve the PDF version of the I-9. See the \"get employee form PDF\" request for more details.\n\n### Related guides\n- [I-9 employment verification](doc:i-9-employment-verification)\n\nscope: `i9_authorizations:read`","tags":["I-9 Verification"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"alien_with_foreign_passport":{"value":{"$ref":"#/components/schemas/I9-Authorization/x-examples/alien_with_foreign_passport"}},"citizen_authorization":{"value":{"$ref":"#/components/schemas/I9-Authorization/x-examples/citizen_authorization"}}},"schema":{"$ref":"#/components/schemas/I9-Authorization"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Create or update an employee's I-9 authorization","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-employees-employee_id-i9_authorization","security":[{"CompanyAccessAuth":[]}],"description":"An employee's I-9 authorization stores information about an employee's authorization status, as well as signatures and other information required to complete the Form I-9 for employment eligibility verification.\n\nIf the version is supplied and the employee I-9 authorization exists, this endpoint acts as an update. Otherwise, it will create an employee I-9 authorization.\n\nValidations on this endpoint are conditional:\n  * `document_type` may be required, depending on `authorization_status`.\n  * Valid formats for `document_number` vary, depending on `document_type`.\n  * `country` is only allowed with `document_type: 'foreign_passport'`.\n  * `expiration_date` is only allowed with `authorization_status: 'alien'`.\n\n> ℹ️ Unneeded information is automatically removed during updates.\n>\n> If an update causes some formerly-required fields to be unneeded, the now-unneeded data will be removed automatically.\n>\n> **Example:** Updating `authorization_status` from `alien` to `citizen` will cause any data in `document_type`, `document_number`, `country`, and `expiration_date` to be removed, since these fields are unused for `authorization_status:'citizen'`.\n\nDetailed instructions for completing Form I-9 can be found at https://www.uscis.gov/sites/default/files/document/forms/i-9instr.pdf\n\n### Related guides\n- [I-9 employment verification](doc:i-9-employment-verification)\n\nscope: `i9_authorizations:write`","tags":["I-9 Verification"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"alien_with_foreign_passport":{"value":{"$ref":"#/components/schemas/I9-Authorization/x-examples/alien_with_foreign_passport"}},"citizen_authorization":{"value":{"$ref":"#/components/schemas/I9-Authorization/x-examples/citizen_authorization"}}},"schema":{"$ref":"#/components/schemas/I9-Authorization"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"i9_authorization_unneeded_document_params":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/i9_authorization_unneeded_document_params"}},"i9_authorization_not_self_onboarding":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/i9_authorization_not_self_onboarding"}},"i9_authorization_employee_already_signed":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/i9_authorization_employee_already_signed"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/I9-Authorization-Request-Body"}}},"required":true}}},"/v1/employees/{employee_id}/i9_authorization/document_options":{"get":{"summary":"Get an employee's I-9 verification document options","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_id-i9_authorization-document_options","security":[{"CompanyAccessAuth":[]}],"description":"An employee's I-9 verification documents are the documents an employee has provided the employer to verify their identity and authorization to work in the United States. This endpoint returns the possible document options based on the employee's authorization status. These options can then be used to create the I-9 verification documents.\n\n### Related guides\n- [I-9 employment verification](doc:i-9-employment-verification)\n\nscope: `i9_authorizations:read`","tags":["I-9 Verification"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":[{"$ref":"#/components/schemas/I9-Authorization-Document-Option/x-examples/example_a"},{"$ref":"#/components/schemas/I9-Authorization-Document-Option/x-examples/example_b"},{"$ref":"#/components/schemas/I9-Authorization-Document-Option/x-examples/example_c"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/I9-Authorization-Document-Option"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/employees/{employee_id}/i9_authorization/documents":{"get":{"summary":"Get an employee's I-9 verification documents","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_id-i9_authorization-documents","security":[{"CompanyAccessAuth":[]}],"description":"An employee's I-9 verification documents are the documents an employee has provided the employer to verify their identity and authorization to work in the United States.\n\n### Related guides\n- [I-9 employment verification](doc:i-9-employment-verification)\n\nscope: `i9_authorizations:read`","tags":["I-9 Verification"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":[{"$ref":"#/components/schemas/I9-Authorization-Document/x-examples/driver_license"},{"$ref":"#/components/schemas/I9-Authorization-Document/x-examples/ssn_card"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/I9-Authorization-Document"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Create an employee's I-9 authorization verification documents","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-employees-employee_id-i9_authorization-documents","security":[{"CompanyAccessAuth":[]}],"description":"An employee's I-9 verification documents are the documents an employee has provided the employer to verify their identity and authorization to work in the United States.\n\nUse the [document options endpoint](ref:get-v1-employees-employee_id-i9_authorization-document_options) to get the possible document types and titles, which can vary depending on the employee's authorization status.\n\n> 🚧 Every request must contain the complete list of documents for the Employee.\n>\n> Every request to this endpoint removes any previous verification document records for the employee.\n\n### Related guides\n- [I-9 employment verification](doc:i-9-employment-verification)\n\nscope: `i9_authorizations:manage`","tags":["I-9 Verification"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"Example":{"value":[{"$ref":"#/components/schemas/I9-Authorization-Document/x-examples/driver_license"},{"$ref":"#/components/schemas/I9-Authorization-Document/x-examples/ssn_card"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/I9-Authorization-Document"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"i9_documents_already_signed":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/i9_documents_already_signed"}},"i9_documents_invalid_params":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/i9_documents_invalid_params"}},"i9_documents_not_array":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/i9_documents_not_array"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/I9-Authorization-Documents-Request-Body"}}},"required":true}}},"/v1/employees/{employee_id}/i9_authorization/documents/{document_id}":{"delete":{"summary":"Delete an employee's I-9 verification document","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}},{"name":"document_id","in":"path","description":"The UUID of the document","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-employees-employee_id-i9_authorization-documents-document_id","security":[{"CompanyAccessAuth":[]}],"description":"An employee's I-9 verification documents are the documents an employee has provided the employer to verify their identity and authorization to work in the United States. This endpoint deletes a specific verification document.\n\n### Related guides\n- [I-9 employment verification](doc:i-9-employment-verification)\n\nscope: `i9_authorizations:manage`","tags":["I-9 Verification"],"x-gusto-integration-type":["embedded"],"responses":{"204":{"description":"No Content"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"i9_documents_already_signed":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/i9_documents_already_signed"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/employees/{employee_id}/i9_authorization/employer_sign":{"put":{"summary":"Employer sign an employee's Form I-9","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}},{"name":"x-gusto-client-ip","in":"header","required":false,"schema":{"type":"string"},"description":"Optional header to supply the IP address. This can be used to supply the IP address for signature endpoints instead of the signed_by_ip_address parameter."}],"x-gusto-rswag":true,"operationId":"put-v1-employees-employee_id-i9_authorization-employer_sign","security":[{"CompanyAccessAuth":[]}],"description":"Sign an employee's Form I-9 as an employer. Once the form is signed, the employee's I-9 authorization is considered complete and cannot be modified.\n\n### Prerequisites\nBefore calling this endpoint:\n1. The employee must have a completed [I-9 authorization](ref:put-v1-employees-employee_id-i9_authorization)\n2. The employee must have signed the Form I-9\n3. [I-9 verification documents](ref:put-v1-employees-employee_id-i9_authorization-documents) must be submitted\n\n### Related guides\n- [I-9 employment verification](doc:i-9-employment-verification)\n\nscope: `i9_authorizations:manage`","tags":["I-9 Verification"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"employer_signed_authorization":{"value":{"$ref":"#/components/schemas/I9-Authorization/x-examples/employer_signed_authorization"}}},"schema":{"$ref":"#/components/schemas/I9-Authorization"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"i9_employer_sign_invalid_params":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/i9_employer_sign_invalid_params"}},"i9_employer_sign_employee_not_signed":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/i9_employer_sign_employee_not_signed"}},"i9_employer_sign_already_signed":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/i9_employer_sign_already_signed"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/I9-Authorization-Employer-Sign-Request-Body"}}},"required":true}}},"/v1/companies/{company_uuid}/information_requests":{"get":{"summary":"Get all information requests for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","pattern":"^(payroll_blocker|status|type)(:(asc|desc))?(,(payroll_blocker|status|type)(:(asc|desc))?)*$","example":"payroll_blocker:asc"},"description":"Sort by one or more fields. Options: payroll_blocker, status, type. Append `:asc` or `:desc` to specify direction (e.g., `payroll_blocker:asc`). Defaults to ascending."}],"x-gusto-rswag":true,"operationId":"get-information-requests","security":[{"CompanyAccessAuth":[]}],"description":"Fetch all information requests for a company.\n\nscope: `information_requests:read`","tags":["Information Requests"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"information_request_index_item":{"value":[{"$ref":"#/components/schemas/Information-Request/x-examples/information_request_index_item"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Information-Request"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/invoices/{invoice_period}":{"get":{"summary":"Retrieve invoicing data for companies","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"invoice_period","in":"path","required":true,"description":"The month we are calculating the invoice for. Must be in YYYY-MM format","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}},{"name":"company_uuids","in":"query","required":false,"description":"Filter companies returned in the active_companies response, will return an error if company not active during provided invoice period. i.e. `?company_uuids=781922d8-e780-4b6b-bf74-ee303166d022,bbbca930-7322-491c-ba7f-98707a52a9c5`","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-invoices-invoice-period","security":[{"SystemAccessAuth":[]}],"description":"Retrieve data for active companies used to calculate invoices for Gusto Embedded Payroll. A company is considered active for an invoice period if they are an active partner managed company, have run payroll or created contractor payments since becoming a partner managed company, and are not suspended at any point during the invoice period.  This endpoint forces pagination, with 100 results returned at a time. You can learn more about our pagination here: [pagination guide](https://docs.gusto.com/embedded-payroll/docs/pagination)\n\n📘 System Access Authentication\n\nThis endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)\n\nscope: `invoices:read`","tags":["Invoices"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Invoice-Data/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Invoice-Data"}}}},"422":{"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","content":{"application/json":{"examples":{"invoice_period_invalid_format":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invoice_period_invalid_format"}},"invoice_period_future":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invoice_period_future"}},"invoice_company_uuids_max_exceeded":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invoice_company_uuids_max_exceeded"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/jobs/{job_id}":{"get":{"summary":"Get a job","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"job_id","in":"path","description":"The UUID of the job","required":true,"schema":{"type":"string"}},{"name":"include","in":"query","required":false,"schema":{"type":"string","enum":["all_compensations"]},"description":"Available options:\n- all_compensations: Include all effective dated compensations for each job instead of only the current compensation\n"}],"x-gusto-rswag":true,"operationId":"get-v1-jobs-job_id","security":[{"CompanyAccessAuth":[]}],"description":"Get a job.\n\nNote: Compensation data (pay rate, payment unit, and related fields) represents sensitive employee pay information. When retrieving employee job data, these fields (`rate`, `payment_unit`, `current_compensation_uuid`, `compensations`) are only returned when the `compensations:read` scope is included. This allows you to access employee and job metadata without exposing pay rates.\n\nCompensation data in the response requires the `compensations:read` scope.\n\nscope: `jobs:read`","tags":["Jobs and Compensations"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Job/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Job"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update a job","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"job_id","in":"path","description":"The UUID of the job","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-jobs-job_id","security":[{"CompanyAccessAuth":[]}],"description":"Update a job.\n\nscope: `jobs:write`","tags":["Jobs and Compensations"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful blank title on a non-primary active job","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Job/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Job"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"job_invalid_hire_date":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/job_invalid_hire_date"}},"job_duplicate_title":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/job_duplicate_title"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Jobs-Update-Request-Body"}}},"required":true}},"delete":{"summary":"Delete an individual job","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"job_id","in":"path","description":"The UUID of the job","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-jobs-job_id","security":[{"CompanyAccessAuth":[]}],"description":"Deletes a specific job that an employee holds.\n\nscope: `jobs:write`","tags":["Jobs and Compensations"],"x-gusto-integration-type":["embedded"],"responses":{"204":{"description":"successful"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"job_primary_cannot_delete":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/job_primary_cannot_delete"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/employees/{employee_id}/jobs":{"get":{"summary":"Get jobs for an employee","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}},{"name":"include","in":"query","required":false,"schema":{"type":"string","enum":["all_compensations"]},"description":"Available options:\n- all_compensations: Include all effective dated compensations for each job instead of only the current compensation\n"}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_id-jobs","security":[{"CompanyAccessAuth":[]}],"description":"Get all of the jobs that an employee holds.\nNote: Compensation data (pay rate, payment unit, and related fields) represents sensitive employee pay information. When retrieving employee job data, these fields (`rate`, `payment_unit`, `current_compensation_uuid`, `compensations`) are only returned when the `compensations:read` scope is included. This allows you to access employee and job metadata without exposing pay rates.\n\nCompensation data in the response requires the `compensations:read` scope.\n\nscope: `jobs:read`","tags":["Jobs and Compensations"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"example":{"value":[{"$ref":"#/components/schemas/Job/x-examples/example"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Job"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create a job","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-employees-employee_id-jobs","security":[{"CompanyAccessAuth":[]}],"description":"Create a job.\n\nscope: `jobs:write`","tags":["Jobs and Compensations"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"created a primary job with a null title","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Job/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Job"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"job_exempt_multiple_jobs":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/job_exempt_multiple_jobs"}},"job_invalid_hire_date":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/job_invalid_hire_date"}},"job_duplicate_title":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/job_duplicate_title"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Jobs-Create-Request-Body"}}},"required":true}}},"/v1/locations/{location_uuid}/minimum_wages":{"get":{"summary":"Get minimum wages for a location","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"location_uuid","in":"path","description":"The UUID of the location","required":true,"schema":{"type":"string"}},{"name":"effective_date","in":"query","required":false,"example":"2020-01-31","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-locations-location_uuid-minimum_wages","security":[{"CompanyAccessAuth":[]}],"description":"Get minimum wages for a location\n\nscope: `companies:read`","tags":["Locations"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Minimum-Wage-List/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Minimum-Wage-List"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/locations/{location_id}":{"get":{"summary":"Get a location","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"location_id","in":"path","description":"The UUID of the location","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-locations-location_id","security":[{"CompanyAccessAuth":[]}],"description":"Get a location.\n\nscope: `companies:read`","tags":["Locations"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Location/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Location"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update a location","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"location_id","in":"path","description":"The UUID of the location","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-locations-location_id","security":[{"CompanyAccessAuth":[]}],"description":"Update a location.\n\nscope: `companies:write`","tags":["Locations"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Location/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Location"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"409":{"description":"Invalid version param","content":{"application/json":{"examples":{"invalid_version":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_version"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}},"422":{"description":"Invalid state","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Versionable-Required"},{"type":"object","properties":{"phone_number":{"type":"string","pattern":"[0-9]{10}","example":"8009360383"},"street_1":{"type":"string","example":"300 3rd Street"},"street_2":{"type":["string","null"],"example":"Apartment 318"},"city":{"type":"string","example":"San Francisco"},"state":{"type":"string"},"zip":{"type":"string","example":"94107"},"country":{"type":"string"},"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."},"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."}}}]}}},"required":true}}},"/v1/companies/{company_id}/locations":{"get":{"summary":"Get all company locations","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","example":"7b1d0df1-6403-4a06-8768-c1dd7d24d27a","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-locations","security":[{"CompanyAccessAuth":[]}],"description":"Retrieves all company locations (addresses) associated with a company: mailing addresses, filing\naddresses, or work locations. A single address may serve multiple, or all, purposes.\n\nSince all company locations are subsets of locations, use the Locations endpoints to\n[get](ref:get-v1-locations-location_id) or [update](ref:put-v1-locations-location_id) an individual record.\n\nscope: `companies:read`","tags":["Locations"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Company-Locations-List/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Company-Locations-List"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create a company location","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_id-locations","security":[{"CompanyAccessAuth":[]}],"description":"Create a company location, which represents any address associated with a company: mailing\naddresses, filing addresses, or work locations. A single address may serve multiple, or all, purposes.\n\nSince all company locations are subsets of locations, use the Locations endpoints to\n[get](ref:get-v1-locations-location_id) or [update](ref:put-v1-locations-location_id) an individual record.\n\nscope: `companies:write`","tags":["Locations"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Location/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Location"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"company_location_validation":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/company_location_validation"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company-Location-Request"}}},"required":true}}},"/v1/employees/{employee_id}/member_portal_invitations":{"post":{"summary":"Create an employee member portal invitation","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-employees-employee_id-member_portal_invitations","security":[{"CompanyAccessAuth":[]}],"description":"Generates a member portal invitation for the specified employee. If the employee already has an invitation and its token has expired, calling this endpoint regenerates the invitation and overrides the prior token.\n\nscope: `member_portal_invitation:write`","tags":["Member Portal Invitations"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"Created"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"member_portal_member_info_incomplete_missing_start_date":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/member_portal_member_info_incomplete_missing_start_date"}},"member_portal_already_complete":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/member_portal_already_complete"}},"member_portal_not_eligible":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/member_portal_not_eligible"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}},"get":{"summary":"Get an employee member portal invitation","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_id-member_portal_invitations","security":[{"CompanyAccessAuth":[]}],"description":"Returns the current status of an employee's member portal invitation (`pending`, `sent`, `verified`, `complete`, or `cancelled`) along with an `expired` flag indicating whether the invitation can still be acted on by the employee.\n\nscope: `member_portal_invitation:read`","tags":["Member Portal Invitations"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"sent_invitation":{"value":{"$ref":"#/components/schemas/Member-Portal-Invitation/x-examples/sent_invitation"}},"complete_invitation":{"value":{"$ref":"#/components/schemas/Member-Portal-Invitation/x-examples/complete_invitation"}},"cancelled_invitation":{"value":{"$ref":"#/components/schemas/Member-Portal-Invitation/x-examples/cancelled_invitation"}}},"schema":{"$ref":"#/components/schemas/Member-Portal-Invitation"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"delete":{"summary":"Cancel an employee member portal invitation","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-employees-employee_id-member_portal_invitations","security":[{"CompanyAccessAuth":[]}],"description":"Cancels the member portal invitation for the specified employee.\n\nNote: this endpoint does not cancel the employee's self-onboarding flow. If you want the company admin to take full control of onboarding the employee, cancel the self-onboarding request instead.\n\nscope: `member_portal_invitation:write`","tags":["Member Portal Invitations"],"x-gusto-integration-type":["embedded"],"responses":{"204":{"description":"No Content"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"member_portal_already_cancelled":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/member_portal_already_cancelled"}},"member_portal_not_cancellable":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/member_portal_not_cancellable"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/contractors/{contractor_uuid}/member_portal_invitations":{"post":{"summary":"Create a contractor member portal invitation","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","description":"The UUID of the contractor","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-contractors-contractor_uuid-member_portal_invitations","security":[{"CompanyAccessAuth":[]}],"description":"Generates a member portal invitation for the specified contractor. If the contractor already has an invitation and its token has expired, calling this endpoint regenerates the invitation and overrides the prior token.\n\nscope: `member_portal_invitation:write`","tags":["Member Portal Invitations"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"Created"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"member_portal_member_info_incomplete_missing_email":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/member_portal_member_info_incomplete_missing_email"}},"member_portal_already_complete":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/member_portal_already_complete"}},"member_portal_not_eligible":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/member_portal_not_eligible"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}},"get":{"summary":"Get a contractor member portal invitation","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","description":"The UUID of the contractor","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-contractors-contractor_uuid-member_portal_invitations","security":[{"CompanyAccessAuth":[]}],"description":"Returns the current status of a contractor's member portal invitation (`pending`, `sent`, `verified`, `complete`, or `cancelled`) along with an `expired` flag indicating whether the invitation can still be acted on by the contractor.\n\nscope: `member_portal_invitation:read`","tags":["Member Portal Invitations"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"sent_invitation":{"value":{"$ref":"#/components/schemas/Member-Portal-Invitation/x-examples/sent_invitation"}},"complete_invitation":{"value":{"$ref":"#/components/schemas/Member-Portal-Invitation/x-examples/complete_invitation"}},"cancelled_invitation":{"value":{"$ref":"#/components/schemas/Member-Portal-Invitation/x-examples/cancelled_invitation"}}},"schema":{"$ref":"#/components/schemas/Member-Portal-Invitation"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"delete":{"summary":"Cancel a contractor member portal invitation","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"contractor_uuid","in":"path","description":"The UUID of the contractor","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-contractors-contractor_uuid-member_portal_invitations","security":[{"CompanyAccessAuth":[]}],"description":"Cancels the member portal invitation for the specified contractor.\n\nNote: this endpoint does not cancel the contractor's self-onboarding flow. If you want the company admin to take full control of onboarding the contractor, cancel the self-onboarding request instead.\n\nscope: `member_portal_invitation:write`","tags":["Member Portal Invitations"],"x-gusto-integration-type":["embedded"],"responses":{"204":{"description":"No Content"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"member_portal_already_cancelled":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/member_portal_already_cancelled"}},"member_portal_not_cancellable":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/member_portal_not_cancellable"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/notifications/{notification_uuid}":{"get":{"summary":"Get a notification's details","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"notification_uuid","in":"path","description":"The notification entity_uuid","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-notifications-notification_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Upon receiving a notification webhook event, use this endpoint to fetch the notification's details. The notification details include basic suggested content that can help you build notifications in your platform.\n\nNote: partners are responsible for the delivery and any custom state management of notifications in their application. Refer to our [partner notification guide](https://docs.gusto.com/embedded-payroll/docs/partner-notifications) for more details.\n\nIf the notification UUID is not found, the response will be 404 Not Found. If the notification's supporting data is no longer valid, the response will be 422 Unprocessable Entity.\n\nscope: `notifications:read`","tags":["Notifications"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"notification_show":{"value":{"$ref":"#/components/schemas/Notification/x-examples/notification_show"}},"transactional_mailer_notification_show":{"value":{"$ref":"#/components/schemas/Notification/x-examples/transactional_mailer_notification_show"}}},"schema":{"$ref":"#/components/schemas/Notification"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"notification_supporting_data_invalid":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/notification_supporting_data_invalid"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/companies/{company_uuid}/paid_holidays":{"get":{"summary":"Preview a company's paid holidays","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"year","in":"query","required":false,"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.","schema":{"type":"string","example":"2023"}}],"x-gusto-rswag":true,"operationId":"get-companies-company_uuid-paid_holidays","security":[{"CompanyAccessAuth":[]}],"description":"Preview a company's paid holidays\n\nIf a year is passed, paid holidays for that year will be returned. Otherwise, paid holidays for the next three years will be returned.\n\nscope: `holiday_pay_policies:read`","tags":["Holiday Pay Policies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":[{"$ref":"#/components/schemas/Paid-Holiday/x-examples/success_status"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Paid-Holiday"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"paid_holidays_invalid_year":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/paid_holidays_invalid_year"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/partner_managed_companies/{company_uuid}/disassociate":{"put":{"summary":"Disassociate a partner managed company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-partner-managed-companies-company-uuid-disassociate","security":[{"SystemAccessAuth":[]}],"description":"Disassociate a company from your embedded payroll product, reversing an earlier association or migration. You can only disassociate a company that is currently associated with your application.\n\n📘 System Access Authentication\n\nThis endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)\n\nscope: `partner_managed_companies:disassociate`","tags":["Companies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Partner-Managed-Company-Disassociate-Response/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Partner-Managed-Company-Disassociate-Response"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"partner_managed_company_disassociate_not_associated":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/partner_managed_company_disassociate_not_associated"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/partner_managed_companies/{company_uuid}/migrate":{"put":{"summary":"Migrate company to embedded payroll","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-partner-managed-companies-company-uuid-migrate","security":[{"CompanyAccessAuth":[]}],"description":"Migrate an existing Gusto customer to your embedded payroll product.\n\n### Prerequisites\nBefore calling this endpoint:\n1. The customer must connect their Gusto account to your application using [OAuth2](doc:oauth2)\n2. The customer must view and [accept the Embedded Payroll Terms of Service](ref:post-partner-managed-companies-company_uuid-accept_terms_of_service)\n\n### Related guides\n- [Migrate an existing company](doc:migrate-existing-company)\n\nscope: `partner_managed_companies:write`","tags":["Companies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Partner-Managed-Company-Migrate-Response/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Partner-Managed-Company-Migrate-Response"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"migrate_company_terms_of_service":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/migrate_company_terms_of_service"}},"migrate_company_already_migrated":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/migrate_company_already_migrated"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Partner-Managed-Company-Migrate-Request"}}},"required":true}}},"/v1/partner_managed_companies":{"post":{"summary":"Create a partner managed company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."}],"x-gusto-rswag":true,"operationId":"post-v1-partner-managed-companies","security":[{"SystemAccessAuth":[]}],"description":"Create a partner managed company. When you successfully call the API, it does the following:\n* Creates a new company in Gusto\n* Creates a new user using the provided email if the user does not already exist.\n* Makes the user the primary payroll administrator of the new company.\n\nIn response, you will receive oauth access tokens for the created company.\n\nIMPORTANT: the returned access and refresh tokens are reserved for this company only. They cannot be used to access other companies AND previously granted tokens cannot be used to access this company.\n\n📘 System Access Authentication\n\nThis endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)\n\nscope: `partner_managed_companies:manage`","tags":["Companies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Partner-Managed-Company/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Partner-Managed-Company"}}}},"422":{"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","content":{"application/json":{"examples":{"partner_managed_company_create_missing_company":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/partner_managed_company_create_missing_company"}},"partner_managed_company_create_invalid_name":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/partner_managed_company_create_invalid_name"}},"ein_collision":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/ein_collision"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Partner-Managed-Company-Create-Request"}}},"required":true}}},"/v1/partner_managed_companies/{company_uuid}/migration_readiness":{"get":{"summary":"Check company migration readiness","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-partner-managed-companies-company-uuid-migration_readiness","security":[{"CompanyAccessAuth":[]}],"description":"Check if an existing Gusto customer is ready to be migrated to embedded payroll. This endpoint returns blockers and warnings associated with migrating the company and is recommended to be called before attempting to migrate a company.\n\nscope: `partner_managed_companies:read`","tags":["Companies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Partner-Managed-Company-Migration-Readiness-Response/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Partner-Managed-Company-Migration-Readiness-Response"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/partner_managed_companies/{company_uuid}/accept_terms_of_service":{"post":{"summary":"Accept terms of service for an admin","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-partner-managed-companies-company_uuid-accept_terms_of_service","security":[{"CompanyAccessAuth":[]}],"deprecated":true,"description":"> Deprecated: use [POST /v1/partner_managed_companies/{company_uuid}/terms_of_service](https://docs.gusto.com/embedded-payroll/reference/post-v1-partner-managed-companies-company-uuid-terms_of_service).\n\nAccept the Gusto Embedded Payroll's [Terms of Service](https://flows.gusto.com/terms).\nThe user must be a company admin in order to accept the Terms of Service.\n\nscope: `terms_of_services:write`","tags":["Companies"],"x-gusto-integration-type":["embedded"],"responses":{"404":{"description":"Deprecated endpoint","content":{"application/json":{"examples":{"deprecated_accept_terms_of_service":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/deprecated_accept_terms_of_service"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Partner-Managed-Company-Accept-Terms-Of-Service-Request"}}},"required":true}}},"/v1/partner_managed_companies/{company_uuid}/retrieve_terms_of_service":{"post":{"summary":"Retrieve terms of service status for an admin","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-partner-managed-companies-company_uuid-retrieve_terms_of_service","security":[{"CompanyAccessAuth":[]}],"deprecated":true,"description":"> Deprecated: use [PUT /v1/partner_managed_companies/{company_uuid}/terms_of_service](https://docs.gusto.com/embedded-payroll/reference/put-v1-partner-managed-companies-company-uuid-terms_of_service) for user-level status, or [GET /v1/partner_managed_companies/{company_uuid}/terms_of_service](https://docs.gusto.com/embedded-payroll/reference/get-v1-partner-managed-companies-company-uuid-terms_of_service) for company-level status.\n\nRetrieve the user acceptance status of the Gusto Embedded Payroll's [Terms of Service](https://flows.gusto.com/terms).\n\nscope: `terms_of_services:read`","tags":["Companies"],"x-gusto-integration-type":["embedded"],"responses":{"404":{"description":"Deprecated endpoint","content":{"application/json":{"examples":{"deprecated_retrieve_terms_of_service":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/deprecated_retrieve_terms_of_service"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Partner-Managed-Company-Retrieve-Terms-Of-Service-Request"}}},"required":true}}},"/v1/partner_managed_companies/{company_uuid}/terms_of_service":{"get":{"summary":"Get the terms of service status for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-partner-managed-companies-company-uuid-terms_of_service","security":[{"CompanyAccessAuth":[]}],"description":"Check if any company payroll admin has accepted the Gusto Embedded Payroll's [Terms of Service](https://flows.gusto.com/terms).\n\nThis is useful for partners with multiple payroll admins who need to check TOS status at the company level rather than for a specific user.\n\nscope: `terms_of_services:read`","tags":["Companies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Partner-Managed-Company-Terms-Of-Service-Response/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Partner-Managed-Company-Terms-Of-Service-Response"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Check terms of service status for a specific user","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-partner-managed-companies-company-uuid-terms_of_service","security":[{"CompanyAccessAuth":[]}],"description":"Check user-specific Terms of Service acceptance for the Gusto Embedded Payroll [Terms of Service](https://flows.gusto.com/terms).\n\nThe user must have a role on the company. Returns whether the specific user has accepted the latest TOS version.\n\nUses PUT (rather than GET) to hide the email address from URL logs.\n\nscope: `terms_of_services:read`","tags":["Companies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Partner-Managed-Company-Terms-Of-Service-Response/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Partner-Managed-Company-Terms-Of-Service-Response"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"partner_managed_company_tos_invalid_user_email":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/partner_managed_company_tos_invalid_user_email"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Partner-Managed-Company-Retrieve-Terms-Of-Service-Request"}}},"required":true}},"post":{"summary":"Accept terms of service for a specific user","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-partner-managed-companies-company-uuid-terms_of_service","security":[{"CompanyAccessAuth":[]}],"description":"Accept the Gusto Embedded Payroll's [Terms of Service](https://flows.gusto.com/terms) on behalf of a specific user. The user must have a role on the company.\n\nscope: `terms_of_services:write`","tags":["Companies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Partner-Managed-Company-Terms-Of-Service-Response/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Partner-Managed-Company-Terms-Of-Service-Response"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"partner_managed_company_tos_invalid_ip_address":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/partner_managed_company_tos_invalid_ip_address"}},"partner_managed_company_tos_missing_external_user_id":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/partner_managed_company_tos_missing_external_user_id"}},"partner_managed_company_tos_invalid_user_email":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/partner_managed_company_tos_invalid_user_email"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Partner-Managed-Company-Accept-Terms-Of-Service-Request"}}},"required":true}}},"/v1/companies/{company_id}/pay_periods":{"get":{"summary":"Get pay periods for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"start_date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Start date (YYYY-MM-DD) for the pay periods range. Defaults to 6 months ago."},{"name":"end_date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"End date (YYYY-MM-DD) for the pay periods range. Cannot be more than 3 months in the future. Defaults to today."},{"name":"payroll_types","in":"query","required":false,"schema":{"type":"string","enum":["regular","transition","regular,transition"],"description":"Comma-separated list of payroll types to include (regular, transition). Defaults to regular only."}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-pay_periods","security":[{"CompanyAccessAuth":[]}],"description":"Pay periods are the foundation of payroll. Compensation, time & attendance, taxes, and expense reports all rely on when they happened.\n\nTo begin submitting information for a given payroll, we need to agree on the time period.\n\nBy default, this endpoint returns pay periods starting from 6 months ago to the date today. Use the `start_date` and `end_date` parameters to change the scope of the response. End dates can be up to 3 months in the future and there is no limit on start dates.\n\nStarting in version 2023-04-01, the `eligible_employees` attribute was removed from the response. The eligible employees for a payroll are determined by the employee_compensations returned from the [PUT /v1/companies/{company_id}/payrolls/{payroll_id}/prepare](ref:put-v1-companies-company_id-payrolls-payroll_id-prepare) endpoint.\n\nscope: `payrolls:read`","tags":["Payrolls"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"typical_pay_period":{"value":[{"$ref":"#/components/schemas/Pay-Period/x-examples/typical_pay_period"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Pay-Period"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"pay_periods_invalid_end_date":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/pay_periods_invalid_end_date"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/companies/{company_id}/pay_periods/unprocessed_termination_pay_periods":{"get":{"summary":"Get termination pay periods for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-unprocessed_termination_pay_periods","security":[{"CompanyAccessAuth":[]}],"description":"When a payroll admin terminates an employee and selects \"Dismissal Payroll\" as the employee's final payroll, their last pay period will appear on the list.\n\nThis endpoint returns the unprocessed pay periods for past and future terminated employees in a given company.\n\nscope: `payrolls:read`","tags":["Pay Schedules"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"typical_unprocessed_termination_pay_period":{"value":[{"$ref":"#/components/schemas/Unprocessed-Termination-Pay-Period/x-examples/typical_unprocessed_termination_pay_period"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Unprocessed-Termination-Pay-Period"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/companies/{company_id}/pay_schedules":{"get":{"summary":"Get the pay schedules for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-pay_schedules","security":[{"CompanyAccessAuth":[]}],"description":"Returns all pay schedules for a company. The pay schedule object captures the details of when employees work and when they should be paid. A company can have multiple pay schedules.\n\nscope: `pay_schedules:read`","tags":["Pay Schedules"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Pay-Schedule-Show-Response/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Pay-Schedule-Show-Response"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create a new pay schedule","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_id-pay_schedules","security":[{"CompanyAccessAuth":[]}],"description":"If a company does not have any pay schedules, this endpoint will create a single pay schedule and assign it to all employees. This is a common use case during company onboarding.\n\nIf a company has an existing active pay schedule and want to support multiple pay schedules, this endpoint will create a pay schedule that is not assigned to any employee.\n\nBe sure to **[check state laws](https://www.dol.gov/agencies/whd/state/payday)** to know what schedule is right for your customers.\n\n> If an onboarded company misses their first pay date, Gusto will automatically adjust the pay schedule to the next available pay date.\n\n### Webhooks\n- `pay_schedule.created`: Fires when a pay schedule is successfully created.\n\n### Related guides\n- [Create a pay schedule](doc:create-a-pay-schedule)\n- [Pay Schedules](doc:pay-schedule-info)\n- [Manage Pay Schedules via API](doc:manage-pay-schedules-api)\n\nscope: `pay_schedules:write`","tags":["Pay Schedules"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Pay-Schedule-Show/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Pay-Schedule-Show"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pay-Schedule-Create-Request"}}},"required":true}}},"/v1/companies/{company_id}/pay_schedules/preview":{"get":{"summary":"Preview pay schedule dates","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"frequency","in":"query","required":true,"schema":{"type":"string","enum":["Every week","Every other week","Twice per month","Monthly"],"example":"Twice per month"},"description":"The frequency that employees on this pay schedule are paid with Gusto."},{"name":"anchor_pay_date","in":"query","required":true,"schema":{"type":"string","format":"date","example":"2020-05-15"},"description":"The first date that employees on this pay schedule are paid with Gusto."},{"name":"anchor_end_of_pay_period","in":"query","required":true,"schema":{"type":"string","format":"date","example":"2020-05-08"},"description":"The last date of the first pay period. This can be the same date as the anchor pay date."},{"name":"day_1","in":"query","required":false,"schema":{"type":"integer","example":15},"description":"An integer between 1 and 31 indicating the first day of the month that employees are paid. This field is only relevant for pay schedules with the \"Twice per month\" and \"Monthly\" frequencies. It will be null for pay schedules with other frequencies."},{"name":"day_2","in":"query","required":false,"schema":{"type":"integer","example":31},"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, the second pay date is set to the last day of the month. It will be null for pay schedules with other frequencies."},{"name":"end_date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"End date for the preview range. If given, this date must be in the future. When unspecified, defaults to 18 months from today."},{"name":"pay_schedule_uuid","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Optional UUID of an existing pay schedule. When supplied, the preview is seeded from the persisted schedule — including internal flags (such as arrears handling) that affect period boundaries but are not exposed as request parameters. Any other query parameters override individual attributes on top of the loaded schedule."}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-pay_schedules-preview","security":[{"CompanyAccessAuth":[]}],"description":"Provides a preview of a pay schedule with the specified parameters for the next 18 months. Use this before creating or updating a pay schedule to show expected check dates, pay period boundaries, and payroll deadlines.\n\n### Related guides\n- [Create a pay schedule](doc:create-a-pay-schedule)\n- [Manage Pay Schedules via API](doc:manage-pay-schedules-api)\n\nscope: `pay_schedules:write`","tags":["Pay Schedules"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Pay-Schedule-Preview/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Pay-Schedule-Preview"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"pay_schedule_missing_anchor_dates":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/pay_schedule_missing_anchor_dates"}},"pay_schedule_malformed_dates":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/pay_schedule_malformed_dates"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/companies/{company_id}/pay_schedules/{pay_schedule_id}":{"get":{"summary":"Get a pay schedule","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"pay_schedule_id","in":"path","description":"The UUID of the pay schedule","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-pay_schedules-pay_schedule_id","security":[{"CompanyAccessAuth":[]}],"description":"Returns a single pay schedule by UUID. The pay schedule object in Gusto captures the details of when employees work and when they should be paid. A company can have multiple pay schedules.\n\nscope: `pay_schedules:read`","tags":["Pay Schedules"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Pay-Schedule-Show/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Pay-Schedule-Show"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update a pay schedule","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"pay_schedule_id","in":"path","description":"The UUID of the pay schedule","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-companies-company_id-pay_schedules-pay_schedule_id","security":[{"CompanyAccessAuth":[]}],"description":"Updates a pay schedule. The `version` parameter from the GET response is required for [optimistic concurrency](doc:api-fundamentals); a mismatch returns 409 Conflict.\n\n### Effect on payrolls\nUpdating a pay schedule will delete any unprocessed regular payrolls whose pay period end date is today or in the future. Already-processed payrolls are not affected.\n\n### Pay schedules may be automatically adjusted\nIf an onboarded company misses their first pay date, Gusto will automatically adjust the pay schedule to the next available pay date.\n\n### Webhooks\n- `pay_schedule.updated`: Fires when a pay schedule is successfully updated.\n\n### Related guides\n- [Create a pay schedule](doc:create-a-pay-schedule)\n- [Manage Pay Schedules via API](doc:manage-pay-schedules-api)\n\nscope: `pay_schedules:write`","tags":["Pay Schedules"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Pay-Schedule-Show/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Pay-Schedule-Show"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"409":{"description":"Conflict","content":{"application/json":{"examples":{"invalid_version":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_version"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pay-Schedule-Update-Request"}}},"required":true}}},"/v1/companies/{company_id}/pay_schedules/assignment_preview":{"post":{"summary":"Preview pay schedule assignments for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_id-pay_schedules-assignment_preview","security":[{"CompanyAccessAuth":[]}],"description":"This endpoint returns the employee changes, including pay period and transition pay periods, for changing the pay schedule.\n\nscope: `pay_schedules:write`","tags":["Pay Schedules"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Pay-Schedule-Assignment-Preview/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Pay-Schedule-Assignment-Preview"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pay-Schedule-Assignment-Body"}}},"required":true}}},"/v1/companies/{company_id}/pay_schedules/assign":{"post":{"summary":"Assign pay schedules for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_id-pay_schedules-assign","security":[{"CompanyAccessAuth":[]}],"description":"This endpoint assigns employees to pay schedules based on the schedule type.\nFor `by_employee` and `by_department` schedules, use the `partial_assignment` parameter to control the assignment scope. Set it to `true` for partial assignments (only some employees or departments at a time) and `false` for full assignments (all employees or departments at once).\n\nscope: `pay_schedules:write`","tags":["Pay Schedules"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"No Content"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pay-Schedule-Assignment-Body"}}},"required":true}}},"/v1/companies/{company_id}/pay_schedules/assignments":{"get":{"summary":"Get pay schedule assignments for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-pay_schedules-assignments","security":[{"CompanyAccessAuth":[]}],"description":"This endpoint returns the current pay schedule assignment for a company, with pay schedule and employee/department mappings depending on the pay schedule type.\n\nscope: `pay_schedules:read`","tags":["Pay Schedules"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Pay-Schedule-Assignment/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Pay-Schedule-Assignment"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/employees/{employee_id}/pay_stubs":{"get":{"summary":"Get an employee's pay stubs","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_uuid-pay_stubs","security":[{"CompanyAccessAuth":[]}],"description":"Get an employee's pay stubs.\n\nResults are returned in reverse chronological order (newest first).\n\nscope: `pay_stubs:read`","x-gusto-integration-type":["embedded"],"tags":["Payrolls"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee-Pay-Stubs-List/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee-Pay-Stubs-List"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/payrolls/{payroll_id}/employees/{employee_id}/pay_stub":{"get":{"summary":"Get an employee pay stub (pdf)","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"payroll_id","in":"path","description":"The UUID of the payroll","required":true,"schema":{"type":"string"}},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-payrolls-payroll_uuid-employees-employee_uuid-pay_stub","security":[{"CompanyAccessAuth":[]}],"description":"Get an employee's pay stub for the specified payroll. By default, an application/pdf response will be returned. No other content types are currently supported, but may be supported in the future.\n\nscope: `pay_stubs:read`","tags":["Payrolls"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful"},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/companies/{company_id}/payrolls/{id}/partner_disbursements":{"get":{"summary":"Get partner disbursements for a payroll","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","description":"The UUID of the payroll","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-payrolls-id-partner_disbursements","security":[{"CompanyAccessAuth":[]}],"description":"Get partner disbursements for a specific payroll.\n\nscope: `partner_disbursements:read`","tags":["Payrolls"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Payroll-Partner-Disbursements/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Payroll-Partner-Disbursements"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"patch":{"summary":"Update partner disbursements for a payroll","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","description":"The UUID of the payroll","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"patch-v1-companies-company_id-payrolls-id-partner_disbursements","security":[{"CompanyAccessAuth":[]}],"description":"Update partner disbursements for a specific payroll.\n\nscope: `partner_disbursements:write`","tags":["Payrolls"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Payroll-Partner-Disbursements/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Payroll-Partner-Disbursements"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"mixed single and multiple errors example","content":{"application/json":{"examples":{"nested_disbursement_errors":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/nested_disbursement_errors"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"disbursements":{"type":"array","items":{"type":"object","properties":{"employee_uuid":{"type":"string","description":"UUID of the employee","example":"1a2b3c4d-5e6f-7890-abcd-ef1234567890"},"payment_method":{"type":"string","enum":["Direct Deposit","Check"],"description":"Payment method for the employee"},"payment_status":{"type":"string","enum":["Pending","Paid","Not partner managed","Converted to check"],"description":"Status of the payment disbursement"}},"required":["employee_uuid"]}}},"required":["disbursements"]}}}}}},"/v1/payroll_batches":{"post":{"summary":"Create a payroll cancellation batch","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."}],"x-gusto-rswag":true,"operationId":"post-v1-payroll_batches","security":[{"SystemAccessAuth":[]}],"description":"Cancels up to 100 payrolls across one or more companies the partner is mapped to, asynchronously.\n\nThe batch is processed asynchronously. Use the returned batch UUID to poll `GET /v1/payroll_batches/{payroll_batch_uuid}` for status and per-payroll results.\n\nEach item carries the payroll `uuid` and the `company_uuid` that owns it. A payroll whose company is not mapped to the partner — or that doesn't exist — is recorded as a `not_found` exclusion rather than a hard error, so every requested UUID lands in either `results` or `exclusions`.\n\nIdempotency is scoped per `(partner, idempotency_key)`. A duplicate POST with the same `idempotency_key` returns a 409 Conflict referencing the existing batch UUID — no duplicate processing occurs.\n\n📘 System Access Authentication\n\nThis endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)\n\nscope: `payroll_batches:write`","tags":["Payroll Cancellations"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"created","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Payroll-Batch/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Payroll-Batch"}}}},"409":{"description":"conflict - idempotency key already used by this partner","content":{"application/json":{"examples":{"conflict":{"value":{"$ref":"#/components/schemas/Payroll-Batch-Conflict-Error/x-examples/conflict"}}},"schema":{"$ref":"#/components/schemas/Payroll-Batch-Conflict-Error"}}}},"422":{"description":"unprocessable entity - validation errors","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["idempotency_key","batch_action","batch"],"properties":{"idempotency_key":{"type":"string","format":"uuid","description":"A partner-generated unique identifier to ensure idempotency of the batch request. Scoped per partner.","example":"80a74f8b-2c16-45e5-9038-aa108849c6e6"},"batch_action":{"type":"string","enum":["cancel"],"description":"The action to perform on the batch. Only `cancel` is supported.","example":"cancel"},"batch":{"type":"array","description":"Array of payrolls to cancel. Maximum 100 payrolls per request.","minItems":1,"maxItems":100,"items":{"type":"object","required":["entity_type","uuid","company_uuid"],"properties":{"entity_type":{"type":"string","enum":["payroll"],"description":"The type of entity to act on.","example":"payroll"},"uuid":{"type":"string","format":"uuid","description":"The UUID of the payroll to cancel. Payrolls the partner is not authorized to access, or that do not exist, appear in the response's `exclusions` array."},"company_uuid":{"type":"string","format":"uuid","description":"The UUID of the company that owns the payroll. The partner must be mapped to this company."}}}}}}}},"required":true}}},"/v1/payroll_batches/{payroll_batch_uuid}":{"get":{"summary":"Get a payroll cancellation batch","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"payroll_batch_uuid","in":"path","description":"The UUID of the payroll cancellation batch returned by `POST /v1/payroll_batches`.","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-payroll_batches-payroll_batch_uuid","security":[{"SystemAccessAuth":[]}],"description":"Returns the status and per-payroll results of a payroll cancellation batch.\n\nPoll this endpoint until the batch `status` reaches a terminal value (`completed` or `failed`). Once terminal, the response includes the `results` array (one entry per authorized payroll, each with its own per-payroll `status` — `success` or `failed`) and the `exclusions` array (one entry per payroll that could not be processed). A cancel is atomic, so a per-payroll result is only ever `success` or `failed` — never `partial_success`.\n\nNote that the top-level batch `status` (`pending` / `processing` / `completed` / `failed`) is the request lifecycle, distinct from the per-payroll `status` inside `results[]`. A `completed` batch does not imply every payroll was cancelled — inspect the array for per-payroll outcomes.\n\nResults are stored in Redis with a limited TTL after completion. If the partner polls after results have expired, this endpoint returns 410 Gone — partners should re-submit a new batch.\n\n📘 System Access Authentication\n\nThis endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)\n\nscope: `payroll_batches:read`","tags":["Payroll Cancellations"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Payroll-Batch-Results/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Payroll-Batch-Results"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"410":{"description":"Gone - results have expired from Redis","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/payroll_digests":{"post":{"summary":"Create a payroll digest batch","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."}],"x-gusto-rswag":true,"operationId":"post-v1-payroll_digests","security":[{"SystemAccessAuth":[]}],"description":"Triggers an asynchronous computation of payroll digest data (statuses, blockers, pay periods, totals) across up to 25 companies that the partner is mapped to.\n\nThe batch is processed asynchronously. Use the returned batch UUID to poll `GET /v1/payroll_digests/{payroll_digest_uuid}` for status and results.\n\nIdempotency is scoped per `(partner, idempotency_key)`. A duplicate POST with the same `idempotency_key` returns a 409 Conflict referencing the existing batch UUID — no duplicate computation occurs.\n\n📘 System Access Authentication\n\nThis endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)\n\nscope: `payroll_digests:write`","tags":["Payroll Digests"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"created","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Payroll-Digest/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Payroll-Digest"}}}},"409":{"description":"conflict - idempotency key already used by this partner","content":{"application/json":{"examples":{"conflict":{"value":{"$ref":"#/components/schemas/Payroll-Digest-Conflict-Error/x-examples/conflict"}}},"schema":{"$ref":"#/components/schemas/Payroll-Digest-Conflict-Error"}}}},"422":{"description":"unprocessable entity - validation errors","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["idempotency_key","batch_action","batch"],"properties":{"idempotency_key":{"type":"string","format":"uuid","description":"A partner-generated unique identifier to ensure idempotency of the batch request. Scoped per partner.","example":"80a74f8b-2c16-45e5-9038-aa108849c6e6"},"batch_action":{"type":"string","enum":["create"],"description":"The action to perform on the batch.","example":"create"},"batch":{"type":"array","description":"Array of companies to fetch payroll digest data for. Maximum 25 companies per request.","minItems":1,"maxItems":25,"items":{"type":"object","required":["entity_type","uuid"],"properties":{"entity_type":{"type":"string","enum":["company"],"description":"The type of entity to look up.","example":"company"},"uuid":{"type":"string","format":"uuid","description":"The UUID of a company that the partner is mapped to. Companies that the partner is not authorized to access will appear in the response's `exclusions` array."}}}}}}}},"required":true}}},"/v1/payroll_digests/{payroll_digest_uuid}":{"get":{"summary":"Get a payroll digest batch","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"payroll_digest_uuid","in":"path","description":"The UUID of the payroll digest batch returned by `POST /v1/payroll_digests`.","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-payroll_digests-payroll_digest_uuid","security":[{"SystemAccessAuth":[]}],"description":"Returns the status and results of a payroll digest batch.\n\nPoll this endpoint until the batch `status` reaches a terminal value (`completed` or `failed`). Once terminal, the response includes the full `results` array (one entry per attempted company, each with its own per-company `status` — `success`, `partial_success`, or `failed`) and the `exclusions` array (one entry per company that could not be looked up or processed).\n\nNote that the top-level batch `status` (`pending` / `processing` / `completed` / `failed`) is distinct from the per-company `status` returned inside `results[]` and `exclusions[]`. A `completed` batch does not imply every company succeeded — inspect the arrays for per-company outcomes.\n\nResults are stored in Redis with a short TTL after completion. If the partner polls after results have expired, this endpoint returns 410 Gone — partners should re-submit a new batch to fetch fresh data.\n\n📘 System Access Authentication\n\nThis endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)\n\nscope: `payroll_digests:read`","tags":["Payroll Digests"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Payroll-Digest-Results/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Payroll-Digest-Results"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"410":{"description":"Gone - results have expired from Redis","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/companies/{company_id}/payroll_reversals":{"get":{"summary":"Get approved payroll reversals","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-payroll_reversals","security":[{"CompanyAccessAuth":[]}],"description":"Returns all approved Payroll Reversals for a Company.\n\nscope: `payrolls:read`","tags":["Payrolls"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Example response","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Payroll-Reversal-List/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Payroll-Reversal-List"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/companies/{company_id}/payrolls/{payroll_id}":{"get":{"summary":"Get a single payroll","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"payroll_id","in":"path","description":"The UUID of the payroll","required":true,"schema":{"type":"string"}},{"name":"include","in":"query","explode":false,"required":false,"schema":{"type":"array","items":{"type":"string","enum":["benefits","deductions","taxes","payroll_status_meta","totals","risk_blockers","reversals","payroll_taxes"]}},"description":"Include the requested attribute in the response, for multiple attributes comma separate the values, i.e. `?include=benefits,deductions,taxes`"},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","pattern":"^(first_name|last_name)(:(asc|desc))?(,(first_name|last_name)(:(asc|desc))?)*$","example":"first_name:asc"},"description":"Sort employee compensations by one or more fields. Options: first_name, last_name. Append `:asc` or `:desc` to specify direction (e.g., `last_name:asc` or `last_name:asc,first_name:asc`). Defaults to ascending."}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-payrolls-payroll_id","security":[{"CompanyAccessAuth":[]}],"description":"Returns a payroll. If payroll is calculated or processed, will return employee_compensations and totals.\n\nResults are paginated, with a maximum page size of 100 employee_compensations.\n\nNotes:\n* Hour and dollar amounts are returned as string representations of numeric decimals.\n* Hours are represented to the thousands place; dollar amounts are represented to the cent.\n* Every eligible compensation is returned for each employee. If no data has yet be inserted for a given field, it defaults to \"0.00\" (for fixed amounts) or \"0.000\" (for hours ).\n* When include parameter with benefits value is passed, employee_benefits:read scope is required to return benefits\n  * Benefits containing PHI are only visible with the `employee_benefits:read:phi` scope\n\nscope: `payrolls:read`","tags":["Payrolls"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful with wait_for_reverse_wire credit blocker","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Payroll-Show/x-examples/success_status"}},"with_submit_wire_credit_blocker":{"value":{"$ref":"#/components/schemas/Payroll-Show/x-examples/with_submit_wire_credit_blocker"}},"with_submit_bank_screenshot_credit_blocker":{"value":{"$ref":"#/components/schemas/Payroll-Show/x-examples/with_submit_bank_screenshot_credit_blocker"}},"with_respond_to_high_risk_fraud_rfi_credit_blocker":{"value":{"$ref":"#/components/schemas/Payroll-Show/x-examples/with_respond_to_high_risk_fraud_rfi_credit_blocker"}},"with_wait_for_reverse_wire_credit_blocker":{"value":{"$ref":"#/components/schemas/Payroll-Show/x-examples/with_wait_for_reverse_wire_credit_blocker"}}},"schema":{"$ref":"#/components/schemas/Payroll-Show"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update a payroll by ID","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"payroll_id","in":"path","description":"The UUID of the payroll","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-companies-company_id-payrolls","security":[{"CompanyAccessAuth":[]}],"description":"This endpoint allows you to update information for one or more employees for a specific **unprocessed** payroll.  You can think of the **unprocessed**\npayroll object as a template of fields that you can update.  You cannot modify the structure of the payroll object through this endpoint, only values\nof the fields included in the payroll.  If you do not include specific employee compensations, fixed/hourly compensations, or deductions in your request body, they\nwill not be removed from the payroll. A maximum of 100 employee_compensations can be updated at a time. Only the employee compensation objects that were\ninputted will be returned.\n\nscope: `payrolls:write`","tags":["Payrolls"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Payroll-Prepared/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Payroll-Prepared"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"409":{"description":"Conflict","content":{"application/json":{"examples":{"payroll_update_stale_employee_compensation_version":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/payroll_update_stale_employee_compensation_version"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}},"payroll_update_payroll_item_validation_error":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/payroll_update_payroll_item_validation_error"}},"payroll_update_recurring_reimbursement_error":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/payroll_update_recurring_reimbursement_error"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payroll-Update"}}},"required":true}},"delete":{"summary":"Delete a payroll","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"payroll_id","in":"path","description":"The UUID of the payroll","required":true,"schema":{"type":"string"}},{"name":"async","in":"query","description":"When true, request an asynchronous delete of the payroll.","schema":{"type":"boolean"}}],"x-gusto-rswag":true,"operationId":"delete-v1-companies-company_id-payrolls","security":[{"CompanyAccessAuth":[]}],"description":"This endpoint allows you to delete an **unprocessed** payroll.\n\nBy default the payroll and associated data is deleted synchronously. To request an asynchronous delete, use the `async=true` query parameter. In both cases validation of ability to delete will be performed and an Unprocessable Entity error will be returned if the payroll is not able to be deleted. A successful synchronous delete will return `204/No Content`. When a payroll has been enqueued for asynchronous deletion, `202/Accepted` will be returned.\n\nscope: `payrolls:run`","tags":["Payrolls"],"x-gusto-integration-type":["embedded"],"responses":{"202":{"description":"Accepted"},"204":{"description":"no content"},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/companies/{company_id}/payrolls":{"get":{"summary":"Get all payrolls for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"processing_statuses","in":"query","required":false,"explode":false,"description":"Whether to include processed and/or unprocessed payrolls in the response, defaults to processed, for multiple attributes comma separate the values, i.e. `?processing_statuses=processed,unprocessed`","schema":{"type":"array","items":{"type":"string","enum":["processed","unprocessed"]}}},{"name":"payroll_types","in":"query","required":false,"explode":false,"description":"Whether to include regular and/or off_cycle payrolls in the response, defaults to regular, for multiple attributes comma separate the values, i.e. `?payroll_types=regular,off_cycle`","schema":{"type":"array","items":{"type":"string","enum":["regular","off_cycle","external"]}}},{"name":"processed","in":"query","required":false,"description":"Whether to return processed or unprocessed payrolls","schema":{"type":"boolean"}},{"name":"include_off_cycle","in":"query","required":false,"description":"Whether to include off cycle payrolls in the response","schema":{"type":"boolean"}},{"name":"include","in":"query","explode":false,"required":false,"schema":{"type":"array","items":{"type":"string","enum":["taxes","payroll_status_meta","totals","risk_blockers","reversals"]}},"description":"Include the requested attribute in the response, for multiple attributes comma separate the values, i.e. `?include=benefits,deductions,taxes`"},{"name":"start_date","in":"query","required":false,"example":"2020-01-31","description":"Return payrolls whose pay period is after the start date","schema":{"type":"string"}},{"name":"end_date","in":"query","required":false,"example":"2020-01-31","description":"Return payrolls whose pay period is before the end date. If left empty, defaults to today's date.","schema":{"type":"string"}},{"name":"date_filter_by","in":"query","required":false,"description":"Specifies which date field to use when filtering payrolls with start_date and end_date. This field applies only to regular processed payrolls and defaults to pay period if not provided.","schema":{"type":"string","enum":["check_date"]},"example":"check_date"},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}},{"name":"sort_order","in":"query","required":false,"description":"A string indicating whether to sort resulting events in ascending (asc) or descending (desc) chronological order. Events are sorted by their `timestamp`. Defaults to asc if left empty.","schema":{"type":"string","enum":["asc","desc"]},"example":"asc"}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_id-payrolls","security":[{"CompanyAccessAuth":[]}],"description":"Returns a list of payrolls for a company. You can change the payrolls returned by updating the processing_status, payroll_types, start_date, & end_date params.\n\nBy default, will return processed, regular payrolls for the past 6 months.\n\nNotes:\n* Dollar amounts are returned as string representations of numeric decimals, are represented to the cent.\n* end_date can be at most 3 months in the future and start_date and end_date can't be more than 1 year apart.\n* Results are paginated. Maximum page size is 100 payrolls per request; the default page size is 25.\n\nscope: `payrolls:read`","tags":["Payrolls"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Payroll-List/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Payroll-List"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create an off-cycle payroll","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_id-payrolls","security":[{"CompanyAccessAuth":[]}],"description":"Creates a new, unprocessed, off-cycle payroll.\n\n## `off_cycle_reason`\nBy default:\n- External benefits and deductions will be included when the `off_cycle_reason` is set to `Correction`.\n- All benefits and deductions are blocked when the `off_cycle_reason` is set to `Bonus`.\n\nThese elections can be overridden with the `skip_regular_deductions` boolean.\n\nscope: `payrolls:run`","tags":["Payrolls"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Payroll-Unprocessed/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Payroll-Unprocessed"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}},"employee_uuids_required":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/employee_uuids_required"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["off_cycle","off_cycle_reason","start_date","end_date"],"properties":{"off_cycle":{"type":"boolean","description":"Whether it is an off cycle payroll."},"off_cycle_reason":{"type":"string","enum":["Bonus","Correction","Adhoc","Dismissed employee","Transition from old pay schedule"],"description":"An off cycle payroll reason. Select one from the following list."},"start_date":{"type":"string","format":"date","description":"Pay period start date."},"end_date":{"type":"string","format":"date","description":"Pay period end date."},"pay_schedule_uuid":{"description":"A pay schedule is required for transition from old pay schedule payroll to identify the matching transition pay period.","type":"string"},"employee_uuids":{"description":"A list of employee UUIDs to include on the payroll. At least one UUID is required for non-termination off-cycle payrolls.","type":"array","minItems":1,"items":{"type":"string"}},"check_date":{"type":"string","format":"date","description":"Payment date."},"withholding_pay_period":{"description":"The payment schedule tax rate the payroll is based on.","type":"string","enum":["Every week","Every other week","Twice per month","Monthly","Quarterly","Semiannually","Annually"]},"skip_regular_deductions":{"description":"Block regular deductions and contributions for this payroll.","type":"boolean"},"fixed_withholding_rate":{"description":"Enable taxes to be withheld at the IRS's required rate of 22% for federal income taxes. State income taxes will be taxed at the state's supplemental tax rate. Otherwise, we'll sum the entirety of the employee's wages and withhold taxes on the entire amount at the rate for regular wages.","type":"boolean"},"is_check_only_payroll":{"description":"When true, all employees in the payroll will be paid by check and the check date can be set to today or any future business day (rather than requiring ACH lead time). Payment methods cannot be changed on check-only payrolls.","type":"boolean"}}}}}}}},"/v1/payrolls/{payroll_uuid}/receipt":{"get":{"summary":"Get a single payroll receipt","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"payroll_uuid","in":"path","description":"The UUID of the payroll","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-payment-receipts-payrolls-payroll_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Returns a payroll receipt.\n\nNotes:\n* Hour and dollar amounts are returned as string representations of numeric decimals.\n* Dollar amounts are represented to the cent.\n* If no data has yet be inserted for a given field, it defaults to \"0.00\" (for fixed amounts).\n* Results are paginated. Maximum page size is 100 employee compensations per request.\n\nscope: `payrolls:read`","tags":["Payrolls"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Payroll-Receipt/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Payroll-Receipt"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/companies/{company_id}/payrolls/{payroll_id}/cancel":{"put":{"summary":"Cancel a payroll","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"payroll_id","in":"path","description":"The UUID of the payroll","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-api-v1-companies-company_id-payrolls-payroll_id-cancel","security":[{"CompanyAccessAuth":[]}],"description":"Transitions a `processed` payroll back to the `unprocessed` state. A payroll can be canceled if it meets both criteria:\n\n- `processed` is `true`\n- Current time is earlier than 4pm PT on the `payroll_deadline`\n\nscope: `payrolls:run`","tags":["Payrolls"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Unprocessed-Payroll/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Unprocessed-Payroll"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"payroll_cannot_cancel":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/payroll_cannot_cancel"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/companies/{company_id}/payrolls/{payroll_id}/prepare":{"put":{"summary":"Prepare a payroll for update","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"payroll_id","in":"path","description":"The UUID of the payroll","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","pattern":"^(first_name|last_name)(:(asc|desc))?(,(first_name|last_name)(:(asc|desc))?)*$","example":"first_name:asc"},"description":"Sort employee compensations by one or more fields. Options: first_name, last_name. Append `:asc` or `:desc` to specify direction (e.g., `last_name:asc` or `last_name:asc,first_name:asc`). Defaults to ascending."}],"x-gusto-rswag":true,"operationId":"put-v1-companies-company_id-payrolls-payroll_id-prepare","security":[{"CompanyAccessAuth":[]}],"description":"Prepares an unprocessed payroll for update, including: adding or removing eligible employees from the payroll,\nand updating `check_date`, `payroll_deadline`, and `payroll_status_meta` dates and times.\n\nUse this endpoint before calling [PUT /v1/companies/{company_id}/payrolls/{payroll_id}](ref:put-v1-companies-company_id-payrolls).\n\n### Notes\n\n* Nullifies `calculated_at` and `totals` if the payroll was previously calculated\n* Returns the `version` parameter required for [updating the payroll](ref:put-v1-companies-company_id-payrolls)\n* `employees:read` scope is required to include employee compensations data in the response.\n* Results are paginated, with a maximum page size of 100 employee compensations.\n\nscope: `payrolls:write employees:read`","tags":["Payrolls"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Payroll-Prepared/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Payroll-Prepared"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"frozen_payroll":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/frozen_payroll"}},"frozen_payroll_processing":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/frozen_payroll_processing"}},"unmodifiable_payroll_type":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/unmodifiable_payroll_type"}},"invalid_employee_uuids_format":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_employee_uuids_format"}},"maximum_employee_uuids_surpassed":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/maximum_employee_uuids_surpassed"}},"invalid_employee_uuid":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_employee_uuid"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"employee_uuids":{"type":["array","null"],"description":"An array of employee UUIDs. If passed, only those employees payroll items will be prepared.","items":{"type":"string"}}}}}}}}},"/v1/companies/{company_id}/payrolls/{payroll_id}/calculate":{"put":{"summary":"Calculate a payroll","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"payroll_id","in":"path","description":"The UUID of the payroll","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-companies-company_id-payrolls-payroll_id-calculate","security":[{"CompanyAccessAuth":[]}],"description":"Performs calculations for taxes, benefits, and deductions for an unprocessed payroll. The calculated payroll details provide a preview of the actual values that will be used when the payroll is run.\n\nThis calculation is asynchronous and a successful request responds with a 202 HTTP status. To view the details of the calculated payroll, use the GET /v1/companies/{company_id}/payrolls/{payroll_id} endpoint with *include=taxes,benefits,deductions* params.\n\nIf the company is blocked from running payroll due to issues like incomplete setup, missing information or other compliance issues, the response will be 422 Unprocessable Entity with a categorization of the blockers as described in the error responses.\n\nscope: `payrolls:run`","tags":["Payrolls"],"x-gusto-integration-type":["embedded"],"responses":{"202":{"description":"Accepted"},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"unmodifiable_payroll_type":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/unmodifiable_payroll_type"}},"payroll_blocker_missing_bank_info":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/payroll_blocker_missing_bank_info"}},"payroll_blocker_missing_employee_setup":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/payroll_blocker_missing_employee_setup"}},"payroll_blocker_missing_federal_tax_setup":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/payroll_blocker_missing_federal_tax_setup"}},"payroll_blocker_missing_bank_verification":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/payroll_blocker_missing_bank_verification"}},"payroll_blocker_suspended":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/payroll_blocker_suspended"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/companies/{company_uuid}/payrolls/blockers":{"get":{"summary":"Get all payroll blockers for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-payroll-blockers-company_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Returns a list of reasons that prevent the company from running payrolls. See the [Payroll Blockers guide](doc:payroll-blockers) for a complete list of reasons. The list is empty if there are no payroll blockers.\n\nscope: `payrolls:run`","tags":["Payrolls"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"blockers_list":{"value":[{"$ref":"#/components/schemas/Payroll-Blocker/x-examples/blockers_list"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Payroll-Blocker"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/companies/{company_uuid}/payrolls/skip":{"post":{"summary":"Skip a payroll","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-companies-payroll-skip-company_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Submits a $0 payroll for employees associated with the pay schedule to skip payroll. This submission is asynchronous and a successful request responds with a 202 HTTP status. Upon success, the payroll is transitioned to the `processed` state.\n\nIf the company is blocked from running payroll due to issues like incomplete setup, missing information or other compliance issues, the response will be 422 Unprocessable Entity with a categorization of the blockers as described in the error responses.\n\nscope: `payrolls:run`","tags":["Payrolls"],"x-gusto-integration-type":["embedded"],"responses":{"202":{"description":"Accepted"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"skip_payroll_invalid_payroll_type":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/skip_payroll_invalid_payroll_type"}},"needs_onboarding":{"value":{"$ref":"#/components/schemas/Payroll-Blockers-Error/x-examples/needs_onboarding"}}},"schema":{"$ref":"#/components/schemas/Payroll-Blockers-Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payroll_type":{"type":"string","description":"Payroll type","enum":["Regular","Hired employee","Dismissed employee","Transition from old pay schedule"]},"start_date":{"type":"string","description":"Pay period start date"},"end_date":{"type":"string","description":"Pay period end date. If left empty, defaults to today's date. Required when skipping a termination payroll (`payroll_type` = `Dismissed employee`)."},"pay_schedule_uuid":{"type":"string","description":"The UUID of the pay schedule. Required when skipping a termination payroll (`payroll_type` = `Dismissed employee`)."},"employee_uuids":{"description":"An array of employees. This field is only applicable to new hire payroll and termination payroll","type":["array","null"],"items":{"type":"string"}}},"required":["payroll_type"]}}},"required":true}}},"/v1/companies/{company_id}/payrolls/{payroll_id}/submit":{"put":{"summary":"Submit payroll","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"payroll_id","in":"path","description":"The UUID of the payroll","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-companies-company_id-payrolls-payroll_id-submit","security":[{"CompanyAccessAuth":[]}],"description":"Submits an unprocessed payroll to be calculated and run. This submission is asynchronous and a successful request responds with a 202 HTTP status. Upon success, transitions the payroll to the `processed` state.\n\nYou should poll to ensure that payroll is processed successfully, as async errors only occur after async processing is complete.\n\nIf the company is blocked from running payroll due to issues like incomplete setup, missing information or other compliance issues, the response will be 422 Unprocessable Entity with a categorization of the blockers as described in the error responses.\n\nscope: `payrolls:run`","tags":["Payrolls"],"x-gusto-integration-type":["embedded"],"responses":{"202":{"description":"Accepted"},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"unmodifiable_payroll_type":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/unmodifiable_payroll_type"}},"payroll_blocker_missing_bank_info":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/payroll_blocker_missing_bank_info"}},"payroll_blocker_missing_employee_setup":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/payroll_blocker_missing_employee_setup"}},"payroll_blocker_missing_federal_tax_setup":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/payroll_blocker_missing_federal_tax_setup"}},"payroll_blocker_missing_bank_verification":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/payroll_blocker_missing_bank_verification"}},"payroll_blocker_suspended":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/payroll_blocker_suspended"}},"submission_blocker_missing_selection":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/submission_blocker_missing_selection"}},"submission_blocker_invalid_option":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/submission_blocker_invalid_option"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"submission_blockers":{"type":"array","description":"An array of submission_blockers, each with a selected unblock option.","items":{"$ref":"#/components/schemas/Payroll-Submission-Blocker-Request-Type"}}}}}}}}},"/v1/payrolls/{payroll_uuid}/gross_up":{"post":{"summary":"Calculate gross up for a payroll","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"payroll_uuid","in":"path","description":"The UUID of the payroll","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-payrolls-gross-up-payroll_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Calculates gross up earnings for an employee's payroll, given net earnings. This endpoint is only applicable to off-cycle unprocessed payrolls.\n\nThe gross up amount must then be mapped to the corresponding fixed compensation earning type to get the correct payroll amount. For example, for bonus off-cycles, the gross up amount should be set with the Bonus earning type in the payroll `fixed_compensations` field.\n\nscope: `payrolls:run`","tags":["Payrolls"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Payroll-Gross-Up-Response/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Payroll-Gross-Up-Response"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"payroll_gross_up_invalid_net_pay":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/payroll_gross_up_invalid_net_pay"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payroll-Gross-Up-Request"}}},"required":true}}},"/v1/payrolls/{payroll_id}/employees/{employee_id}/calculate_accruing_time_off_hours":{"post":{"summary":"Calculate accruing time off hours","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"payroll_id","in":"path","description":"The UUID of the payroll","required":true,"schema":{"type":"string"}},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-payrolls-payroll_id-calculate_accruing_time_off_hours","security":[{"CompanyAccessAuth":[]}],"description":"Returns a list of accruing time off for each time off policy associated with the employee.\n\nFactors affecting the accrued hours:\n\n- the time off policy accrual method (whether they get pay per hour worked, per hour paid, with / without overtime, accumulate time off based on pay period / calendar year / anniversary)\n- how many hours of work during this pay period\n- how many hours of PTO / sick hours taken during this pay period (for per hour paid policies only)\n- company pay schedule frequency (for per pay period)\n\nIf none of the parameters is passed in, the accrued time off hour will be 0.\n\nscope: `payrolls:read`","tags":["Time Off Policies"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Payroll-Calculate-Accruing-Time-Off-Hours-Response/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Payroll-Calculate-Accruing-Time-Off-Hours-Response"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"payroll_accruing_hours_invalid":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/payroll_accruing_hours_invalid"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payroll-Calculate-Accruing-Time-Off-Hours-Request"}}}}}},"/v1/companies/{company_id}/people_batches":{"post":{"summary":"Create a people batch","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_id","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_id-people_batches","security":[{"CompanyAccessAuth":[]}],"description":"Creates a batch for bulk employee creation.\n\nThe batch is processed asynchronously. Use the returned batch UUID to poll for status and results.\n\nscope: `people_batches:write`","tags":["People Batches"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"created","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/People-Batch/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/People-Batch"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"409":{"description":"conflict - idempotency key already used","content":{"application/json":{"examples":{"conflict":{"value":{"$ref":"#/components/schemas/People-Batch-Conflict-Error/x-examples/conflict"}}},"schema":{"$ref":"#/components/schemas/People-Batch-Conflict-Error"}}}},"422":{"description":"unprocessable entity - validation errors","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["idempotency_key","batch_action","batch"],"properties":{"idempotency_key":{"type":"string","format":"uuid","description":"A unique identifier to ensure idempotency of the batch request","example":"550e8400-e29b-41d4-a716-446655440000"},"batch_action":{"type":"string","enum":["create"],"description":"The action to perform on the batch","example":"create"},"batch":{"type":"array","description":"Array of people to create","items":{"type":"object","required":["entity_type","person"],"properties":{"entity_type":{"type":"string","enum":["employee"],"description":"The type of entity to create","example":"employee"},"person":{"type":"object","required":["external_id","first_name","last_name"],"properties":{"external_id":{"type":"string","description":"External identifier for the person"},"first_name":{"type":"string","description":"Legal first name"},"last_name":{"type":"string","description":"Legal last name"},"middle_initial":{"type":["string","null"],"maxLength":1,"minLength":1,"description":"Middle initial"},"preferred_first_name":{"type":["string","null"],"description":"Preferred first name"},"email":{"type":["string","null"],"format":"email","description":"Personal email address"},"work_email":{"type":["string","null"],"format":"email","description":"Work email address"},"ssn":{"type":["string","null"],"description":"Social Security Number (format: xxx-xx-xxxx)"},"date_of_birth":{"type":["string","null"],"format":"date","description":"Date of birth (YYYY-MM-DD)"},"self_onboarding":{"type":["boolean","null"],"description":"Whether the employee will complete their own onboarding"}}},"home_address":{"type":"object","description":"Home address for the employee","required":["street_1","city","state","zip"],"properties":{"street_1":{"type":"string","description":"Street address line 1"},"street_2":{"type":"string","description":"Street address line 2"},"city":{"type":"string","description":"City"},"state":{"type":"string","description":"State abbreviation"},"zip":{"type":"string","description":"ZIP code"},"country":{"type":"string","description":"Country (defaults to USA)"},"work_from_home":{"type":"boolean","description":"If true, a company work address will be created based on this home address and the `work_address` property is not allowed."}}},"work_address":{"type":"object","description":"Specify the company work location for the employee","required":["location_uuid"],"properties":{"location_uuid":{"type":"string","format":"uuid","description":"UUID of an existing company work location"}}},"job":{"type":"object","description":"Job details for the employee (required if compensation is provided)","required":["title","hire_date"],"properties":{"title":{"type":"string","description":"Job title"},"hire_date":{"type":"string","format":"date","description":"The date when the employee was hired or rehired for the job."},"two_percent_shareholder":{"type":"boolean","description":"Whether the employee owns at least 2% of the company. Can only be `true` for S-Corp companies."},"state_wc_covered":{"type":["boolean","null"],"description":"Whether this job is eligible for workers' compensation coverage in the state of Washington (WA)."},"state_wc_class_code":{"type":["string","null"],"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."}}},"department":{"type":"object","description":"Department details for the employee","required":["department_uuid"],"properties":{"department_uuid":{"type":"string","format":"uuid","description":"UUID of an existing company department"}}},"compensation":{"type":"object","description":"Compensation details for the employee (requires job to be provided)","required":["rate","payment_unit","flsa_status"],"properties":{"rate":{"type":"string","description":"The dollar amount paid per payment unit."},"payment_unit":{"type":"string","enum":["Hour","Week","Month","Year","Paycheck"],"description":"The unit accompanying the compensation rate. If the employee is an owner, rate should be `Paycheck`."},"flsa_status":{"type":"string","enum":["Exempt","Salaried Nonexempt","Nonexempt","Owner","Commission Only Exempt","Commission Only Nonexempt"],"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. If selecting `Owner`, `payment_unit` must be `\"Paycheck\"`."}}},"bank_accounts":{"type":"array","description":"Creates employee bank account(s) and payment method(s) for direct deposit. Payments can be split across accounts by Percentage or by Amount. If splitting payments by `Percentage`, all splits must have a `split_amount` and the percentages must add up to `100`.\nIf splitting payments by `Amount`, the priority is set based on the order of the bank accounts in the array and the last bank account is the remainder account (should have `split_amount` set to `null`).","items":{"type":"object","required":["type","account_type","routing_number","account_number","split_by"],"properties":{"name":{"type":["string","null"],"description":"Account nickname"},"account_type":{"type":"string","enum":["Checking","Savings"],"description":"Type of bank account"},"routing_number":{"type":"string","description":"Bank routing number"},"account_number":{"type":"string","description":"Bank account number"},"type":{"type":"string","enum":["Direct Deposit"],"description":"Payment type (must be Direct Deposit)"},"split_by":{"type":"string","enum":["Amount","Percentage"],"description":"How to split deposits, must be the same for all bank accounts. If split_by is `Percentage`, then the split_amounts must add up to exactly 100."},"split_amount":{"type":["string","null"],"description":"Split amount in percentage or CENTS (`null` for remainder account)"}}}}}}}}}}},"required":true}}},"/v1/people_batches/{people_batch_uuid}":{"get":{"summary":"Get a people batch","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"people_batch_uuid","in":"path","description":"The UUID of the people batch","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-people_batches-people_batch_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Returns the status and results of a people batch.\n\nPoll this endpoint to check the batch processing status and retrieve results.\n\nscope: `people_batches:read`","tags":["People Batches"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/People-Batch-Results/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/People-Batch-Results"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/plaid/processor_token":{"post":{"summary":"Create a bank account from a plaid processor token","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."}],"x-gusto-rswag":true,"operationId":"post-v1-plaid-processor_token","security":[{"CompanyAccessAuth":[]}],"description":"This endpoint creates a new **verified** bank account by using a plaid processor token to retrieve its information.\n\n> 📘\n> To create a token please use the [plaid api](https://plaid.com/docs/api/processors/#processortokencreate) and select \"gusto\" as processor.\n\n> 🚧 Warning - Company Bank Accounts\n>\n> If a default company bank account exists, it will be disabled and the new bank account will replace it as the company's default funding method.\n\nscope: `plaid_processor:write`","tags":["Bank Accounts"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"A JSON object containing bank information","content":{"application/json":{"examples":{"plaid_external_status":{"value":{"$ref":"#/components/schemas/Company-Bank-Account/x-examples/plaid_external_status"}}},"schema":{"$ref":"#/components/schemas/Company-Bank-Account"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"plaid_processor_token_missing":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/plaid_processor_token_missing"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Plaid-Processor-Token-Request"}}},"required":true}}},"/v1/companies/{company_uuid}/recovery_cases":{"get":{"summary":"Get all recovery cases for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-recovery-cases","security":[{"CompanyAccessAuth":[]}],"description":"Fetch all recovery cases for a company.\n\nscope: `recovery_cases:read`","tags":["Recovery Cases"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"recovery_case_index_item":{"value":[{"$ref":"#/components/schemas/Recovery-Case/x-examples/recovery_case_index_item"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Recovery-Case"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/recovery_cases/{recovery_case_uuid}/redebit":{"put":{"summary":"Initiate a redebit for a recovery case","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"recovery_case_uuid","in":"path","required":true,"description":"The UUID of the recovery case","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"redebit-recovery-case","security":[{"CompanyAccessAuth":[]}],"description":"After resolving the underlying bank error, initiate a redebit for an open recovery case. This submission is asynchronous and a successful request responds with a 202 HTTP status.\n\nIt may take up to four business days for the ACH debit to process; in the meantime, the status of the recovery case will be in the `initiated_redebit` state. When funds are successfully redebited, the recovery case is transitioned to the `recovered` state.\n\nIf the company has exceeded maximum redebit attempts, or if the recovery case is not in a redebitable state, the response will be 422 Unprocessable Entity.\n\nscope: `recovery_cases:write`","tags":["Recovery Cases"],"x-gusto-integration-type":["embedded"],"responses":{"202":{"description":"Accepted"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"recovery_case_not_redebitable":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/recovery_case_not_redebitable"}},"recovery_case_exceeded_retries":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/recovery_case_exceeded_retries"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/employees/{employee_id}/recurring_reimbursements":{"get":{"summary":"Get recurring reimbursements for an employee","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_id-recurring_reimbursements","security":[{"CompanyAccessAuth":[]}],"description":"Get all active recurring reimbursements for an employee.\n\nscope: `reimbursements:read`","tags":["Reimbursements"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Recurring-Reimbursement-List/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Recurring-Reimbursement-List"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create a recurring reimbursement","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-employees-employee_id-recurring_reimbursements","security":[{"CompanyAccessAuth":[]}],"description":"Create a recurring reimbursement for an employee.\n\nscope: `reimbursements:write`","tags":["Reimbursements"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"201":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Recurring-Reimbursement/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Recurring-Reimbursement"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"invalid attributes","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["description","amount"],"properties":{"description":{"type":"string","description":"The description of the reimbursement"},"amount":{"type":"number","description":"The dollar amount of the reimbursement"}}}}},"required":true}}},"/v1/recurring_reimbursements/{id}":{"get":{"summary":"Get a recurring reimbursement","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"id","in":"path","description":"The UUID of the reimbursement","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-recurring_reimbursements","security":[{"CompanyAccessAuth":[]}],"description":"Get a specific recurring reimbursement.\n\nscope: `reimbursements:read`","tags":["Reimbursements"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Recurring-Reimbursement/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Recurring-Reimbursement"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update a recurring reimbursement","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"id","in":"path","description":"The UUID of the reimbursement","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-recurring_reimbursements","security":[{"CompanyAccessAuth":[]}],"description":"Update a recurring reimbursement.\n\nscope: `reimbursements:write`","tags":["Reimbursements"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Recurring-Reimbursement/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Recurring-Reimbursement"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"409":{"description":"invalid version","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"invalid attributes","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Versionable-Required"},{"type":"object","properties":{"description":{"type":"string","description":"The description of the reimbursement"},"amount":{"type":"number","description":"The dollar amount of the reimbursement"}}}]}}},"required":true}},"delete":{"summary":"Delete a recurring reimbursement","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"id","in":"path","description":"The UUID of the reimbursement","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-recurring_reimbursements","security":[{"CompanyAccessAuth":[]}],"description":"Delete (soft delete) a recurring reimbursement for an employee.\n\nscope: `reimbursements:write`","tags":["Reimbursements"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"204":{"description":"successful"},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/companies/{company_uuid}/reports":{"post":{"summary":"Create a custom report","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","required":true,"description":"The UUID of the company","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-companies-company_uuid-reports","security":[{"CompanyAccessAuth":[]}],"description":"Create a custom report for a company. This endpoint initiates creating a custom report with custom columns, groupings, and filters. The `request_uuid` in the response can then be used to poll for the status and report URL upon completion using the [report GET endpoint](https://docs.gusto.com/embedded-payroll/reference/get-reports-request_uuid). This URL is valid for 10 minutes.\n\nscope: `company_reports:write`","tags":["Reports"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Create-Report/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Create-Report"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"report_invalid_columns":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/report_invalid_columns"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Create-Report-Body"}}},"required":true}}},"/v1/payrolls/{payroll_uuid}/reports/general_ledger":{"post":{"summary":"Create a general ledger report","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"payroll_uuid","in":"path","required":true,"description":"The UUID of the payroll","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-payrolls-payroll_uuid-reports-general_ledger","security":[{"CompanyAccessAuth":[]}],"description":"Create a general ledger report for a payroll. The report can be aggregated by different dimensions such as job or department.\n\nUse the `request_uuid` in the response with the [report GET endpoint](../reference/get-reports-request_uuid) to poll for the status and report URL upon completion. The retrieved report will be generated in a JSON format.\n\nscope: `company_reports:write`","tags":["Reports"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/General-Ledger-Report/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/General-Ledger-Report"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"general_ledger_invalid_aggregation":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/general_ledger_invalid_aggregation"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/General-Ledger-Report-Body"}}},"required":true}}},"/v1/reports/{request_uuid}":{"get":{"summary":"Get a report","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"request_uuid","in":"path","required":true,"description":"The UUID of the request to generate a document. Generate document endpoints return request_uuids to be used with the GET generated document endpoint.","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-reports-request_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Get a company's report given the `request_uuid`. The response will include the report request's status and, if complete, the report URL.\n\nReports containing PHI are inaccessible with `company_reports:read:tier_2_only` data scope\n\nscope: `company_reports:read`","tags":["Reports"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Report/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Report"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/companies/{company_uuid}/report_templates/{report_type}":{"get":{"summary":"Get a report template","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","required":true,"description":"The UUID of the company","schema":{"type":"string"}},{"name":"report_type","in":"path","required":true,"description":"The report type","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-companies-company_uuid-report-templates-report_type","security":[{"CompanyAccessAuth":[]}],"description":"Get a company's report template. The only supported report type is `payroll_journal`. The resulting columns and groupings from this endpoint can be used as a guidance to create the report using the POST create report endpoint.\n\nscope: `company_reports:write`","tags":["Reports"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Report-Template/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Report-Template"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"report_template_invalid_report_type":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/report_template_invalid_report_type"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/employees/{employee_id}/salary_estimates":{"post":{"summary":"Create a salary estimate for an employee","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","required":true,"description":"The UUID of the employee","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-employees-employee_id-salary_estimates","security":[{"CompanyAccessAuth":[]}],"description":"Create a salary estimate for an employee. This endpoint helps calculate a reasonable salary for S Corp owners based on their occupation, experience level, location, and business revenue.\n\nA salary estimate must include:\n- Annual net revenue of the business\n- ZIP code for location-based salary data\n- One or more occupations with experience levels and time percentages (must sum to 100%)\n\nOnly one in-progress salary estimate can exist per employee at a time. If an in-progress estimate already exists, you must either accept it or use the update endpoint.\n\nscope: `salary_estimates:write`","tags":["Salary Estimates"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"201":{"description":"successfully created","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Salary-Estimate/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Salary-Estimate"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"unprocessable entity - invalid parameters","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["zip_code","occupations"],"properties":{"annual_net_revenue":{"type":["number","null"],"description":"The annual net revenue of the business (must be greater than 0)","example":500000},"zip_code":{"type":"string","description":"The ZIP code for location-based salary calculations","pattern":"^\\d{5}$","example":"94107"},"occupations":{"type":"array","description":"Array of occupations. Time percentages must sum to 100%.","minItems":1,"items":{"type":"object","required":["code","experience_level","time_percentage"],"properties":{"code":{"type":"string","description":"Bureau of Labor Statistics (BLS) occupation code","example":"151252"},"experience_level":{"type":"string","description":"Experience level for this occupation","enum":["novice","intermediate","average","skilled","expert"],"example":"skilled"},"time_percentage":{"type":"string","format":"float","description":"Percentage of time spent in this occupation (as decimal, e.g., 1.0 = 100%)","minimum":0,"maximum":1,"example":"1.0"},"primary":{"type":"boolean","description":"Whether this is the primary occupation","example":true}}}}}}}},"required":true}}},"/v1/salary_estimates/{uuid}":{"get":{"summary":"Get a salary estimate","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"uuid","in":"path","required":true,"description":"The UUID of the salary estimate","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-salary_estimates-id","security":[{"CompanyAccessAuth":[]}],"description":"Retrieve a salary estimate by its UUID. Returns the estimated salary calculation along with all occupation details, revenue, and location information.\n\nscope: `salary_estimates:read`","tags":["Salary Estimates"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Salary-Estimate/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Salary-Estimate"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update a salary estimate","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"uuid","in":"path","required":true,"description":"The UUID of the salary estimate","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-salary_estimates-id","security":[{"CompanyAccessAuth":[]}],"description":"Update an existing salary estimate. You can modify the annual net revenue, ZIP code, and occupations.\n\nThe salary estimate must not be finalized (accepted). Once accepted, salary estimates become read-only for record-keeping purposes.\n\nscope: `salary_estimates:write`","tags":["Salary Estimates"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Salary-Estimate/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Salary-Estimate"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"unprocessable entity - already finalized","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["zip_code","occupations"],"properties":{"annual_net_revenue":{"type":["number","null"],"description":"The annual net revenue of the business (must be greater than 0)","example":600000},"zip_code":{"type":"string","description":"The ZIP code for location-based salary calculations","pattern":"^\\d{5}$","example":"94107"},"occupations":{"type":"array","description":"Array of occupations. Time percentages must sum to 100%.","minItems":1,"items":{"type":"object","required":["code","experience_level","time_percentage"],"properties":{"code":{"type":"string","description":"Bureau of Labor Statistics (BLS) occupation code","example":"151252"},"experience_level":{"type":"string","description":"Experience level for this occupation","enum":["novice","intermediate","average","skilled","expert"],"example":"expert"},"time_percentage":{"type":"string","format":"float","description":"Percentage of time spent in this occupation (as decimal, e.g., 0.5 = 50%)","minimum":0,"maximum":1,"example":"0.6"},"primary":{"type":"boolean","description":"Whether this is the primary occupation","example":true}}}}}}}},"required":true}}},"/v1/salary_estimates/{uuid}/accept":{"post":{"summary":"Accept a salary estimate","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"uuid","in":"path","required":true,"description":"The UUID of the salary estimate","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-salary_estimates-uuid-accept","security":[{"CompanyAccessAuth":[]}],"description":"Accept and finalize a salary estimate. This associates the estimate with an employee job and marks it as accepted.\n\nOnce accepted, the salary estimate becomes read-only for record-keeping purposes. The accepted salary can then be used to set up compensation for the employee.\n\nscope: `salary_estimates:write`","tags":["Salary Estimates"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Salary-Estimate/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Salary-Estimate"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"unprocessable entity - invalid employee job","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["employee_job_uuid"],"properties":{"employee_job_uuid":{"type":"string","description":"The UUID of the employee job to associate with this salary estimate","example":"7f5d3d93-6d6f-48c0-9f4e-cd12c2d3e4b2"}}}}},"required":true}}},"/v1/salary_estimates/occupations":{"get":{"summary":"Search for BLS occupations","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"search","in":"query","required":true,"description":"Search term for occupation (minimum 3 characters)","example":"software","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-salary_estimates-occupations","security":[{"SystemAccessAuth":[]}],"description":"Search for Bureau of Labor Statistics (BLS) occupations by name or keyword. This endpoint helps users find the appropriate occupation codes to use when creating or updating salary estimates.\n\nReturns a list of matching occupations with their codes, titles, and descriptions.\n\n📘 System Access Authentication\n\nThis endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)\n\nscope: `salary_estimates:read`","tags":["Salary Estimates"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":[{"$ref":"#/components/schemas/BLS-Occupation/x-examples/success_status"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/BLS-Occupation"}}}}},"422":{"description":"unprocessable entity - search term too short","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/sandbox/generate_w2":{"post":{"summary":"Generate a W2 form [DEMO]","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."}],"x-gusto-rswag":true,"operationId":"post-v1-sandbox-generate_w2","security":[{"CompanyAccessAuth":[]}],"description":"> 🚧 Demo action\n>\n> This action is only available in the Demo environment\n\nGenerates a W2 document for testing purposes.\n\nscope: `employees:write`","tags":["Employee Forms"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"sandbox_w2":{"value":{"$ref":"#/components/schemas/Form/x-examples/sandbox_w2"}}},"schema":{"$ref":"#/components/schemas/Form"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"sandbox_w2_already_generated":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/sandbox_w2_already_generated"}},"sandbox_w2_invalid_year":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/sandbox_w2_invalid_year"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","description":"The employee UUID."},"year":{"type":"integer","description":"Must be equal to or more recent than 2015. If not specified, defaults to the previous year.\n"}},"required":["employee_id"]}}},"required":true}}},"/v1/sandbox/generate_1099":{"post":{"summary":"Generate a 1099 form [DEMO]","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."}],"x-gusto-rswag":true,"operationId":"post-v1-sandbox-generate_1099","security":[{"CompanyAccessAuth":[]}],"description":"> 🚧 Demo action\n>\n> This action is only available in the Demo environment\n\nGenerates a 1099 document for testing purposes.\n\nscope: `contractors:write`","tags":["Contractor Forms"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"sandbox_1099":{"value":{"$ref":"#/components/schemas/Form_1099/x-examples/sandbox_1099"}}},"schema":{"$ref":"#/components/schemas/Form_1099"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"sandbox_1099_invalid_year":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/sandbox_1099_invalid_year"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"contractor_id":{"type":"string","description":"The contractor UUID."},"year":{"type":"integer","description":"Must be equal to or more recent than 2015. If not specified, defaults to the previous year.\n"}},"required":["contractor_id"]}}},"required":true}}},"/v1/companies/{company_uuid}/signatories":{"get":{"summary":"Get the signatories for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_uuid-signatories","security":[{"CompanyAccessAuth":[]}],"description":"Returns the signatories for a company. A company has at most one signatory.\n\n## Related guides\n- [Signatory Events](doc:signatory-events)\n\nscope: `signatories:read`","tags":["Signatories"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"typical_signatory":{"value":[{"$ref":"#/components/schemas/Signatory/x-examples/typical_signatory"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Signatory"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create a signatory","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-company-signatories","security":[{"CompanyAccessAuth":[]}],"description":"Creates a company signatory with complete information. The company must not already have a signatory.\n\nA signatory can legally sign forms once the identity verification process is successful. The signatory should be an officer, owner, general partner or LLC member manager, plan administrator, fiduciary, or an authorized representative who is designated to sign agreements on the company's behalf. An officer is the president, vice president, treasurer, chief accounting officer, etc. There can only be a single primary signatory in a company.\n\n### Webhooks\n- `signatory.created`: Fires when a signatory is successfully created.\n\n### Related guides\n- [Signatory Events](doc:signatory-events)\n\nscope: `signatories:manage`","tags":["Signatories"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"typical_signatory":{"value":{"$ref":"#/components/schemas/Signatory/x-examples/typical_signatory"}}},"schema":{"$ref":"#/components/schemas/Signatory"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"signatory_email_required":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/signatory_email_required"}},"signatory_company_already_has_signatory":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/signatory_company_already_has_signatory"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Signatory-Create-Request"}}},"required":true}}},"/v1/companies/{company_uuid}/signatories/invite":{"post":{"summary":"Invite a signatory","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_uuid-signatories-invite","security":[{"CompanyAccessAuth":[]}],"description":"Creates a signatory with minimal information. This signatory can be invited to provide more information through the [Update a signatory](ref:put-v1-companies-company_uuid-signatories-signatory_uuid) endpoint. This will start the identity verification process and allow the signatory to be verified to sign documents.\n\n## Related guides\n- [Signatory Events](doc:signatory-events)\n\nscope: `signatories:manage`","tags":["Signatories"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"signatory_with_address":{"value":{"$ref":"#/components/schemas/Signatory/x-examples/signatory_with_address"}}},"schema":{"$ref":"#/components/schemas/Signatory"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"signatory_company_already_has_signatory":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/signatory_company_already_has_signatory"}},"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Signatory-Invite-Request"}}},"required":true}}},"/v1/companies/{company_uuid}/signatories/{signatory_uuid}":{"put":{"summary":"Update a signatory","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"signatory_uuid","in":"path","description":"The UUID of the signatory","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-companies-company_uuid-signatories-signatory_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Updates a signatory that has been either invited or created. If the signatory has been created with minimal information through the [Invite a signatory](ref:post-v1-companies-company_uuid-signatories-invite) endpoint, then the first update must contain all attributes specified in the request body in order to start the identity verification process.\n\n## Related guides\n- [Signatory Events](doc:signatory-events)\n\nscope: `signatories:write`","tags":["Signatories"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"signatory_with_address":{"value":{"$ref":"#/components/schemas/Signatory/x-examples/signatory_with_address"}}},"schema":{"$ref":"#/components/schemas/Signatory"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"409":{"description":"Conflict","content":{"application/json":{"examples":{"invalid_version":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_version"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"signatory_email_required":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/signatory_email_required"}},"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Signatory-Update-Request"}}},"required":true}},"delete":{"summary":"Delete a signatory","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"signatory_uuid","in":"path","description":"The UUID of the signatory","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-companies-company_uuid-signatories-signatory_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Deletes a company signatory.\n\n## Related guides\n- [Signatory Events](doc:signatory-events)\n\nscope: `signatories:manage`","tags":["Signatories"],"x-gusto-integration-type":["embedded"],"responses":{"204":{"description":"No Content"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/employees/{employee_id}/terminations":{"get":{"summary":"Get terminations for an employee","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_id-terminations","security":[{"CompanyAccessAuth":[]}],"description":"Terminations are created whenever an employee is scheduled to leave the company. The only things required are an effective date (their last day of work) and whether they should receive their wages in a one-off termination payroll or with the rest of the company.\n\nNote that some states require employees to receive their final wages within 24 hours (unless they consent otherwise,) in which case running a one-off payroll may be the only option.\n\nscope: `employments:read`","tags":["Employee Employments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"terminated_employee":{"value":[{"$ref":"#/components/schemas/Termination/x-examples/terminated_employee"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Termination"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create an employee termination","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-employees-employee_id-terminations","security":[{"CompanyAccessAuth":[]}],"description":"Create a termination for an employee. The only things required are an effective date (their last day of work) and whether they should receive their wages in a one-off termination payroll or with the rest of the company.\n\nNote that some states require employees to receive their final wages within 24 hours (unless they consent otherwise,) in which case running a one-off payroll may be the only option.\n\nscope: `employments:write`","tags":["Employee Employments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"terminated_employee":{"value":{"$ref":"#/components/schemas/Termination/x-examples/terminated_employee"}}},"schema":{"$ref":"#/components/schemas/Termination"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"termination_already_terminated":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/termination_already_terminated"}},"termination_invalid_effective_date":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/termination_invalid_effective_date"}},"termination_effective_date_required":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/termination_effective_date_required"}},"termination_payroll_exists":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/termination_payroll_exists"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"effective_date":{"type":"string","description":"The employee's last day of work.","example":"2020-06-30"},"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.","default":false,"example":true}},"required":["effective_date"],"example":{"effective_date":"2020-06-30","run_termination_payroll":false}}}},"required":true}},"delete":{"summary":"Delete an employee termination","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-employees-employee_id-terminations","security":[{"CompanyAccessAuth":[]}],"description":"Delete an employee termination.\n\nscope: `employments:write`","tags":["Employee Employments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"204":{"description":"No Content"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"termination_already_in_effect":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/termination_already_in_effect"}},"termination_payroll_exists":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/termination_payroll_exists"}},"termination_rehired":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/termination_rehired"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/terminations/{employee_id}":{"get":{"summary":"Get an employee termination","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-terminations-employee_id","security":[{"CompanyAccessAuth":[]}],"description":"Terminations are created whenever an employee is scheduled to leave the company. The only things required are an effective date (their last day of work) and whether they should receive their wages in a one-off termination payroll or with the rest of the company.\n\nNote that some states require employees to receive their final wages within 24 hours (unless they consent otherwise,) in which case running a one-off payroll may be the only option.\n\nscope: `employments:read`","tags":["Employee Employments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"terminated_employee":{"value":{"$ref":"#/components/schemas/Termination/x-examples/terminated_employee"}}},"schema":{"$ref":"#/components/schemas/Termination"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update an employee termination","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-terminations-employee_id","security":[{"CompanyAccessAuth":[]}],"description":"Terminations are created whenever an employee is scheduled to leave the company. The only things required are an effective date (their last day of work) and whether they should receive their wages in a one-off termination payroll or with the rest of the company.\n\nNote that some states require employees to receive their final wages within 24 hours (unless they consent otherwise,) in which case running a one-off payroll may be the only option.\n\nscope: `employments:write`","tags":["Employee Employments"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Successful","content":{"application/json":{"examples":{"terminated_employee":{"value":{"$ref":"#/components/schemas/Termination/x-examples/terminated_employee"}}},"schema":{"$ref":"#/components/schemas/Termination"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"termination_invalid_effective_date":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/termination_invalid_effective_date"}},"termination_effective_date_required":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/termination_effective_date_required"}},"termination_rehired":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/termination_rehired"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Versionable-Required"},{"type":"object","properties":{"effective_date":{"type":"string","description":"The employee's last day of work.","example":"2020-06-30"},"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.","default":false,"example":true}},"required":["effective_date"]}],"example":{"version":"d487dd0b55dfcacdd920ccbdaeafa351","effective_date":"2020-06-30","run_termination_payroll":false}}}},"required":true}}},"/v1/companies/{company_uuid}/time_off/admin_approved_requests":{"post":{"summary":"Create an admin-approved time off request","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_uuid-time_off-admin_approved_requests","security":[{"CompanyAccessAuth":[]}],"description":"Create a pre-approved time off request on behalf of an employee (admin or system initiated).\nThe request is always created with approved status.\n\nscope: `time_off_requests:manage`","tags":["Time Off Requests"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"created","content":{"application/json":{"examples":{"approved_status":{"value":{"$ref":"#/components/schemas/Embedded-Time-Off-Request/x-examples/approved_status"}}},"schema":{"$ref":"#/components/schemas/Embedded-Time-Off-Request"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"employee_uuid":{"type":"string","description":"The UUID of the employee"},"policy_uuid":{"type":"string","description":"The UUID of the time off policy"},"employer_note":{"type":"string","description":"A note from the employer about the request"},"approver_uuid":{"type":"string","description":"The UUID of the approving admin. Defaults to the primary payroll admin."},"start_date":{"type":"string","description":"The start date of the time off request (YYYY-MM-DD)"},"end_date":{"type":"string","description":"The end date of the time off request (YYYY-MM-DD)"},"days":{"type":"object","additionalProperties":{"type":"string"},"description":"An object where keys are dates in YYYY-MM-DD format and values are hours as string decimals (e.g. {\"2025-01-20\": \"8.000\"})"}},"required":["employee_uuid","policy_uuid","start_date","end_date","days"]}}},"required":true}}},"/v1/companies/{company_uuid}/time_off/balances":{"get":{"summary":"Get time off balances for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"employee_uuids","in":"query","required":false,"description":"Filter by employee UUIDs (comma-separated)","schema":{"type":"string"}},{"name":"policy_uuids","in":"query","required":false,"description":"Filter by time off policy UUIDs (comma-separated)","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_uuid-time_off-balances","security":[{"CompanyAccessAuth":[]}],"description":"Get time off balances for all employees in a company\n\nscope: `time_off_requests:read`","tags":["Time Off Requests"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":[{"$ref":"#/components/schemas/Embedded-Time-Off-Balance/x-examples/success_status"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Embedded-Time-Off-Balance"}}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/companies/{company_uuid}/time_off/requests":{"get":{"summary":"List time off requests for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"employee_uuids","in":"query","required":false,"description":"Filter by employee UUIDs. Comma-separated for multiple values.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by request status. Comma-separated for multiple values (e.g. pending,approved,declined,consumed).","schema":{"type":"string"}},{"name":"start_date","in":"query","required":false,"description":"Filter requests that overlap with this start date","schema":{"type":"string"}},{"name":"end_date","in":"query","required":false,"description":"Filter requests that overlap with this end date","schema":{"type":"string"}},{"name":"sort_order","in":"query","required":false,"description":"Sort order by start_date (asc or desc, defaults to desc)","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_uuid-time_off-requests","security":[{"CompanyAccessAuth":[]}],"description":"Get all time off requests for a company. Supports filtering by status, employee, and date ranges.\n\nPossible statuses:\n- `pending` — awaiting approval\n- `approved` — approved by an admin but not yet processed in a payroll\n- `declined` — declined by an admin\n- `consumed` — processed in a completed payroll\n\nAllowed values for `status`: pending, approved, declined, consumed.\n\nscope: `time_off_requests:read`","tags":["Time Off Requests"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":[{"$ref":"#/components/schemas/Embedded-Time-Off-Request/x-examples/success_status"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Embedded-Time-Off-Request"}}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"time_off_request_invalid_status_filter":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/time_off_request_invalid_status_filter"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}},"post":{"summary":"Create a time off request","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_uuid-time_off-requests","security":[{"CompanyAccessAuth":[]}],"description":"Create a time off request for an employee\n\nscope: `time_off_requests:write`","tags":["Time Off Requests"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"created","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Embedded-Time-Off-Request/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Embedded-Time-Off-Request"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"employee_uuid":{"type":"string","description":"The UUID of the employee"},"policy_uuid":{"type":"string","description":"The UUID of the time off policy"},"employee_note":{"type":"string","description":"A note from the employee about the request"},"start_date":{"type":"string","description":"The start date of the time off request (YYYY-MM-DD)"},"end_date":{"type":"string","description":"The end date of the time off request (YYYY-MM-DD)"},"days":{"type":"object","additionalProperties":{"type":"string"},"description":"An object where keys are dates in YYYY-MM-DD format and values are hours as string decimals (e.g. {\"2025-01-20\": \"8.000\"})"}},"required":["employee_uuid","policy_uuid","start_date","end_date","days"]}}},"required":true}}},"/v1/companies/{company_uuid}/time_off/requests/preview":{"post":{"summary":"Preview a time off request","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_uuid-time_off-requests-preview","security":[{"CompanyAccessAuth":[]}],"description":"Preview a time off request to see balance impact before creating\n\nscope: `time_off_requests:read`","tags":["Time Off Requests"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Embedded-Time-Off-Request-Preview/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Embedded-Time-Off-Request-Preview"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request_uuid":{"type":"string","description":"The UUID of an existing time off request to preview changes for"},"employee_uuid":{"type":"string","description":"The UUID of the employee"},"policy_uuid":{"type":"string","description":"The UUID of the time off policy"},"start_date":{"type":"string","description":"The start date of the time off request (YYYY-MM-DD)"},"end_date":{"type":"string","description":"The end date of the time off request (YYYY-MM-DD)"},"days":{"type":"object","additionalProperties":{"type":"string"},"description":"An object where keys are dates in YYYY-MM-DD format and values are hours as string decimals (e.g. {\"2025-01-20\": \"8.000\"})"}},"required":["employee_uuid","policy_uuid","start_date","end_date","days"]}}},"required":true}}},"/v1/time_off/requests/{time_off_request_uuid}":{"get":{"summary":"Get a time off request","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"time_off_request_uuid","in":"path","description":"The UUID of the time off request","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-time_off-requests-time_off_request_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Get a single time off request by UUID\n\nscope: `time_off_requests:read`","tags":["Time Off Requests"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Embedded-Time-Off-Request/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Embedded-Time-Off-Request"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"delete":{"summary":"Delete a time off request","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"time_off_request_uuid","in":"path","description":"The UUID of the time off request","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-time_off-requests-time_off_request_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Delete a time off request\n\nscope: `time_off_requests:write`","tags":["Time Off Requests"],"x-gusto-integration-type":["embedded"],"responses":{"204":{"description":"no content"},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"time_off_request_cannot_delete":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/time_off_request_cannot_delete"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/time_off/requests/{time_off_request_uuid}/approve":{"put":{"summary":"Approve a time off request","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"time_off_request_uuid","in":"path","description":"The UUID of the time off request","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-time_off-requests-time_off_request_uuid-approve","security":[{"CompanyAccessAuth":[]}],"description":"Approve a pending time off request. Optionally override the dates and hours.\n\nOnly requests with a `pending` status can be approved. Attempting to approve a request that has already been `declined` or `consumed` will fail with a 422 error.\n\nscope: `time_off_requests:manage`","tags":["Time Off Requests"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"approved_status":{"value":{"$ref":"#/components/schemas/Embedded-Time-Off-Request/x-examples/approved_status"}}},"schema":{"$ref":"#/components/schemas/Embedded-Time-Off-Request"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"time_off_request_cannot_approve":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/time_off_request_cannot_approve"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"approver_uuid":{"type":"string","description":"The UUID of the admin approving the request. Defaults to the company's primary payroll admin."},"employer_note":{"type":"string","description":"A note from the employer about the approval"},"days":{"type":"object","additionalProperties":{"type":"string"},"description":"An object where keys are dates in YYYY-MM-DD format and values are hours as string decimals (e.g. {\"2025-01-20\": \"8.000\"}). Use this to override the requested hours."}}}}}}}},"/v1/time_off/requests/{time_off_request_uuid}/decline":{"put":{"summary":"Decline a time off request","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"time_off_request_uuid","in":"path","description":"The UUID of the time off request","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-time_off-requests-time_off_request_uuid-decline","security":[{"CompanyAccessAuth":[]}],"description":"Decline a pending or approved time off request. Requires an employer_note.\n\nscope: `time_off_requests:manage`","tags":["Time Off Requests"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"declined_status":{"value":{"$ref":"#/components/schemas/Embedded-Time-Off-Request/x-examples/declined_status"}}},"schema":{"$ref":"#/components/schemas/Embedded-Time-Off-Request"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"time_off_request_missing_employer_note":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/time_off_request_missing_employer_note"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"employer_note":{"type":"string","description":"Note explaining why the request was declined"},"approver_uuid":{"type":"string","description":"The UUID of the admin declining the request. Defaults to the company's primary payroll admin."}},"required":["employer_note"]}}},"required":true}}},"/v1/companies/{company_uuid}/time_off_policies":{"get":{"summary":"Get all time off policies for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-companies-company_uuid-time_off_policies","security":[{"CompanyAccessAuth":[]}],"description":"Get all time off policies for a company\n\nscope: `time_off_policies:read`","tags":["Time Off Policies"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":[{"$ref":"#/components/schemas/Time-Off-Policy/x-examples/success_status"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Time-Off-Policy"}}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create a time off policy","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-companies-company_uuid-time_off_policies","security":[{"CompanyAccessAuth":[]}],"description":"Create a time off policy\n\nscope: `time_off_policies:write`","tags":["Time Off Policies"],"x-gusto-integration-type":["embedded"],"responses":{"201":{"description":"created","content":{"application/json":{"examples":{"success_status_no_employees":{"value":{"$ref":"#/components/schemas/Time-Off-Policy/x-examples/success_status_no_employees"}}},"schema":{"$ref":"#/components/schemas/Time-Off-Policy"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"Policy name required","content":{"application/json":{"examples":{"time_off_policy_name_required":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/time_off_policy_name_required"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Time-Off-Policy-Request"}}},"required":true}}},"/v1/time_off_policies/{time_off_policy_uuid}":{"get":{"summary":"Get a time off policy","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"time_off_policy_uuid","in":"path","description":"The UUID of the time off policy","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-time_off_policies-time_off_policy_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Get a time off policy\n\nscope: `time_off_policies:read`","tags":["Time Off Policies"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Time-Off-Policy/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Time-Off-Policy"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update a time off policy","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"time_off_policy_uuid","in":"path","description":"The UUID of the time off policy","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-time_off_policies-time_off_policy_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Update a time off policy\n\nscope: `time_off_policies:write`","tags":["Time Off Policies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Time-Off-Policy/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Time-Off-Policy"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"Unlimited Policy updated with accrual rate","content":{"application/json":{"examples":{"time_off_policy_unlimited_invalid_accrual_rate":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/time_off_policy_unlimited_invalid_accrual_rate"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Versionable-Required"},{"$ref":"#/components/schemas/Time-Off-Policy-Update-Request"}]}}},"required":true}}},"/v1/time_off_policies/{time_off_policy_uuid}/deactivate":{"put":{"summary":"Deactivate a time off policy","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"time_off_policy_uuid","in":"path","description":"The UUID of the time off policy","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-time_off_policies-time_off_policy_uuid-deactivate","security":[{"CompanyAccessAuth":[]}],"description":"Deactivate a time off policy\n\nscope: `time_off_policies:write`","tags":["Time Off Policies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"deactivated_status":{"value":{"$ref":"#/components/schemas/Time-Off-Policy/x-examples/deactivated_status"}}},"schema":{"$ref":"#/components/schemas/Time-Off-Policy"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"Policy has pending time off requests","content":{"application/json":{"examples":{"time_off_policy_pending_requests":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/time_off_policy_pending_requests"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/time_off_policies/{time_off_policy_uuid}/add_employees":{"put":{"summary":"Add employees to a time off policy","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"time_off_policy_uuid","in":"path","description":"The UUID of the time off policy","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-time_off_policies-time_off_policy_uuid-add_employees","security":[{"CompanyAccessAuth":[]}],"description":"Add employees to a time off policy. Employees are required to have at least one job to be added to a time off policy. Accepts starting balances for non-unlimited policies\n\nscope: `time_off_policies:write`","tags":["Time Off Policies"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Time-Off-Policy/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Time-Off-Policy"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"Add employees with no employees","content":{"application/json":{"examples":{"time_off_policy_employees_required":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/time_off_policy_employees_required"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["employees"],"properties":{"employees":{"type":"array","items":{"type":"object","required":["uuid"],"properties":{"uuid":{"type":"string","description":"The UUID of the employee"},"balance":{"type":["string","null"],"description":"The starting balance for the employee"}}}}}}}},"required":true}}},"/v1/time_off_policies/{time_off_policy_uuid}/remove_employees":{"put":{"summary":"Remove employees from a time off policy","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"time_off_policy_uuid","in":"path","description":"The UUID of the time off policy","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-time_off_policies-time_off_policy_uuid-remove_employees","security":[{"CompanyAccessAuth":[]}],"description":"Remove employees from a time off policy\n\nscope: `time_off_policies:write`","tags":["Time Off Policies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Time-Off-Policy/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Time-Off-Policy"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"Remove employees with no employees","content":{"application/json":{"examples":{"time_off_policy_employees_required":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/time_off_policy_employees_required"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["employees"],"properties":{"employees":{"type":"array","items":{"type":"object","required":["uuid"],"properties":{"uuid":{"type":"string","description":"The UUID of the employee"}}}}}}}},"required":true}}},"/v1/time_off_policies/{time_off_policy_uuid}/balance":{"put":{"summary":"Update employee time off balances","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"time_off_policy_uuid","in":"path","description":"The UUID of the time off policy","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-time_off_policies-time_off_policy_uuid-balance","security":[{"CompanyAccessAuth":[]}],"description":"Updates time off hours balances for employees for a time off policy.\n\nscope: `time_off_policies:write`","tags":["Time Off Policies"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Time-Off-Policy/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Time-Off-Policy"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"Unlimited policy balance update","content":{"application/json":{"examples":{"time_off_policy_unlimited_balance_update":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/time_off_policy_unlimited_balance_update"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["employees"],"properties":{"employees":{"type":"array","items":{"type":"object","required":["uuid","balance"],"properties":{"uuid":{"type":"string","description":"The UUID of the employee"},"balance":{"type":"string","description":"The new balance for the employee"}}}}}}}},"required":true}}},"/oauth/token":{"post":{"summary":"Create a System Access Token or Refresh an Access Token","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."}],"x-gusto-rswag":true,"operationId":"oauth-access-token","security":[],"description":"Creates a system access token or refreshes an oauth access token","tags":["Introspection"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"create_token":{"value":{"$ref":"#/components/schemas/Authentication/x-examples/create_token"}},"refresh_token":{"value":{"$ref":"#/components/schemas/Authentication/x-examples/refresh_token"}}},"schema":{"$ref":"#/components/schemas/Authentication"}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Refresh Token Request","required":["client_id","client_secret","grant_type","refresh_token"],"properties":{"client_id":{"type":"string","description":"Your client ID","example":"qr6L_9FRkbMVL_GdwvrMW6Ef8tcU6NUxjWpOfqXqOG8"},"client_secret":{"type":"string","description":"Your client secret","example":"3aQSHRB3596nZhm6NdNBELZ1u9xbZmvCrKpBhbZYq6w"},"grant_type":{"type":"string","enum":["refresh_token"],"description":"Set system_access to create a system access token, refresh_token to refresh an existing token"},"refresh_token":{"type":"string","descrition":"The refresh token being exchanged for an access token code","example":"iEjL96L9Pndwmi-xVX3Q-xbrvvhnjHYGX87sopgGJ8E"},"redirect_uri":{"type":"string","description":"The redirect URI you set up via the Developer Portal"}}},{"type":"object","title":"System Access Token Request","required":["client_id","client_secret","grant_type"],"properties":{"client_id":{"type":"string","description":"Your client ID","example":"qr6L_9FRkbMVL_GdwvrMW6Ef8tcU6NUxjWpOfqXqOG8"},"client_secret":{"type":"string","description":"Your client secret","example":"3aQSHRB3596nZhm6NdNBELZ1u9xbZmvCrKpBhbZYq6w"},"grant_type":{"type":"string","description":"Set system_access to create a system access token, refresh_token to refresh an existing token","enum":["system_access"]}}}]}}},"required":true}}},"/v1/token_info":{"get":{"summary":"Get info about the current access token","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."}],"x-gusto-rswag":true,"operationId":"get-v1-token-info","security":[{"CompanyAccessAuth":[]}],"description":"Returns scope and resource information associated with the current access token. Use this endpoint to verify the following for the current access token:\n* Resource (company, employee, contractor, or application) and resource owner\n* Access level","tags":["Introspection"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"company_admin_token":{"value":{"$ref":"#/components/schemas/Token-Info/x-examples/company_admin_token"}},"system_token":{"value":{"$ref":"#/components/schemas/Token-Info/x-examples/system_token"}}},"schema":{"$ref":"#/components/schemas/Token-Info"}}}}}}},"/v1/webhook_subscriptions":{"get":{"summary":"List webhook subscriptions","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."}],"x-gusto-rswag":true,"operationId":"get-v1-webhook-subscriptions","security":[{"SystemAccessAuth":[]}],"description":"Returns all webhook subscriptions associated with the provided Partner API token.\n\n📘 System Access Authentication\n\nThis endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)\n\nscope: `webhook_subscriptions:read`","tags":["Webhooks"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"Example":{"value":[{"$ref":"#/components/schemas/Webhook-Subscription/x-examples/Example"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Webhook-Subscription"}}}}}}},"post":{"summary":"Create a webhook subscription","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."}],"x-gusto-rswag":true,"operationId":"post-v1-webhook-subscription","security":[{"SystemAccessAuth":[]}],"description":"Create a webhook subscription to receive events of the specified subscription_types whenever there is a state change.\n\n📘 System Access Authentication\n\nThis endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)\n\nscope: `webhook_subscriptions:write`","tags":["Webhooks"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"201":{"description":"created","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Webhook-Subscription/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Webhook-Subscription"}}}},"422":{"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","content":{"application/json":{"examples":{"webhook_subscription_url_missing":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/webhook_subscription_url_missing"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url","subscription_types"],"properties":{"url":{"type":"string","description":"The URL where webhook events will be POSTed."},"subscription_types":{"type":"array","description":"The types of events to subscribe to.","items":{"type":"string","enum":["BankAccount","Company","CompanyBenefit","Contractor","ContractorPayment","Employee","EmployeeBenefit","EmployeeJobCompensation","ExternalPayroll","Form","Location","Notification","Payroll","PayrollSync","PaySchedule","PeopleBatch","Signatory","TimeOffRequest"]}}}}}},"required":true}}},"/v1/webhook_subscriptions/{webhook_subscription_uuid}":{"get":{"summary":"Get a webhook subscription","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"webhook_subscription_uuid","in":"path","description":"The webhook subscription UUID.","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-webhook-subscription-uuid","security":[{"SystemAccessAuth":[]}],"description":"Returns the Webhook Subscription associated with the provided UUID.\n\n📘 System Access Authentication\n\nThis endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)\n\nscope: `webhook_subscriptions:read`","tags":["Webhooks"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Webhook-Subscription/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Webhook-Subscription"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update a webhook subscription","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"webhook_subscription_uuid","in":"path","description":"The webhook subscription UUID.","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-webhook-subscription-uuid","security":[{"SystemAccessAuth":[]}],"description":"Updates the Webhook Subscription associated with the provided UUID.\n\n📘 System Access Authentication\n\nThis endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)\n\nscope: `webhook_subscriptions:write`","tags":["Webhooks"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Webhook-Subscription/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Webhook-Subscription"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"webhook_subscription_invalid_entity_type":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/webhook_subscription_invalid_entity_type"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["subscription_types"],"properties":{"subscription_types":{"type":"array","description":"The types of events to subscribe to.","items":{"type":"string","enum":["BankAccount","Company","CompanyBenefit","Contractor","ContractorPayment","Employee","EmployeeBenefit","EmployeeJobCompensation","ExternalPayroll","Form","Location","Notification","Payroll","PayrollSync","PaySchedule","PeopleBatch","Signatory","TimeOffRequest"]}}}}}},"required":true}},"delete":{"summary":"Delete a webhook subscription","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"webhook_subscription_uuid","in":"path","description":"The webhook subscription UUID.","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-webhook-subscription-uuid","security":[{"SystemAccessAuth":[]}],"description":"Deletes the Webhook Subscription associated with the provided UUID.\n\n📘 System Access Authentication\n\nThis endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)\n\nscope: `webhook_subscriptions:write`","tags":["Webhooks"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"204":{"description":"No Content"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/webhook_subscriptions/{webhook_subscription_uuid}/request_verification_token":{"get":{"summary":"Request a verification token for a webhook subscription","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"webhook_subscription_uuid","in":"path","description":"The webhook subscription UUID.","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-webhook-subscription-verification-token-uuid","security":[{"SystemAccessAuth":[]}],"description":"Request that the webhook subscription `verification_token` be POSTed to the Subscription URL.\n\n📘 System Access Authentication\n\nThis endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)\n\nscope: `webhook_subscriptions:read`","tags":["Webhooks"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"No Content. The `verification_token` is POSTed to the Subscription URL.","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Webhook-Verification-Token-Response/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Webhook-Verification-Token-Response"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}}},"/v1/webhook_subscriptions/{webhook_subscription_uuid}/verify":{"put":{"summary":"Verify a webhook subscription","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"webhook_subscription_uuid","in":"path","description":"The webhook subscription UUID.","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-verify-webhook-subscription-uuid","security":[{"SystemAccessAuth":[]}],"description":"When a webhook subscription is created, a `verification_token` is POSTed to the registered webhook subscription URL. This `verify` endpoint needs to be called with `verification_token` before webhook events can be sent to the registered webhook URL.\n\nUse the /v1/webhook_subscriptions/{webhook_subscription_uuid}/request_verification_token API to resend the `verification_token` to the Subscriber.\n\n📘 System Access Authentication\n\nThis endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)\n\nscope: `webhook_subscriptions:write`","tags":["Webhooks"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"Example":{"value":{"$ref":"#/components/schemas/Webhook-Subscription/x-examples/Example"}}},"schema":{"$ref":"#/components/schemas/Webhook-Subscription"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"invalid_token":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_token"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["verification_token"],"properties":{"verification_token":{"type":"string","description":"The verification token received at the webhook subscription URL."}}}}},"required":true}}},"/v1/webhooks/health_check":{"get":{"summary":"Get the webhooks health status","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."}],"x-gusto-rswag":true,"operationId":"get-v1-webhooks-health_check","security":[{"SystemAccessAuth":[]}],"description":"Returns the health status (`healthy`, `unhealthy`, or `unknown`) of the webhooks system based on the last ten minutes of activity.\n\n📘 System Access Authentication\n\nThis endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)\n\nscope: `webhook_subscriptions:read`","tags":["Webhooks"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Webhooks-Health-Check-Status/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Webhooks-Health-Check-Status"}}}}}}},"/v1/wire_in_requests/{wire_in_request_uuid}":{"get":{"summary":"Get a single Wire In Request","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"wire_in_request_uuid","in":"path","description":"The UUID of the Wire In Request","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-wire_in_requests-wire_in_request_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Fetch a Wire In Request.\n\nscope: `payrolls:read`","tags":["Wire In Requests"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Wire-In-Request/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Wire-In-Request"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Submit a wire in request","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"wire_in_request_uuid","in":"path","description":"The UUID of the Wire In Request","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-wire_in_requests-wire_in_request_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Submit a wire in request for a payment\n\nscope: `payrolls:run`","tags":["Wire In Requests"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Wire-In-Request/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Wire-In-Request"}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"wire_in_request_invalid_amount_sent":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/wire_in_request_invalid_amount_sent"}},"wire_in_request_invalid_date_sent":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/wire_in_request_invalid_date_sent"}},"wire_in_request_missing_bank_name":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/wire_in_request_missing_bank_name"}},"wire_in_request_additional_notes_too_long":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/wire_in_request_additional_notes_too_long"}},"wire_in_request_not_awaiting_funds":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/wire_in_request_not_awaiting_funds"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Wire-In-Request-Update-Request-Body"}}},"required":true}}},"/v1/companies/{company_uuid}/wire_in_requests":{"get":{"summary":"Get all Wire In Requests for a company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"company_uuid","in":"path","description":"The UUID of the company","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.","schema":{"type":"integer"}},{"name":"per","in":"query","required":false,"description":"Number of objects per page. For majority of endpoints will default to 25","schema":{"type":"integer"}}],"x-gusto-rswag":true,"operationId":"get-companies-company_uuid-wire_in_request_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Fetches all Wire In Requests for a company.\n\nscope: `payrolls:read`","tags":["Wire In Requests"],"x-gusto-integration-type":["embedded"],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"example":{"value":{"$ref":"#/components/schemas/Wire-In-Request-List/x-examples/example"}}},"schema":{"$ref":"#/components/schemas/Wire-In-Request-List"}}}}}}},"/v1/employees/{employee_id}/work_addresses":{"get":{"summary":"Get an employee's work addresses","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-employees-employee_id-work_addresses","security":[{"CompanyAccessAuth":[]}],"description":"Returns a list of an employee's work addresses. Each address includes its effective\ndate and a boolean signifying if it is the currently active work address.\n\nscope: `employees:read`","tags":["Employee Addresses"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"List of employee work addresses","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee-Work-Addresses-List/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee-Work-Addresses-List"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create an employee work address","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","description":"The UUID of the employee","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-v1-employees-employee_id-work_addresses","security":[{"CompanyAccessAuth":[]}],"description":"The work address of an employee describes when an employee began working at an associated company location.\n\nscope: `employees:manage`","tags":["Employee Addresses"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"201":{"description":"created","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee-Work-Address/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee-Work-Address"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"location_uuid":{"type":"string","description":"Reference to a company location","example":"6a119be7-b4b0-4e27-aaa0-89d5f2524635"},"effective_date":{"type":"string","format":"date","description":"Date the employee began working at the company location","example":"2023-05-15"}}}}},"required":true}}},"/v1/work_addresses/{work_address_uuid}":{"get":{"summary":"Get an employee work address","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"work_address_uuid","in":"path","description":"The UUID of the work address","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"get-v1-work_addresses-work_address_uuid","security":[{"CompanyAccessAuth":[]}],"description":"The work address of an employee is used for payroll tax purposes.\n\nscope: `employees:read`","tags":["Employee Addresses"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee-Work-Address/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee-Work-Address"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"put":{"summary":"Update an employee work address","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"work_address_uuid","in":"path","description":"The UUID of the work address","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"put-v1-work_addresses-work_address_uuid","security":[{"CompanyAccessAuth":[]}],"description":"The work address of an employee is used for payroll tax purposes.\n\nscope: `employees:manage`","tags":["Employee Addresses"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"success_status":{"value":{"$ref":"#/components/schemas/Employee-Work-Address/x-examples/success_status"}}},"schema":{"$ref":"#/components/schemas/Employee-Work-Address"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Versionable-Required"},{"type":"object","properties":{"location_uuid":{"type":"string","description":"Reference to a company location","example":"6a119be7-b4b0-4e27-aaa0-89d5f2524635"},"effective_date":{"type":"string","format":"date","example":"2023-05-15"}}}]}}},"required":true}},"delete":{"summary":"Delete an employee's work address","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"work_address_uuid","in":"path","description":"The UUID of the work address","required":true,"schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"delete-v1-work_addresses-work_address_uuid","security":[{"CompanyAccessAuth":[]}],"description":"Used for deleting an employee's work address. Cannot delete the employee's active work address.\n\nscope: `employees:manage`","tags":["Employee Addresses"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"204":{"description":"no content"},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"examples":{"invalid_attribute":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}}}},"/v1/employees/{employee_id}/ytd_benefit_amounts_from_different_company":{"get":{"summary":"Get year-to-date benefit amounts from a different company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","required":true,"description":"The UUID of the employee","schema":{"type":"string"}},{"name":"tax_year","in":"query","required":false,"schema":{"type":"integer","minimum":2000,"maximum":2999,"example":2024},"description":"The tax year for which to retrieve YTD benefit amounts. Defaults to current year if not specified."}],"x-gusto-rswag":true,"operationId":"get-employee-ytd-benefit-amounts-from-different-company","security":[{"CompanyAccessAuth":[]}],"description":"Retrieves year-to-date benefit amounts that were contributed at a different company for the specified employee.\nReturns benefit amounts for the requested tax year (defaults to current year if not specified).\n\nThis endpoint only supports retrieving outside contributions for 401(k) benefits.\n\nscope: `employee_benefits:read`","tags":["Employee Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"200":{"description":"OK","content":{"application/json":{"examples":{"Ytd-Benefit-Amounts-List":{"value":{"$ref":"#/components/schemas/Ytd-Benefit-Amounts-From-Different-Company/x-examples/Ytd-Benefit-Amounts-List"}}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/Ytd-Benefit-Amounts-From-Different-Company"}}}}},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}}}},"post":{"summary":"Create year-to-date benefit amounts from a different company","parameters":[{"name":"X-Gusto-API-Version","in":"header","schema":{"type":"string","enum":["2026-06-15"],"default":"2026-06-15"},"description":"Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used."},{"name":"employee_id","in":"path","required":true,"description":"The UUID of the employee","schema":{"type":"string"}}],"x-gusto-rswag":true,"operationId":"post-employee-ytd-benefit-amounts-from-different-company","security":[{"CompanyAccessAuth":[]}],"description":"Year-to-date benefit amounts from a different company represents the amount of money added to an employee's plan during a current year, made outside of the current contribution when they were employed at a different company.\n\nThis endpoint only supports passing outside contributions for 401(k) benefits.\n\nscope: `employee_benefits:write`","tags":["Employee Benefits"],"x-gusto-integration-type":["embedded","app-integrations"],"responses":{"204":{"description":"No Content"},"404":{"description":"Not Found\n\nThe requested resource does not exist. Make sure the provided UUID is valid.\n","content":{"application/json":{"examples":{"not_found":{"value":{"$ref":"#/components/schemas/Not-Found-Error-Object/x-examples/not_found"}}},"schema":{"$ref":"#/components/schemas/Not-Found-Error-Object"}}}},"422":{"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","content":{"application/json":{"examples":{"ytd_benefit_amounts_invalid_tax_year":{"value":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/ytd_benefit_amounts_invalid_tax_year"}}},"schema":{"$ref":"#/components/schemas/Unprocessable-Entity-Error-Object"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ytd-Benefit-Amounts-From-Different-Company-Body"}}},"required":true}}}}}