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: Tax Payments
  - name: Tax Filings
  - 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: Reverse Wire Transactions
  - name: Salary Estimates
  - name: Reimbursements
  - name: Member Portal Invitations
info:
  title: Gusto API
  version: '2025-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: deprecated
servers:
  - url: https://api.gusto-demo.com
    description: Demo
    x-speakeasy-server-id: demo
  - url: https://api.gusto.com
    description: Prod
    x-speakeasy-server-id: prod
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
        warnings:
          type: array
          description: An array of warning objects that provide additional information about the address. Warnings do not prevent the address from being saved.
          items:
            "$ref": "#/components/schemas/Warning-Object"
      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.
    Conflict-Error-Object:
      description: "Conflict\n  \nThis may happen when the resource version provided does not match the current version — retrieve the latest version and retry — or when the request conflicts with another in-progress operation on the same resource. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details."
      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.
        locked_payroll:
          errors:
            - error_key: base
              category: invalid_operation
              message: This payroll is currently being processed by another request. Please try again later.
    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:
        tax_filing_invalid_status:
          errors:
            - error_key: status
              category: invalid_attribute_value
              message: 'Status must be one of: not_started, in_progress, blocked, accepted, not_required, failed'
        tax_filing_invalid_sort_by:
          errors:
            - error_key: sort_by
              category: invalid_attribute_value
              message: Sort by must be one of period_start, period_end, due_date, filed_at, optionally suffixed with :asc or :desc
        tax_filing_invalid_period_start:
          errors:
            - error_key: period_start
              category: invalid_attribute_value
              message: Period start must be a valid ISO 8601 date
        tax_filing_invalid_jurisdiction:
          errors:
            - error_key: jurisdiction
              category: invalid_attribute_value
              message: 'Jurisdiction must be two-letter state codes or US (invalid: XX)'
        tax_payment_invalid_sort_by:
          errors:
            - error_key: sort_by
              category: invalid_parameter
              message: 'Unknown sort_by: bogus:asc. Must be one of amount, due_date, payment_sent_on, period_end, period_start, optionally suffixed with :asc or :desc'
        tax_payment_inverted_range:
          errors:
            - error_key: due_date_to
              category: invalid_attribute_value
              message: Due date to must be greater than or equal to due date from
        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_create_unfunded_payments:
          errors:
            - error_key: base
              category: invalid_operation
              message: FundingMethod has unfunded payments
        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'
        plaid_bank_account_linking_unavailable:
          errors:
            - error_key: base
              category: invalid_operation
              message: This company's bank account can't be linked through this endpoint. Contact Gusto support to set it up.
        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.
        migrate_company_invalid_ip:
          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.
        migrate_company_invalid_signatory:
          errors:
            - error_key: email
              category: invalid_attribute_value
              message: A valid signatory email is required to perform this operation.
        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.
        nyc_withholding_allowance_required:
          errors:
            - error_key: states
              category: nested_errors
              errors:
                - error_key: questions
                  category: nested_errors
                  metadata:
                    state: NY
                  errors:
                    - error_key: answers
                      category: nested_errors
                      metadata:
                        key: total_allowances_nyc
                      errors:
                        - error_key: value
                          category: invalid_attribute_value
                          message: NYC Withholding Allowance is required for employees who live in New York City
                          metadata:
                            valid_from: '2010-01-01'
                            valid_up_to:
        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
        pay_schedule_workweek_start_day_not_yet_changeable:
          errors:
            - error_key: workweek_start_day
              category: invalid_attribute_value
              message: Workweek start day can only be changed once per pay period. Please wait until 2022-10-05 to change it again.
        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:
                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:
                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.
        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.
        maximum_off_roster_additions_surpassed:
          errors:
            - error_key: employee_uuids
              category: invalid_attribute_value
              message: Cannot add more than 25 new employees to the payroll per call.
        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.
        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: benefit_type
              category: invalid_parameter
              message: This application is not permitted to modify benefits of type 100 (Other (taxable)).
        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
        earning_type_invalid_category:
          errors:
            - error_key: category
              category: invalid_attribute_value
              message: Category is not valid
        earning_type_included_in_overtime_pay_invalid_category:
          errors:
            - error_key: included_in_overtime_pay
              category: invalid_attribute_value
              message: Category must be 'Other' to set included_in_overtime_pay
        earning_type_category_not_modifiable:
          errors:
            - error_key: category
              category: invalid_attribute_value
              message: Category is not modifiable
        earning_type_included_in_overtime_pay_not_modifiable:
          errors:
            - error_key: included_in_overtime_pay
              category: invalid_attribute_value
              message: Included in overtime pay is not modifiable
        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.
      x-speakeasy-name-override: UnprocessableEntityError
    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:
            "$ref": "#/components/schemas/Entity-Error-Object"
    Warning-Object:
      type: object
      properties:
        error_key:
          type: string
          description: Specifies where the warning occurs. Typically identifies the attribute or parameter related to the warning.
        category:
          type: string
          description: Specifies the type of warning. Can be used to build custom warning handling.
        message:
          type: string
          description: Provides details about the warning. The message can be surfaced directly to the end user.
    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:
          last_name: Koss
          email: keena.feest@kiehn.co.uk
          company_uuid: e904cc79-818a-4da8-9d37-0be0a86fdda8
          manager_uuid:
          version: a5cec1f1c0135feb3e76ca6ea3c46176
          current_employment_status: full_time
          onboarding_status: onboarding_completed
          preferred_first_name:
          department_uuid:
          employee_code: 46f036
          payment_method: Direct Deposit
          department:
          terminated: false
          two_percent_shareholder: false
          onboarded: true
          historical: false
          has_ssn: true
          onboarding_documents_config:
            uuid:
            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:
              state_wc_class_code:
              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:
          work_email:
          member_portal_invitation_status:
            status: sent
            token_expired: false
            welcome_email_sent_at: '2024-01-15T14:30:00Z'
            last_password_resent_at:
          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
    Employee-Show:
      title: Employee-Show
      description: An employee, with additional fields that are only ever returned on GET requests gated behind the `include` query parameter.
      x-examples:
        success_status:
          uuid: d7282d99-ab6b-42f5-ba45-f4a670e886a8
          first_name: Boaty
          middle_initial:
          last_name: Koss
          email: keena.feest@kiehn.co.uk
          company_uuid: e904cc79-818a-4da8-9d37-0be0a86fdda8
          manager_uuid:
          version: a5cec1f1c0135feb3e76ca6ea3c46176
          current_employment_status: full_time
          onboarding_status: onboarding_completed
          preferred_first_name:
          department_uuid:
          employee_code: 46f036
          payment_method: Direct Deposit
          department:
          terminated: false
          two_percent_shareholder: false
          onboarded: true
          historical: false
          has_ssn: true
          onboarding_documents_config:
            uuid:
            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:
              state_wc_class_code:
              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:
          work_email:
          member_portal_invitation_status:
            status: sent
            token_expired: false
            welcome_email_sent_at: '2024-01-15T14:30:00Z'
            last_password_resent_at:
          partner_portal_invitation_sent: true
          company_name: Acme Consulting
          current_home_address:
            street_1: 412 Kiera Stravenue
            street_2: Suite 391
            city: San Francisco
            state: CA
            zip: '94107'
            country: USA
            active: true
            uuid: 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
              uuid: sample-uuid-123231
      allOf:
        - "$ref": "#/components/schemas/Employee"
        - type: object
          additionalProperties: true
          properties:
            company_name:
              type: string
              description: The name of the company the employee is associated with. Only included when the include param has the company_name value set.
            current_home_address:
              "$ref": "#/components/schemas/Employee-Home-Address"
              description: The employee's current home address. Only included when the include param has the current_home_address value set.
            all_home_addresses:
              type: array
              items:
                "$ref": "#/components/schemas/Employee-Home-Address"
              description: All of the employee's home addresses, past and present. Only included when the include param has the all_home_addresses value set.
      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:
          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 current compensation rate of the job.
          readOnly: true
        payment_unit:
          type:
            - string
            - 'null'
          description: The payment unit of the current compensation for the job.
          readOnly: true
        current_compensation_uuid:
          type:
            - string
            - 'null'
          description: The UUID of the current compensation of the job. Null when the job has no current compensation.
          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
          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:
          state_wc_class_code:
          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:
          state_wc_class_code:
          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:
          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:
          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:
          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:
          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:
          total_amount:
          pay_period_maximum: '100.00'
          deduct_as_percentage: true
          garnishment_type:
          child_support:
        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:
          recurring: true
          annual_maximum:
          total_amount:
          pay_period_maximum:
          deduct_as_percentage: false
          garnishment_type:
          child_support:
        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:
          recurring: true
          annual_maximum:
          total_amount:
          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:
            remittance_number:
            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:
            total_amount:
            pay_period_maximum: '100.00'
            deduct_as_percentage: true
            garnishment_type:
            child_support:
          - 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:
            recurring: true
            annual_maximum:
            total_amount:
            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:
              remittance_number:
              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:
          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:
          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:
          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:
        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:
            - 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.

            Supported categories:

            - `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.

            This list may grow over time as new validation rules are added.
          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.
        warnings:
          type: array
          description: An array of warning objects that provide additional information about the address. Warnings do not prevent the address from being saved.
          items:
            "$ref": "#/components/schemas/Warning-Object"
      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>.

'
                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:
              - 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.

'
                key: withholding_allowance
                input_question_format:
                  type: Number
                answers:
                  - value: 1
                    valid_from: '2010-01-01'
                    valid_up_to:
              - 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:
              - 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:
      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:
            splits:
      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:
            splits:
          - 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:
                encrypted_account_number:
                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:
            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:
            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:
            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:
            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:
          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_pilot: 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:
      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.
                    breakdowns:
                      type: array
                      description: |
                        Per-workweek amounts to record for this compensation. Not
                        applicable to reimbursements. Submitted breakdowns must tile the
                        pay period's workweeks exactly (no gaps or overlaps), and their
                        amounts must sum to the compensation's total `amount`.
                      items:
                        type: object
                        properties:
                          start_date:
                            type: string
                            format: date
                            description: The start date of the workweek.
                          end_date:
                            type: string
                            format: date
                            description: The end date of the workweek.
                          amount:
                            type: string
                            format: float
                            description: The dollar amount for this workweek.
              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.
                    breakdowns:
                      type: array
                      description: |
                        Per-workweek hours to record for this compensation. Submitted
                        breakdowns must tile the pay period's workweeks exactly (no gaps
                        or overlaps). Either every hourly compensation for a job must
                        include breakdowns, or none of them may. Hours must sum to the
                        compensation's total `hours`.
                      items:
                        type: object
                        properties:
                          start_date:
                            type: string
                            format: date
                            description: The start date of the workweek.
                          end_date:
                            type: string
                            format: date
                            description: The end date of the workweek.
                          hours:
                            type: string
                            format: float
                            description: The number of hours worked during this workweek.
              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.
                  When provided, the supplied override takes precedence over any persistent withholding schedule for this run.
                  This field is in limited release; if your application does not have access, requests including it are silently ignored.
                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_pilot: 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:
      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_pilot:
          "$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_pilot: false
          processed: false
          processed_date:
          calculated_at:
          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:
      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_pilot:
          "$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 is an auto pilot payroll
      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
            - 'null'
          description: The start date, inclusive, of the pay period.
          readOnly: true
        end_date:
          type:
            - string
            - 'null'
          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
          description: The normal check date for the associated pay period.
          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
          description: expected_check_date > initial_check_date.
          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: number
                minLength: 1
            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: number
                readOnly: true
              company_contribution:
                type: number
                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: 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.
                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
        pay_adjustments:
          type: array
          uniqueItems: false
          description: |
            Overtime adjustments for workweeks that have earnings on more than one payroll.
            When earnings on one payroll change the regular rate of pay for a workweek whose
            overtime is paid on another payroll, the resulting difference in overtime pay is
            reported here. For example, a bonus on this payroll for a workweek that had
            overtime paid on an earlier payroll. Adjustment amounts are included in
            `gross_pay` but are not repeated in `hourly_compensations`. Only present on
            calculated or processed payrolls.
          items:
            type: object
            properties:
              name:
                type: string
                description: The compensation type the adjustment applies to (e.g. `Overtime`, `Double Overtime`).
              amount:
                type: string
                format: float
                description: The dollar amount of the adjustment.
            readOnly: true
          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:
            - number
            - 'null'
          description: The employee's gross pay, equal to regular wages + cash tips + payroll tips + any other additional earnings + `pay_adjustments`, excluding imputed income.
          readOnly: true
        net_pay:
          type:
            - number
            - 'null'
          description: The employee's net pay, equal to gross_pay - employee taxes - employee deductions or garnishments - cash tips. This value is only available for processed payrolls.
          readOnly: true
        check_amount:
          type:
            - number
            - 'null'
          description: The employee's check amount, 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, bonuses, and one time reimbursements. If this payroll has been processed, only fixed compensations with a value greater than 0.00 are returned. For an unprocessed payroll, all active fixed compensations are returned.
          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
              breakdowns:
                type: array
                uniqueItems: false
                description: |
                  Per-workweek amounts for this compensation, one entry per workweek
                  overlapping the pay period.
                items:
                  type: object
                  properties:
                    start_date:
                      type: string
                      format: date
                      description: The start date of the workweek.
                    end_date:
                      type: string
                      format: date
                      description: The end date of the workweek.
                    amount:
                      type: string
                      format: float
                      description: The dollar amount for this workweek.
                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
              breakdowns:
                type: array
                uniqueItems: false
                description: |
                  Per-workweek hours for this compensation, one entry per workweek
                  overlapping the pay period.
                items:
                  type: object
                  properties:
                    start_date:
                      type: string
                      format: date
                      description: The start date of the workweek.
                    end_date:
                      type: string
                      format: date
                      description: The end date of the workweek.
                    hours:
                      type: string
                      format: float
                      description: The number of hours worked during this workweek.
                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.
              final_payout_unused_hours_input:
                type:
                  - string
                  - 'null'
                description: The outstanding hours paid upon termination. This field is only applicable for termination payrolls.
              approved_request_hours:
                type:
                  - string
                  - 'null'
                description: 'Total hours of approved time off requests overlapping this pay period for this time-off policy. Only populated on unprocessed (draft) payrolls; absent on processed payrolls. Read-only.

'
                readOnly: true
        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.
            `federal` is null when no federal one-time override is set; `state` is an empty
            array when no state one-time overrides are set.
          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
          properties:
            reverse_wire_detail_id:
              type:
                - integer
                - 'null'
              description: ID of the reverse wire detail
              readOnly: true
            bank_account_last_four_digits:
              type:
                - string
                - 'null'
              description: Last 4 digits of the bank account number for the reverse wire
              readOnly: true
          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_pilot: 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:
        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:
              status: unresolved
          payroll_uuid: b441a30b-2adb-489e-b7b7-9d094011a3f8
          company_uuid: 9aa93530-43d5-484e-b608-33214109420d
          off_cycle: false
          auto_pilot: 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:
        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:
              status: unresolved
          payroll_uuid: b441a30b-2adb-489e-b7b7-9d094011a3f8
          company_uuid: 9aa93530-43d5-484e-b608-33214109420d
          off_cycle: false
          auto_pilot: 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:
        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:
              status: pending_review
          payroll_uuid: b441a30b-2adb-489e-b7b7-9d094011a3f8
          company_uuid: 9aa93530-43d5-484e-b608-33214109420d
          off_cycle: false
          auto_pilot: 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:
        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:
                    reverse_wire_detail_id: 12345
                    bank_account_last_four_digits: '1234'
              selected_option:
              status: resolved
          payroll_uuid: b441a30b-2adb-489e-b7b7-9d094011a3f8
          company_uuid: 9aa93530-43d5-484e-b608-33214109420d
          off_cycle: false
          auto_pilot: 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:
      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_pilot:
          "$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_pilot: 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:
          calculated_at:
          pay_period:
            start_date: '2025-06-10'
            end_date: '2025-06-16'
            pay_schedule_uuid:
          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:
      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_pilot:
          "$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"
        workweeks:
          type:
            - array
            - 'null'
          description: |
            The workweeks overlapping this payroll's pay period, one entry per workweek.
            Null when workweek boundaries can't be determined for this payroll (e.g. some
            off-cycle payrolls without a defined payment period).
          items:
            type: object
            properties:
              start_date:
                type: string
                format: date
                description: The start date of the workweek.
              end_date:
                type: string
                format: date
                description: The end date of the workweek.
          readOnly: true
        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
          payroll_uuid: 4428f108-e46e-4ab6-ba20-03cea031cfc0
          company_uuid: 42b5333b-ee39-493a-bf7e-f41f2bd67848
          payroll_status_meta:
            cancellable: false
            expected_check_date: '2025-06-20'
            initial_check_date: '2025-06-20'
            expected_debit_time: '2025-06-18T23:00:00Z'
            payroll_late: false
            initial_debit_cutoff_time: '2025-06-18T23:00:00Z'
          off_cycle: false
          auto_pilot: false
          processed: false
          processed_date:
          calculated_at:
          pay_period:
            start_date: '2025-06-02'
            end_date: '2025-06-15'
            pay_schedule_uuid: 2c4e6a8b-1d3f-4a5c-9e7b-0f2d4c6a8e1b
          workweeks:
            - start_date: '2025-06-02'
              end_date: '2025-06-08'
            - start_date: '2025-06-09'
              end_date: '2025-06-15'
          check_date: '2025-06-20'
          external: false
          payroll_deadline: '2025-06-18T23: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:
          processing_request:
          employee_compensations:
            - employee_uuid: 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
              version: 3f9a1c7e5b2d4086a1e3c5b7d9f02468
              excluded: false
              first_name: Alex
              preferred_first_name: Alex
              last_name: Rivera
              payment_method: Direct Deposit
              memo:
              gross_pay: 2837.5
              hourly_compensations:
                - flsa_status: Nonexempt
                  name: Regular Hours
                  job_uuid: 6f1e2d3c-4b5a-4968-8776-655443322110
                  compensation_multiplier: 1.0
                  hours: '80.000'
                  breakdowns:
                    - start_date: '2025-06-02'
                      end_date: '2025-06-08'
                      hours: '40.000'
                    - start_date: '2025-06-09'
                      end_date: '2025-06-15'
                      hours: '40.000'
                - flsa_status: Nonexempt
                  name: Overtime
                  job_uuid: 6f1e2d3c-4b5a-4968-8776-655443322110
                  compensation_multiplier: 1.5
                  hours: '5.000'
                  breakdowns:
                    - start_date: '2025-06-02'
                      end_date: '2025-06-08'
                      hours: '2.000'
                    - start_date: '2025-06-09'
                      end_date: '2025-06-15'
                      hours: '3.000'
                - flsa_status: Nonexempt
                  name: Double overtime
                  job_uuid: 6f1e2d3c-4b5a-4968-8776-655443322110
                  compensation_multiplier: 2.0
                  hours: '0.000'
                  breakdowns: []
              fixed_compensations:
                - name: Bonus
                  amount: '500.00'
                  job_uuid: 6f1e2d3c-4b5a-4968-8776-655443322110
                  breakdowns:
                    - start_date: '2025-06-02'
                      end_date: '2025-06-08'
                      amount: '250.00'
                    - start_date: '2025-06-09'
                      end_date: '2025-06-15'
                      amount: '250.00'
                - name: Commission
                  amount: '150.00'
                  job_uuid: 6f1e2d3c-4b5a-4968-8776-655443322110
              paid_time_off: []
              reimbursements: []
              deductions: []
              custom_withholdings:
                federal:
                state: []
        with_approved_request_hours:
          uuid: 4428f108-e46e-4ab6-ba20-03cea031cfc0
          payroll_uuid: 4428f108-e46e-4ab6-ba20-03cea031cfc0
          company_uuid: 42b5333b-ee39-493a-bf7e-f41f2bd67848
          processed: false
          pay_period:
            start_date: '2025-06-10'
            end_date: '2025-06-16'
            pay_schedule_uuid:
          workweeks:
            - start_date: '2025-06-10'
              end_date: '2025-06-15'
            - start_date: '2025-06-16'
              end_date: '2025-06-16'
          check_date: '2025-06-17'
          employee_compensations:
            - employee_uuid: 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
              paid_time_off:
                - name: Vacation Hours
                  hours: '0.0'
                  approved_request_hours: '8.0'
      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_pilot:
          "$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"
        workweeks:
          type:
            - array
            - 'null'
          description: |
            The workweeks overlapping this payroll's pay period, one entry per workweek.
            Null when workweek boundaries can't be determined for this payroll (e.g. some
            off-cycle payrolls without a defined payment period).
          items:
            type: object
            properties:
              start_date:
                type: string
                format: date
                description: The start date of the workweek.
              end_date:
                type: string
                format: date
                description: The end date of the workweek.
          readOnly: true
        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.
        warnings:
          type: array
          description: An array of warning objects that provide additional information about the address. Warnings do not prevent the address from being saved.
          items:
            "$ref": "#/components/schemas/Warning-Object"
    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:
          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:
                  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:
                  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.
            When true, the employee will be prompted to complete Form I-9 as part of their onboarding.
          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:
          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.
            When true, the employee will be prompted to complete Form I-9 as part of their onboarding.
      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:
          alt_procedure:
        citizen_authorization:
          uuid: a12bc345-6789-4def-abcd-ef0123456789
          version: 52b7c567242cb7393b2a206ed6a86afcb
          form_uuid:
          authorization_status: citizen
          document_type:
          has_document_number: false
          expiration_date:
          country:
          employer_signed: false
          employee_signed: false
          additional_info:
          alt_procedure:
        employer_signed_authorization:
          uuid: 7f2337f9-9b78-44b9-aeed-be4777b833a8
          version: 8bc7393b2a206ed6a86afcb4d00c1785
          form_uuid: c54046f7-1be4-4c54-8194-f4842c30c86d
          authorization_status: citizen
          document_type:
          has_document_number: false
          expiration_date:
          country:
          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.
            - `citizen`: A citizen is someone who was born in the United States or is a naturalized citizen living in the United States.
            - `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.
            - `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.
            - `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.
          enum:
            - citizen
            - noncitizen
            - permanent_resident
            - alien
        document_type:
          type: string
          description: |
            The type of document an employee holds, based on their authorization status.
            - This is unused for authorization status `citizen` or `noncitizen`.
            - If the authorization status is `permanent_resident`, this must be `uscis_alien_registration_number`.
            - If the authorization status is `alien`, this is required and may be any of the valid values.
          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.
            - For `document_type:'uscis_alien_registration_number'`, this must be a USCIS Number/A-Number, which is 7 to 9 digits.
            - For `document_type:'form_i94'`, this must be a Form I-94 Admission Number, which is 11 digits.
            - For `document_type:'foreign_passport'`, this must be the passport number.

            This is required when the document type is present.
        country:
          type: string
          description: |
            The document's country of issuance.

            This is required when the document type is `foreign_passport`.
        expiration_date:
          type: string
          description: |
            The document's expiration date.

            This may only be used when the authorization status is `alien`.
      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.

        Send 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.
      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.

'
          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:
          quarter:
          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:
          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:
          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:
          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:
          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:
          document_content_type:
      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:
              x: 69
              "y": 94
              width: 261
              height: 13
              page_number: 0
              data_type: text
              required: true
            - key: optional_text1596141704672
              value:
              x: 69
              "y": 118
              width: 262
              height: 13
              page_number: 0
              data_type: text
              required: false
          signed_at:
          description: Form W-9, Request for Taxpayer Identification Number and Certification
          requires_signing: true
          draft: false
          year:
          quarter:
      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:
          quarter:
      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:
          possible_liabilities:
            - liability_amount: '0.0'
              payroll_check_date:
              external_payroll_uuid:
            - 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:
                name: Reimbursement
            paid_time_off:
              - uuid: 7dcdcb77-22f9-11f1-ad28-0242ac100003
                name: Vacation Hours
              - uuid: 7dcdcc8b-22f9-11f1-ad28-0242ac100003
                name: Sick Hours
              - uuid:
                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:
              skippable: false
              requirements:
                - add_addresses
                - add_employees
            - title: Select a Pay Schedule
              id: payroll_schedule
              required: true
              completed: false
              completed_at:
              skippable: false
              requirements: []
            - title: Sign Documents
              id: sign_all_forms
              required: true
              completed: false
              completed_at:
              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:
              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.
            - `1-day`: Next-day ACH (only for partners that opt in).
            - `2-day`: Two-day ACH.
            - `4-day`: Standard ACH.
          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:
          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.

'
          enum:
            - Fixed
            - Hourly
        start_date:
          type: string
          description: 'The day when the contractor will start working for the company.

'
          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.
            Self-onboarding is recommended so that contractors receive Gusto accounts.
            If self_onboarding is true, then email is required.
        email:
          type: string
          description: The contractor’s email address.
        work_email:
          type: string
          description: The work email address of the contractor. 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).
        first_name:
          type: string
          description: |-
            The contractor’s first name.
            This attribute is required for `Individual` contractors and will be ignored for `Business` contractors.
        last_name:
          type: string
          description: |-
            The contractor’s last name.
            This attribute is required for `Individual` contractors and will be ignored for `Business` contractors.
        middle_initial:
          type: string
          description: |-
            The contractor’s middle initial.
            This 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.
            This 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.
            This value is used when generating the new hire report.
            This attribute is required for `Individual` contractors if `file_new_hire_report` is true and will be ignored for `Business` contractors.
        ssn:
          type: string
          pattern: "[0-9]{9}"
          description: |-
            This attribute is optional for `Individual` contractors and will be ignored for `Business` contractors.
            Social security number is needed to file the annual 1099 tax form.
        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.
            This 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. '
        work_email:
          type:
            - string
            - 'null'
          description: The work email address of the contractor. 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).
        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.
            This 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:
          ein:
          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:
          upcoming_employment:
          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:
          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:
          last_name:
          middle_initial:
          business_name: Labadie-Stroman
          ein: XX-XXX0001
          has_ein: true
          has_ssn: false
          email: jonatan@kerluke.info
          file_new_hire_report: false
          work_state:
          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:
          department:
          department_title:
          dismissal_date:
          upcoming_employment:
          dismissal_cancellation_eligible: false
          rehire_cancellation_eligible: false
          member_portal_invitation_status:
          partner_portal_invitation_sent: false
    Contractor-Show:
      title: Contractor-Show
      description: A contractor, with additional fields that are only ever returned on GET requests gated behind the `include` query parameter.
      allOf:
        - "$ref": "#/components/schemas/Contractor"
        - type: object
          additionalProperties: true
          properties:
            company_name:
              type: string
              description: The name of the company the contractor is associated with. Only included when the include param has the company_name value set.
      x-examples:
        Individual Contractor:
          uuid: c9fc1ad3-c107-4e7b-aa21-2dd4b00a7a07
          company_name: Acme Consulting
          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:
          ein:
          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:
          upcoming_employment:
          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:
          partner_portal_invitation_sent: true
        Business Contractor:
          uuid: c7c0659c-21a6-4b4e-b74c-9252576fc68c
          company_name: Acme Consulting
          company_uuid: 0ec4ae6e-e436-460d-b63c-94a14503d16f
          wage_type: Fixed
          start_date: '2022-01-01'
          is_active: true
          version: 8aab307f1e8ed788697f8986346af559
          type: Business
          first_name:
          last_name:
          middle_initial:
          business_name: Labadie-Stroman
          ein: XX-XXX0001
          has_ein: true
          has_ssn: false
          email: jonatan@kerluke.info
          file_new_hire_report: false
          work_state:
          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:
          department:
          department_title:
          dismissal_date:
          upcoming_employment:
          dismissal_cancellation_eligible: false
          rehire_cancellation_eligible: false
          member_portal_invitation_status:
          partner_portal_invitation_sent: false
    Show-Contractors:
      type: array
      items:
        "$ref": "#/components/schemas/Contractor-Show"
      x-examples:
        success_status:
          - uuid: c9fc1ad3-c107-4e7b-aa21-2dd4b00a7a07
            company_name: Acme Consulting
            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:
            ein:
            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:
            upcoming_employment:
            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:
            partner_portal_invitation_sent: true
          - uuid: c7c0659c-21a6-4b4e-b74c-9252576fc68c
            company_name: Acme Consulting
            company_uuid: 0ec4ae6e-e436-460d-b63c-94a14503d16f
            wage_type: Fixed
            start_date: '2022-01-01'
            is_active: true
            version: 8aab307f1e8ed788697f8986346af559
            type: Business
            first_name:
            last_name:
            middle_initial:
            business_name: Labadie-Stroman
            ein: XX-XXX0001
            has_ein: true
            has_ssn: false
            email: jonatan@kerluke.info
            file_new_hire_report: false
            work_state:
            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:
            department:
            department_title:
            dismissal_date:
            upcoming_employment:
            dismissal_cancellation_eligible: false
            rehire_cancellation_eligible: false
            member_portal_invitation_status:
            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
      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.00'
        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.5'
        bonus:
          type: string
          format: float
          description: If the contractor is on an hourly wage, this is the bonus the contractor earned.
          example: '500.00'
        reimbursement:
          type: string
          format: float
          description: Reimbursed wages for the contractor.
          example: '20.00'
      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: string
                format: float
                description: Fixed wage amount for the payment.
              hours:
                type: string
                format: float
                description: Number of hours worked for the payment.
              bonus:
                type: string
                format: float
                description: Bonus amount for the payment.
              reimbursement:
                type: string
                format: float
                description: Reimbursement amount for the payment.
      x-examples:
        Example:
          contractor_payments:
            - bonus: '0.00'
              date: '2022-09-02'
              contractor_uuid: 5376e95b-cca0-482b-bb81-aba5e360eb04
              hours: '0.00'
              payment_method: Check
              reimbursement: '0.00'
              wage: '123.00'
            - bonus: '0.00'
              date: '2022-09-02'
              contractor_uuid: 0c984dce-de9a-47db-8bfb-5f0c823afe6f
              hours: '0.00'
              payment_method: Check
              reimbursement: '0.00'
              wage: '456.50'
      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
      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
      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:
          splits:
        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

        For 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:
        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.

'
          example: companies:read public
        resource:
          type:
            - object
            - 'null'
          description: |
            The resource associated with this access token. Null when
            the token has no associated resource.
          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.

'
              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
            system-level tokens or when the owner cannot be determined.
          properties:
            type:
              type: string
              enum:
                - CompanyAdmin
                - Employee
                - Contractor
              description: |
                The type of resource owner:
                - `CompanyAdmin`: A company administrator
                - `Employee`: An employee
                - `Contractor`: A contractor
              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:
    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_pilot: 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:
          custom_name: every 1st and 15th of the month
          auto_payroll: true
          active: true
          auto_payroll_enablement_blockers:
      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.

        Response includes frequency, anchor dates, optional day_1/day_2 for monthly/semi-monthly, auto_pilot (or auto_payroll for API version 2025-11-15 and later), and auto_payroll_enablement_blockers when Autopayroll is disabled.

        **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.
      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_pilot:
          type: boolean
          description: |
            With automatic payroll enabled, payroll runs automatically one day before payroll deadlines. When false, payroll does not run automatically.
            For API version 2025-11-15 and later the response uses auto_payroll (Autopayroll) instead.
          readOnly: true
        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).

        For API version 2025-11-15 and later, responses use `auto_payroll`; earlier versions use `auto_pilot` for the same semantic.
      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_pilot:
          type: boolean
          description: |
            With automatic payroll enabled, payroll runs automatically one day before payroll deadlines. When false, payroll does not run automatically.
            For API version 2025-11-15 and later the response uses auto_payroll (Autopayroll) instead.
          readOnly: true
        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"
        workweek_start_day:
          "$ref": "#/components/schemas/Pay-Schedule-Workweek-Start-Day"
      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_pilot: false
          custom_name: A new monthly pay schedule
          active: true
          auto_payroll_enablement_blockers:
          workweek_start_day: Monday
        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:
          custom_name: every 1st and 15th of the month
          auto_pilot: true
          active: true
          auto_payroll_enablement_blockers:
          workweek_start_day: Monday
    Pay-Schedule-List-Item:
      type: object
      title: Pay Schedule
      description: 'Pay schedule returned from [GET /v1/companies/{company_id}/pay_schedules](ref:get-v1-companies-company_id-pay_schedules).

'
      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_pilot:
          type: boolean
          description: 'With automatic payroll enabled, payroll runs automatically one day before payroll deadlines. When false, payroll does not run automatically.

'
          readOnly: true
        active:
          "$ref": "#/components/schemas/Pay-Schedule-Active"
        workweek_start_day:
          "$ref": "#/components/schemas/Pay-Schedule-Workweek-Start-Day"
      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_pilot: false
          custom_name: A new monthly pay schedule
          active: true
          workweek_start_day: Monday
        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:
          custom_name: every 1st and 15th of the month
          auto_pilot: true
          active: true
          workweek_start_day: Monday
    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).

'
      items:
        "$ref": "#/components/schemas/Pay-Schedule-List-Item"
      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:
            name:
            custom_name: every 11th of the month
            auto_pilot: true
            active: true
            workweek_start_day: Monday
    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.
        Returned for API version 2025-11-15 and later; for earlier versions the response uses auto_pilot instead.
    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:
            name:
            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.

        - **pay_periods**: One entry per pay period in the range; each includes check_date, start_date, end_date, and run_payroll_by.
        - **holidays**: Observed bank holidays (ISO date strings) that may affect payroll timing.
      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.

        - **anchor_pay_date**: The first date that employees on this pay schedule will be paid (first company payday).
        - **anchor_end_of_pay_period**: The last date of the first pay period; can be the same as anchor_pay_date.
      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
        workweek_start_day: Monday
      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.

            On create: required for Twice per month and Monthly; omit or null for Every week and Every other week.
        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.

            On create: only for Twice per month; omit or null for other frequencies.
        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.

            When 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.
        workweek_start_day:
          allOf:
            - "$ref": "#/components/schemas/Pay-Schedule-Workweek-Start-Day-Create-Update"
          example: Monday
      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
        workweek_start_day: Monday
      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.
            For API versions before 2025-11-15 the request field is auto_pilot.
        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.

'
        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.

'
        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.
        workweek_start_day:
          allOf:
            - "$ref": "#/components/schemas/Pay-Schedule-Workweek-Start-Day-Create-Update"
          example: Monday
      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_pilot: 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_pilot:
          type: boolean
          description: |
            With automatic payroll enabled, payroll runs automatically one day before payroll deadlines. When false, payroll does not run automatically.
            For API version 2025-11-15 and later the response uses auto_payroll (Autopayroll) instead.
          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.

        READ-ONLY in responses. Possible values:

        - `Every week`: Employees are paid weekly.
        - `Every other week`: Employees are paid bi-weekly (every two weeks).
        - `Twice per month`: Employees are paid on two fixed days each month (e.g. 1st and 15th); use day_1 and day_2.
        - `Monthly`: Employees are paid once per month; use day_1 for the pay day.
        - `Quarterly`: Employees are paid every three months.
        - `Annually`: Employees are paid once per year.
      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.

        - `Every week`: Weekly pay.
        - `Every other week`: Biweekly pay.
        - `Twice per month`: Two pay dates per month; require day_1 and day_2 (use 31 for last day of month).
        - `Monthly`: One pay date per month; require day_1 (1-31).
      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.

'
      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.

'
      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.

        When 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.
      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
    Pay-Schedule-Workweek-Start-Day:
      description: 'The day of the week that this pay schedule''s workweeks start on, used for regular rate of pay overtime calculations. Null when no workweek start day has been configured (e.g. legacy pay schedules).

'
      anyOf:
        - type: string
          enum:
            - Sunday
            - Monday
            - Tuesday
            - Wednesday
            - Thursday
            - Friday
            - Saturday
        - type: 'null'
      readOnly: true
    Pay-Schedule-Workweek-Start-Day-Create-Update:
      type: string
      description: 'The day of the week that this pay schedule''s workweeks start on, used for regular rate of pay overtime calculations.

'
      enum:
        - Sunday
        - Monday
        - Tuesday
        - Wednesday
        - Thursday
        - Friday
        - Saturday
    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.
            - `gep_notice`: A tax notice attachment
            - `compliance`: A compliance attachment
            - `other`: Any other attachment type
          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.
            - `gep_notice`: A tax notice attachment
            - `compliance`: A compliance attachment
          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.

            'awaiting_deposits' means the bank account is just created and money is being transferred.
            'ready_for_verification' means the micro-deposits are completed and the verification process can begin by using the verify endpoint.
            'verified' means the bank account is verified.
        verification_type:
          type: string
          enum:
            - bank_deposits
            - plaid
            - plaid_external
          description: |-
            The verification type of the bank account.

            'bank_deposits' means the bank account is connected by entering routing and accounting numbers and verifying through micro-deposits.
            'plaid' means the bank account is connected through Plaid.
        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
            funding. The same value is returned on every bank-account row in this
            response.
      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:
            choices:
          contribution:
            required: true
            editable: true
            default_value:
            choices:
              - amount
          deduct_as_percentage:
            required: false
            editable: false
            default_value:
            choices:
          catch_up:
            required: false
            editable: false
            default_value:
            choices:
          limit_option:
            required: false
            editable: false
            default_value:
            choices:
          company_contribution_annual_maximum:
            required: false
            editable: false
            default_value:
            choices:
          coverage_salary_multiplier:
            required: false
            editable: false
            default_value:
            choices:
          coverage_amount:
            required: false
            editable: false
            default_value:
            choices:
    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.

                      "amount": The company contributes a fixed amount per payroll. If elective is true, the contribution is matching, dollar-for-dollar.

                      "percentage": The company contributes a percentage of the payroll amount per payroll period. If elective is true, the contribution is matching, dollar-for-dollar.

                      "tiered": The company contribution varies according to the size of the employee deduction.
                  value:
                    description: |-
                      For the `amount` and `percentage` contribution types, the value of the corresponding amount or percentage.

                      For the `tiered` contribution type, an array of tiers.
                    oneOf:
                      - type: string
                      - type: object
                        properties:
                          tiers:
                            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.

                                    Use threshold to define each tier's end point, with tiers applied cumulatively from 0% upwards.

                                    For example:

                                    If 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.

                                    If 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
        custom_bonus_category:
          name: Gym Membership Stipend
          uuid: 6b4a8efb-db90-4c13-a75f-aae11b3f4ff9
          active: true
          category: Other
          included_in_overtime_pay: 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.
        category:
          type: string
          description: |
            The earning type category. Only present when the company has access to
            categorized custom bonus earning types.
          enum:
            - CashTips
            - Commission
            - DiscretionaryBonus
            - BenefitContributions
            - MinimumWageAdjustment
            - MinisterHousing
            - NonDiscretionaryBonus
            - OnCallPay
            - OwnersDraw
            - PaycheckTips
            - CorrectionPayment
            - ServiceCharges
            - SeverancePay
            - Other
            - NonTaxableDisability
            - OtherRegularIncome
            - OtherNonTaxable
        included_in_overtime_pay:
          type: boolean
          description: |
            Whether earnings of this type are included when calculating an employee's
            regular rate of pay for overtime purposes. Only settable when `category` is `Other`.
      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.

                "amount": The company contributes a fixed amount per payroll. If elective is true, the contribution is matching, dollar-for-dollar.

                "percentage": The company contributes a percentage of the payroll amount per payroll period. If elective is true, the contribution is matching, dollar-for-dollar.

                "tiered": The company contribution varies according to the size of the employee deduction.
            value:
              description: |-
                For the `amount` and `percentage` contribution types, the value of the corresponding amount or percentage.

                For the `tiered` contribution type, an array of tiers.
              oneOf:
                - type: string
                - type: object
                  properties:
                    tiers:
                      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.

                              Use threshold to define each tier's end point, with tiers applied cumulatively from 0% upwards.

                              For example:

                              If 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.

                              If 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.

            `Family` and `Individual` are applicable to HSA benefit.

            `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.

                `amount`: The company contributes a fixed amount per payroll. If elective is true, the contribution is matching, dollar-for-dollar.

                `percentage`: The company contributes a percentage of the payroll amount per payroll period. If elective is true, the contribution is matching, dollar-for-dollar.

                `tiered`: The size of the company contribution corresponds to the size of the employee deduction relative to a tiered matching scheme.
            value:
              description: |-
                For the `amount` and `percentage` contribution types, the value of the corresponding amount or percentage.

                For the `tiered` contribution type, an array of tiers.
              oneOf:
                - type: string
                  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.

                          Use threshold to define each tier's end point, with tiers applied cumulatively from 0% upwards.

                          For example:

                          If 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.

                          If 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
            their limit.

            `Family` or `Individual`: Applicable to HSA benefit.

            `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:
          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.

                `amount`: The company contributes a fixed amount per payroll. If elective is true, the contribution is matching, dollar-for-dollar.

                `percentage`: The company contributes a percentage of the payroll amount per payroll period. If elective is true, the contribution is matching, dollar-for-dollar.

                `tiered`: The size of the company contribution corresponds to the size of the employee deduction relative to a tiered matching scheme.
            value:
              description: |-
                For the `amount` and `percentage` contribution types, the value of the corresponding amount or percentage.

                For the `tiered` contribution type, an array of tiers.
              oneOf:
                - type: string
                  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.

                          Use threshold to define each tier's end point, with tiers applied cumulatively from 0% upwards.

                          For example:

                          If 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.

                          If 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
            their limit.

            `Family` or `Individual`: Applicable to HSA benefit.

            `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:
          retirement_loan_identifier:
          deduct_as_percentage: false
          contribute_as_percentage: false
          catch_up: false
          coverage_amount:
          deduction_reduces_taxable_income:
          coverage_salary_multiplier: '0.00'
          contribution:
            type: amount
            value: '100.00'
          elective: false
          effective_date: '2025-01-01'
          expiration_date:
        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:
          deduct_as_percentage: false
          catch_up: false
          coverage_amount:
          deduction_reduces_taxable_income:
          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:
      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:
          submitted_items:
          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`.
                  - `success`: the payroll was cancelled, or required no action (already cancelled / never run)
                  - `failed`: the payroll could not be cancelled; see `errors`
              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.
                        - `not_cancellable`: the payroll is past the point where it can be cancelled
                        - `internal_error`: an unexpected error occurred; the request can be retried
                    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.
                  - `not_found`: the payroll does not exist, or is not associated with a company the partner is mapped to
                  - `duplicate_operation`: the same payroll UUID appeared more than once in the request; only the first occurrence is processed
              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:
                  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:
                - 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_pilot:
          "$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:
          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:
            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.

                  `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:
            - 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:
          annual_net_revenue: '500000'
          zip_code: '94107'
          result: 12000000
          accepted_at:
          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: |-
            |   |   |
            |---|---|
            |__Status__| __Description__ |
            | Pass | Signatory can sign all forms |
            | Fail | Signatory cannot sign forms |
            | Skipped | Signatory cannot sign Form 8655 until the form is manually uploaded as wet-signed |
            | null | Identity verification process has not been completed |
        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:
        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:
          is_admin: false
          has_ssn: false
          version: def456
          identity_verification_status:
          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:
            - Single
            - Married
            - Head of Household
            - Exempt from withholding
            - 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:
            - Single
            - Married
            - Head of Household
            - 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>.

'
              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:
            - 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.

'
              key: withholding_allowance
              input_question_format:
                type: Number
              answers:
                - value: 1
                  valid_from: '2010-01-01'
                  valid_up_to:
            - 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:
            - 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:
      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:
            - C-Corporation
            - S-Corporation
            - Sole proprietor
            - LLC
            - LLP
            - Limited partnership
            - Co-ownership
            - Association
            - Trusteeship
            - General partnership
            - Joint venture
            - 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:
            - S-Corporation
            - C-Corporation
            - LLC
        filing_form:
          type: string
          enum:
            - '941'
            - '944'
          description: |-
            The form used by the company for federal tax filing. One of:
            - 941 (Quarterly federal tax return form)
            - 944 (Annual federal tax return form)
        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:
                - `pending`: The EIN verification process has not completed (or the company does not yet have an EIN).
                - `verified`: The EIN has been successfully verified as a valid EIN with the IRS.
                - `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:
              - Semiweekly
              - 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:
            - C-Corporation
            - S-Corporation
            - Sole proprietor
            - LLC
            - LLP
            - Limited partnership
            - Co-ownership
            - Association
            - Trusteeship
            - General partnership
            - Joint venture
            - Non-Profit
        filing_form:
          type: string
          example: '944'
          enum:
            - '941'
            - '944'
          description: |-
            The form used by the company for federal tax filing. One of:
            - 941 (Quarterly federal tax return form)
            - 944 (Annual federal tax return form)
        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:
        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:
      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.
            Stable across changes to the field's value: a `payroll_blocking: true` field reports `true` whether
            currently empty or populated.
        default_value_applied:
          type: boolean
          description: 'Whether the current `value` is a default rather than an explicitly set one.

'
    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:
      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.

            - `text`: free-text input, no additional requirements
            - `currency`: a value representing a dollar amount, e.g. `374.55` representing `$374.55`
            - `radio`: choose one of options provided, see `options`
            - `select`: choose one of options provided, see `options`
            - `percent`: A decimal value representing a percentage, e.g. `0.034` representing `3.4%`
            - `account_number`: An account number for a tax agency, more information provided by `mask` and `prefix`
            - `tax_rate`: A decimal value representing a tax rate, e.g. `0.034` representing a tax rate of `3.4%`, see `validation` for additional validation guidance
            - `workers_compensation_rate`: A decimal value representing a percentage, see `risk_class_code`, `risk_class_description`, and `rate_type`
          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:
              - `percent`: A percentage formatted as a decimal, e.g. `0.01` for 1%
              - `currency_per_hour`: A dollar amount per hour, e.g. `3.24` for $3.24/hr
          enum:
            - percent
            - currency_per_hour
        mask:
          type:
            - string
            - 'null'
          description: |
            [for `account_number`] A pattern describing the format of the account number

            The mask is a sequence of characters representing the requirements of the actual account number. Each character in the mask represents a single character in the account number as follows:
            - `#`: a digit (`\d`)
            - `@`: a upper or lower case letter (`[a-zA-Z]`)
            - `^`: an uppercase letter (`[A-Z]`)
            - `%`: a digit or uppercase letter (`[0-9A-Z]`)
            - any other character represents the literal character

            Examples:
            - mask: `WHT-######` represents `WHT-` followed by 5 digits, e.g. `WHT-33421`
            - mask: `%####-^^` supports values of `75544-AB` and `Z7654-HK`
        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.
                - e.g. ["0.0", "0.001"] representing 0% and 0.1%
              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:
          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:
            - 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:
      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:
              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:
                - 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:
            - 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:
              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:
        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_complete: false
            setup_status: not_started
            default_rates_applied: false
            ready_to_run_payroll: false
          - state: CA
            setup_complete: true
            setup_status: complete
            default_rates_applied: false
            ready_to_run_payroll: true
      items:
        type: object
        properties:
          state:
            "$ref": "#/components/schemas/State"
          setup_complete:
            type: boolean
            description: Whether all requirements for the state have been satisfied such that the company can complete onboarding. A company must be `setup_complete` in all relevant states to complete the `state_setup` company onboarding step.
          setup_status:
            type: string
            enum:
              - not_started
              - in_progress
              - complete
            description: |
              The current status of the state tax setup.
              - `not_started`: No requirements have been filled
              - `in_progress`: Some requirements have been filled, or default rates are applied
              - `complete`: All requirements have been filled without default rates
          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. This will be `true` when `setup_complete` is `true`.
    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:
          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: The list of required questions for the information request
          items:
            type: object
            properties:
              question_uuid:
                type: string
                description: The UUID of the question
              question_text:
                type: string
                description: The text of the question
              response_type:
                type: string
                description: The type of response to the question
                enum:
                  - text
                  - document
                  - persona
                  - radio_button
            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:
          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:
          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:
          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:
            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:
            bank_name:
            date_sent:
            unique_tracking_code: 1trvxwxp57zf
            payment_type: Payroll
            payment_uuid: 5faae454-e629-490b-a72a-c022c2c9e6bc
            amount_sent:
            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:
            bank_name:
            date_sent:
            unique_tracking_code: 6kfhwxq2crsm
            payment_type: ContractorPaymentGroup
            payment_uuid: 8b6c3d70-9b8e-4d4d-b6a1-a1f3a6d9b2c4
            amount_sent:
            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.

            ## State Transitions
            ```
            pending ──────► in_progress ──────► success
                                        ├─────► failure
                                        └─────► partial_success
            ```

            ### Valid Transitions
            - `pending` → `in_progress`: Automatic when processing begins
            - `in_progress` → `success`: All time sheet data synced successfully
            - `in_progress` → `failure`: Sync failed entirely
            - `in_progress` → `partial_success`: Some members failed to sync
          example: pending
        kind:
          type: string
          enum:
            - regular
          description: |
            The kind of payroll sync.
            - `regular`: A regular payroll sync
          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:
        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.
            - `regular`: A regular payroll sync
          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:
          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:
          reconcile_tax_method: pay_taxes
          file_yearly_forms: true
          file_quarterly_forms: true
          comments:
          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.

'
        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.

'
        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`.

'
          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:
            reconcile_tax_method: refund_taxes
            file_yearly_forms: false
            file_quarterly_forms: false
            comments:
            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:
            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:
          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:
          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:
          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:
          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:
          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:
            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:
            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:
          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:
          submission_blockers: []
          credit_blockers: []
          contractor_payments:
            - uuid:
              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:
          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:
          submission_blockers:
            - blocker_type: fast_ach_threshold_exceeded
              blocker_name: Fast ACH Threshold Exceeded
              selected_option:
              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:
              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-Show"
          - type: object
            additionalProperties: true
            properties:
              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:
            last_name: Koss
            email: keena.feest@kiehn.co.uk
            company_uuid: e904cc79-818a-4da8-9d37-0be0a86fdda8
            manager_uuid:
            version: a5cec1f1c0135feb3e76ca6ea3c46176
            current_employment_status: full_time
            onboarding_status: onboarding_completed
            preferred_first_name:
            department_uuid:
            employee_code: 46f036
            payment_method: Direct Deposit
            department:
            terminated: false
            two_percent_shareholder: false
            onboarded: true
            historical: false
            has_ssn: true
            onboarding_documents_config:
              uuid:
              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:
                state_wc_class_code:
                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:
            work_email:
            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:
                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:
            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.
        id:
          type: integer
          description: The internal ID of the address.
          readOnly: true
        effective_from:
          type: string
          format: date
          description: The date the address became effective.
        effective_to:
          type: string
          format: date
          description: The date the address became inactive.
        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
        id: 3
        effective_from: '2024-01-01'
        effective_to: '2025-01-01'
        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
      required:
        - email
      properties:
        email:
          type: string
          description: Email of the company signatory who is authorized to accept our [Terms of Service](https://flows.gusto.com/terms) and migration decision. You can retrieve the signatory email from the `GET /v/1/companies/{company_id}/signatories` endpoint.
        ip_address:
          type: string
          description: The IP address of the signatory who viewed and accepted the Terms of Service.
        external_user_id:
          type: string
          description: The signatory's user ID on your platform.
      x-examples:
        typical:
          email: payroll.admin@example.com
          ip_address: 203.0.113.42
          external_user_id: 9f8e7d6c-5b4a-3210-fedc-ba9876543210
    Partner-Managed-Company-Migrate-Response:
      type: object
      properties:
        company_uuid:
          type: string
          description: The company UUID
        migration_status:
          type: string
          description: The migration status. Always returns `success` for a successful migration.
          enum:
            - success
      x-examples:
        Example:
          company_uuid: 39abf9b9-650b-4e67-89a0-389dc6ee8a71
          migration_status: success
    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.
            - `pending`: accepted, not yet started
            - `processing`: reports are being generated
            - `completed`: all reports finished
            - `failed`: the batch failed before completing
      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:
          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:
                - report_type: general_ledger
                  file_type: json
                  status: success
                  error:
      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`:
            - `success`: every report succeeded
            - `partial_success`: some succeeded, some failed
            - `failed`: every report failed
            - `pending`: at least one report is still being generated
        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`.

'
      required:
        - status
        - expired
      properties:
        status:
          type: string
          enum:
            - pending
            - sent
            - verified
            - complete
            - cancelled
          description: |
            Current status of the member portal invitation.
            - `pending`: The invitation record has been created but the invitation email has not yet been delivered.
            - `sent`: The invitation email has been delivered to the member.
            - `verified`: The member has been verified by the member portal partner.
            - `complete`: The member has fully completed their member portal registration.
            - `cancelled`: The invitation has been cancelled, either via `DELETE` on this endpoint or because it was superseded.
          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.

'
          example: false
      x-examples:
        sent_invitation:
          status: sent
          expired: false
        complete_invitation:
          status: complete
          expired: false
        cancelled_invitation:
          status: cancelled
          expired: true
    Reverse-Wire-Transaction:
      type: object
      description: Representation of a reverse wire (drawdown) transaction. Reverse wires are debit transactions initiated by Gusto to pull funds from a partner's bank account to cover payroll or contractor payment obligations.
      x-examples:
        example:
          company_uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          amount: '107250.85'
          status: processed
          payment_direction: debit
          bank_name: Chase Payroll Incoming Wires
          payment_event_type: Payroll
          payment_event_uuid: f9e8d7c6-b5a4-3210-fedc-ba9876543210
          payment_event_check_date: '2024-01-15'
          created_at: '2024-01-12'
      properties:
        company_uuid:
          type: string
          description: Unique identifier of the company the reverse wire transaction belongs to
        amount:
          type: string
          format: float
          description: The amount of money moved by the reverse wire, as a decimal string. Always non-negative.
        status:
          type: string
          description: |
            Current status of the reverse wire transaction.
            - `pending_processing`: The reverse wire has been initiated and is awaiting processing by the banking network.
            - `processed`: The reverse wire was successfully settled and funds have been received.
            - `rejected`: The reverse wire was rejected by the receiving bank (e.g. invalid account, insufficient funds).
            - `failed`: The reverse wire failed during processing due to a system or network error.
          enum:
            - pending_processing
            - processed
            - rejected
            - failed
        payment_direction:
          type: string
          description: The direction of the payment. Reverse wires are always debits from the company's account.
          enum:
            - debit
        bank_name:
          type:
            - string
            - 'null'
          description: Name of the receiving bank. Null when the bank is not known.
        payment_event_type:
          description: The type of payment event this reverse wire is associated with. Null when the wire is not linked to a payroll or contractor payment.
          anyOf:
            - type: string
              enum:
                - Payroll
                - ContractorPayment
            - type: 'null'
        payment_event_uuid:
          type:
            - string
            - 'null'
          description: Unique identifier of the associated payroll or contractor payment. Null when the wire is not linked to a payment event.
        payment_event_check_date:
          type:
            - string
            - 'null'
          description: The check date of the associated payment event. Null when the wire is not linked to a payment event.
        created_at:
          type: string
          description: The date the reverse wire record was created.
      required:
        - company_uuid
        - amount
        - status
        - payment_direction
        - created_at
    Reverse-Wire-Transaction-List:
      type: array
      items:
        "$ref": "#/components/schemas/Reverse-Wire-Transaction"
      x-examples:
        example:
          - company_uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
            amount: '107250.85'
            status: processed
            payment_direction: debit
            bank_name: Chase Payroll Incoming Wires
            payment_event_type: Payroll
            payment_event_uuid: f9e8d7c6-b5a4-3210-fedc-ba9876543210
            payment_event_check_date: '2024-01-15'
            created_at: '2024-01-12'
    Tax-Filing:
      type: object
      description: Representation of a tax filing obligation
      x-examples:
        example:
          uuid: 11111111-1111-1111-1111-111111111111
          company_uuid: f0e1d2c3-b4a5-6789-0fed-cba987654321
          form_title: Quarterly Contribution Return and Report of Wages
          jurisdiction: CA
          agency_name: California Employment Development Department (EDD)
          period: Q1 2026
          period_start: '2026-01-01'
          period_end: '2026-03-31'
          due_date: '2026-04-30'
          filed_at:
          is_amendment: false
          amends_filing_uuid:
          status: failed
          status_updated_at: '2026-04-20T14:12:33.000Z'
          form_uuid:
      properties:
        uuid:
          type: string
          description: Unique identifier of the tax filing
        company_uuid:
          type: string
          description: Unique identifier of the company to which the tax filing belongs
        form_title:
          type: string
          description: The human-readable title of the tax form associated with this filing
        jurisdiction:
          type:
            - string
            - 'null'
          description: The tax jurisdiction this filing is for. A two-letter state code, or US for federal.
        agency_name:
          type:
            - string
            - 'null'
          description: The name of the tax agency this filing is submitted to
        period:
          type:
            - string
            - 'null'
          description: Humanized representation of the filing period (e.g. "Q1 2026", "2026", "December 2026")
        period_start:
          type:
            - string
            - 'null'
          description: The start date of the period this filing covers
        period_end:
          type:
            - string
            - 'null'
          description: The end date of the period this filing covers
        due_date:
          type:
            - string
            - 'null'
          description: The date this filing is due
        filed_at:
          type:
            - string
            - 'null'
          description: The timestamp this filing was filed, if it has been filed
        is_amendment:
          type: boolean
          description: Whether this filing is an amendment to a previously filed filing
        amends_filing_uuid:
          type:
            - string
            - 'null'
          description: The unique identifier of the filing this filing amends, if is_amendment is true
        status:
          type: string
          description: The current status of the tax filing
          enum:
            - not_started
            - in_progress
            - blocked
            - accepted
            - not_required
            - failed
        status_updated_at:
          type:
            - string
            - 'null'
          description: The timestamp the status was last updated, if known
        form_uuid:
          type:
            - string
            - 'null'
          description: Unique identifier of the rendered PDF form for this filing, if one has been generated. Fetch the PDF via GET /v1/forms/{form_uuid}/pdf
      required:
        - uuid
        - company_uuid
        - form_title
        - is_amendment
        - status
    Tax-Filing-List:
      type: array
      items:
        "$ref": "#/components/schemas/Tax-Filing"
      x-examples:
        example:
          - uuid: 11111111-1111-1111-1111-111111111111
            company_uuid: f0e1d2c3-b4a5-6789-0fed-cba987654321
            form_title: Quarterly Contribution Return and Report of Wages
            jurisdiction: CA
            agency_name: California Employment Development Department (EDD)
            period: Q1 2026
            period_start: '2026-01-01'
            period_end: '2026-03-31'
            due_date: '2026-04-30'
            filed_at:
            is_amendment: false
            amends_filing_uuid:
            status: failed
            status_updated_at: '2026-04-20T14:12:33.000Z'
            form_uuid:
          - uuid: 33333333-3333-3333-3333-333333333333
            company_uuid: f0e1d2c3-b4a5-6789-0fed-cba987654321
            form_title: Employer's Quarterly Federal Tax Return
            jurisdiction: US
            agency_name: Internal Revenue Service
            period: Q1 2026
            period_start: '2026-01-01'
            period_end: '2026-03-31'
            due_date: '2026-04-30'
            filed_at: '2026-04-12T16:30:25.000Z'
            is_amendment: false
            amends_filing_uuid:
            status: accepted
            status_updated_at: '2026-04-12T16:30:25.000Z'
            form_uuid: 22222222-2222-2222-2222-222222222222
    Tax-Payment:
      type: object
      description: Representation of a tax payment made by Gusto to a tax agency on behalf of a company
      x-examples:
        example:
          uuid: 44444444-4444-4444-4444-444444444444
          company_uuid: f0e1d2c3-b4a5-6789-0fed-cba987654321
          agency_name: Internal Revenue Service
          jurisdiction: US
          period_start: '2026-01-01'
          period_end: '2026-03-31'
          due_date: '2026-04-30'
          payment_sent_on: '2026-04-12'
          amount: '1325.00'
          amount_paid: '1325.00'
          line_items:
            - payroll_uuid: 55555555-5555-5555-5555-555555555555
              unique_tax_id: 00-000-0000-FIT-000
              amount: '1325.00'
      properties:
        uuid:
          type: string
          description: Unique identifier of the tax payment
        company_uuid:
          type: string
          description: Unique identifier of the company to which the tax payment belongs
        agency_name:
          type:
            - string
            - 'null'
          description: The name of the tax agency this payment is submitted to. Null for legacy tax payments whose agent has no reference-data agency.
        jurisdiction:
          type:
            - string
            - 'null'
          description: The tax jurisdiction this payment is for. A two-letter state code, or US for federal. Null for legacy tax payments whose agent has no reference-data agency.
        period_start:
          type:
            - string
            - 'null'
          format: date
          description: The start date of the period this payment covers. Null for legacy tax payments where the period start was never recorded.
        period_end:
          type: string
          format: date
          description: The end date of the period this payment covers
        due_date:
          type:
            - string
            - 'null'
          format: date
          description: The date this payment is due. Null for legacy tax payments where the due date was never recorded.
        payment_sent_on:
          type:
            - string
            - 'null'
          format: date
          description: The date Gusto submitted this payment to the tax agency. It is null until submitted, and also if the payment is returned or cancelled after being sent. It is not guaranteed to stay set once populated.
        amount:
          type: string
          format: float
          description: Total amount owed for this tax payment. Can be negative for corrections, refunds, or credits.
        amount_paid:
          type: string
          format: float
          description: Amount paid toward this tax payment so far, sourced from the payment's running balance. "0.00" until paid; equal to `amount` once fully paid.
        line_items:
          type: array
          description: The payroll tax liabilities that make up this payment. Empty array when the payment has no associated payroll taxes. Only included in the response of GET /v1/companies/{company_uuid}/tax_payments/{uuid}. It is omitted from the list endpoint response.
          items:
            "$ref": "#/components/schemas/Tax-Payment-Line-Item"
      required:
        - uuid
        - company_uuid
        - agency_name
        - jurisdiction
        - period_start
        - period_end
        - due_date
        - amount
        - amount_paid
    Tax-Payment-Line-Item:
      type: object
      description: A single payroll tax liability rolled up into a tax payment
      properties:
        payroll_uuid:
          type: string
          description: Unique identifier of the payroll this liability came from
        unique_tax_id:
          type: string
          description: Unique identifier of the tax type this liability is for
        amount:
          type: string
          format: float
          description: The amount of this liability included in the tax payment
      required:
        - payroll_uuid
        - unique_tax_id
        - amount
    Tax-Payment-List:
      type: array
      items:
        "$ref": "#/components/schemas/Tax-Payment"
      x-examples:
        example:
          - uuid: 44444444-4444-4444-4444-444444444444
            company_uuid: f0e1d2c3-b4a5-6789-0fed-cba987654321
            agency_name: Internal Revenue Service
            jurisdiction: US
            period_start: '2026-01-01'
            period_end: '2026-03-31'
            due_date: '2026-04-30'
            payment_sent_on: '2026-04-12'
            amount: '1325.00'
            amount_paid: '1325.00'
          - uuid: 66666666-6666-6666-6666-666666666666
            company_uuid: f0e1d2c3-b4a5-6789-0fed-cba987654321
            agency_name: Illinois Department of Revenue
            jurisdiction: IL
            period_start: '2026-01-01'
            period_end: '2026-03-31'
            due_date: '2026-04-30'
            payment_sent_on:
            amount: '200.00'
            amount_paid: '0.00'
  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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `ach_transactions:read`
      tags:
        - ACH Transactions
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Ach-Transaction-List"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: achTransactions
      x-speakeasy-name-override: getAll
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `company_admin:read`
      tags:
        - Companies
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Admin"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: listAdmins
    post:
      summary: Create an admin for the company
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.
        If the email matches an existing user, this will create an admin account for the current user. Otherwise, this will create a new user.

        scope: `company_admin:write`
      tags:
        - Companies
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Admin"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Admin-Create-Request"
        required: true
      x-speakeasy-name-override: createAdmin
  "/v1/benefits":
    get:
      summary: Get all supported benefits
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. 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.

        scope: `benefits:read`
      tags:
        - Company Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Supported-Benefit-List"
      x-speakeasy-group: companyBenefits
      x-speakeasy-name-override: getAll
  "/v1/benefits/{benefit_id}":
    get:
      summary: Get a supported benefit
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `benefits:read`
      tags:
        - Company Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Supported-Benefit"
      x-speakeasy-group: companyBenefits
      x-speakeasy-name-override: getSupported
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `benefits:read`
      tags:
        - Company Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Benefit-Type-Requirements"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: companyBenefits
      x-speakeasy-name-override: getRequirements
  "/v1/bulk_reports":
    post:
      summary: Create a bulk report batch
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. 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\U0001F4D8 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:
              schema:
                "$ref": "#/components/schemas/Create-Bulk-Report"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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\U0001F4D8 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:
              schema:
                "$ref": "#/components/schemas/Bulk-Report"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        The employees:read scope is required to return home_address and non-work locations.
        The company_admin:read scope is required to return primary_payroll_admin.
        The signatories:read scope is required to return primary_signatory.

        scope: `companies:read`
      tags:
        - Companies
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Company"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: get
    put:
      summary: Update a company
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `companies:write`
      tags:
        - Companies
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Company"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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
      x-speakeasy-name-override: update
  "/v1/companies/{company_id}/attachments":
    get:
      summary: Get List of Company Attachments
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ### Related guides
        - [Manage company attachments](doc:manage-company-attachments)

        scope: `company_attachments:read`
      tags:
        - Company Attachment
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Company-Attachment"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: companyAttachments
      x-speakeasy-name-override: getList
    post:
      summary: Create Company Attachment and Upload File
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ### Related guides
        - [Manage company attachments](doc:manage-company-attachments)

        scope: `company_attachments:write`
      tags:
        - Company Attachment
      x-gusto-integration-type:
        - embedded
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Company-Attachment"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          multipart/form-data:
            schema:
              "$ref": "#/components/schemas/Company-Attachment-Create-Request-Body"
        required: true
      x-speakeasy-group: companyAttachments
      x-speakeasy-name-override: create
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ### Related guides
        - [Manage company attachments](doc:manage-company-attachments)

        scope: `company_attachments:read`
      tags:
        - Company Attachment
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Company-Attachment"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: companyAttachments
      x-speakeasy-name-override: getDetails
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ### Related guides
        - [Manage company attachments](doc:manage-company-attachments)

        scope: `company_attachments:read`
      tags:
        - Company Attachment
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Company-Attachment-Download-Url"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: companyAttachment
      x-speakeasy-name-override: getDownloadUrl
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `company_bank_accounts:read`
      tags:
        - Bank Accounts
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Company-Bank-Account"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: bankAccounts
      x-speakeasy-name-override: get
    post:
      summary: Create a company bank account
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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>\U0001F6A7 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>\n> A new bank account cannot replace the default if the current default has unprocessed payments. In that case, a 422 `invalid_operation` error is returned. To resolve, fund or cancel the pending payments first.\n\nscope: `company_bank_accounts:write`"
      tags:
        - Bank Accounts
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Bank account unchanged
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Company-Bank-Account"
        '201':
          description: created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Company-Bank-Account"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: Cannot replace default bank account with unfunded payments
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Company-Bank-Account-Request"
        required: true
      x-speakeasy-group: bankAccounts
      x-speakeasy-name-override: create
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        A bank account cannot be disabled if it is used for any unprocessed payments.

        scope: `company_bank_accounts:write`
      tags:
        - Bank Accounts
      x-gusto-integration-type:
        - embedded
      responses:
        '204':
          description: successful
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: Cannot delete bank account with unfunded payments
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Note that the order of the two deposits specified in request parameters does not matter.
        There's a maximum of 5 verification attempts, after which we will automatically initiate a new set of micro-deposits and require the bank account to be verified with the new micro-deposits.

        ### Bank account verification in demo
        In 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.

        ### Webhooks
        - `company.bank_account.verified`: Fires when the company bank account is successfully verified.

        ### Related guides
        - [Manage company bank accounts](doc:manage-company-bank-accounts)
        - [Bank Account Events](doc:bank-account-events)

        scope: `company_bank_accounts:write`
      tags:
        - Bank Accounts
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Company-Bank-Account"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Company-Bank-Account-Verify-Request"
        required: true
      x-speakeasy-group: bankAccounts
      x-speakeasy-name-override: verify
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Note that company benefits can be deactivated only when no employees are enrolled.

        Benefits containing PHI are only visible to applications with the `company_benefits:read:phi` scope.

        scope: `company_benefits:read`
      tags:
        - Company Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Company-Benefit"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: companyBenefits
      x-speakeasy-name-override: list
    post:
      summary: Create a company benefit
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Note that company benefits can be deactivated only when no employees are enrolled.

        When 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.

        scope: `company_benefits:write`
      tags:
        - Company Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Company-Benefit"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Company-Benefit-Create-Request"
        required: true
      x-speakeasy-group: companyBenefits
      x-speakeasy-name-override: create
  "/v1/company_benefits/{company_benefit_id}":
    get:
      summary: Get a company benefit
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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:
            - 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.

        Note that company benefits can be deactivated only when no employees are enrolled.

        When with_employee_benefits parameter with true value is passed, employee_benefits:read scope is required to return employee_benefits.

        scope: `company_benefits:read`
      tags:
        - Company Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Company-Benefit-With-Employee-Benefits"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: companyBenefits
      x-speakeasy-name-override: get
    put:
      summary: Update a company benefit
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Note that company benefits can be deactivated only when no employees are enrolled.

        When 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.

        scope: `company_benefits:write`
      tags:
        - Company Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Company-Benefit"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Company-Benefit-Update-Request"
        required: true
      x-speakeasy-group: companyBenefits
      x-speakeasy-name-override: update
    delete:
      summary: Delete a company benefit
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

          - There are no employee benefits associated with the company benefit
          - There are no payroll items associated with the company benefit
          - The benefit is not managed by a Partner or by Gusto (type must be 'External')

        When 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.

        scope: `company_benefits:write`
      tags:
        - Company Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '204':
          description: No Content
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-name-override: delete
      x-speakeasy-group: companyBenefits
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Currently this endpoint only works for 401-k and Roth 401-k benefit types.

        scope: `company_benefits:read`
      tags:
        - Company Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Contribution-Exclusion"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Currently this endpoint only works for 401-k and Roth 401-k benefit types.

        scope: `company_benefits:write`
      tags:
        - Company Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Contribution-Exclusion"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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:
            - 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.

        Returns an array of all employee benefits enrolled for this company benefit.

        Benefits containing PHI are only visible to applications with the `employee_benefits:read:phi` scope.

        scope: `employee_benefits:read`
      tags:
        - Company Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Employee-Benefit"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getEmployeeBenefits
      x-speakeasy-group: companyBenefits
    put:
      summary: Bulk update employee benefits for a company benefit
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Create or update(if the employee is already enrolled in the company benefit previously) an employee benefit for the company benefit.

        Benefits containing PHI are only visible to applications with the `employee_benefits:read:phi` scope.

        When 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.

        scope: `employee_benefits:write`
      tags:
        - Company Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Employee-Benefit"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Employee-Benefit-Bulk-Update-Request"
        required: true
      x-speakeasy-group: companyBenefits
      x-speakeasy-name-override: updateEmployeeBenefits
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Benefits containing PHI are only visible to applications with the `company_benefits:read:phi` scope.

        scope: `company_benefits:read`
      tags:
        - Company Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Benefit summary response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Benefit-Summary"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: companyBenefits
      x-speakeasy-name-override: getSummary
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `companies:read`
      tags:
        - Companies
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Company-Custom-Field-List"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getCustomFields
  "/v1/companies/{company_id}/forms":
    get:
      summary: Get all company forms
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        ### Related guides
        - [Company Forms](doc:company-form)

        scope: `company_forms:read`
      tags:
        - Company Forms
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Form"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getAll
      x-speakeasy-group: companyForms
  "/v1/forms/{form_id}":
    get:
      summary: Get a company form
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `company_forms:read`
      tags:
        - Company Forms
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Form"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: companyForms
      x-speakeasy-name-override: get
  "/v1/forms/{form_id}/pdf":
    get:
      summary: Get a company form pdf
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `company_forms:read`
      tags:
        - Company Forms
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Form-Pdf"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getPdf
      x-speakeasy-group: companyForms
  "/v1/forms/{form_id}/sign":
    put:
      summary: Sign a company form
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `company_forms:sign`
      tags:
        - Company Forms
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Form"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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
      x-speakeasy-group: companyForms
      x-speakeasy-name-override: sign
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `companies:read`
      tags:
        - Industry Selection
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Industry"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: industrySelection
      x-speakeasy-name-override: get
    put:
      summary: Update a company industry selection
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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).

        Optionally provide an industry title and [SIC codes](https://siccode.com/). If you do not provide SIC codes,
        we will use the NAICS code to perform an internal lookup.

        Our UI leverages [Middesk API](https://docs.middesk.com/reference/introduction) to determine industry
        classification codes.

        scope: `companies:write`
      tags:
        - Industry Selection
      x-gusto-integration-type:
        - embedded
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Industry"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Company-Industry-Selection-Required-Body"
        required: true
      x-speakeasy-group: industrySelection
      x-speakeasy-name-override: update
  "/v1/companies/{company_uuid}/notifications":
    get:
      summary: Get notifications for company
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `notifications:read`
      tags:
        - Notifications
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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
        required onboarding steps with their respective completion state.

        scope: `company_onboarding_status:read`
      tags:
        - Companies
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Company-Onboarding-Status"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getOnboardingStatus
  "/v1/companies/{company_uuid}/finish_onboarding":
    put:
      summary: Finish company onboarding
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ### Approve a company in demo

        After a company is finished onboarding, Gusto requires an additional step to review and approve that company.
        The company onboarding status is "onboarding_completed": false, until the API call is made to finish company
        onboarding. In production environments, this step is required for risk-analysis purposes.

        We provide the endpoint `PUT '/v1/companies/{company_uuid}/approve'` to facilitate company approvals in the demo environment.

        ```shell
        PUT '/v1/companies/89771af8-b964-472e-8064-554dfbcb56d9/approve'

        # Response: Company object, with company_status: 'Approved'
        ```

        scope: `companies:write`
      tags:
        - Companies
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Company-Onboarding-Status"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-name-override: finishOnboarding
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ### Related guides
        - [Payroll Processing Speeds](doc:2-day-vs-4-day)

        scope: `company_payment_configs:read`
      tags:
        - Payment Configs
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Payment-Configs"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: get
      x-speakeasy-group: paymentConfigs
    put:
      summary: Update a company's payment configs
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        At least one of `payment_speed`, `fast_payment_limit`, or `partner_owned_disbursement` is required.
        1-day payment speed is only applicable to partners that opt in. 1-day is not allowed when AutoPilot is enabled.

        ### Related guides
        - [Payroll Processing Speeds](doc:2-day-vs-4-day)

        scope: `company_payment_configs:write`
      tags:
        - Payment Configs
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Payment-Configs"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Payment-Configs-Update-Request"
        required: true
      x-speakeasy-group: paymentConfigs
      x-speakeasy-name-override: update
  "/v1/companies/{company_uuid}/suspensions":
    get:
      summary: Get suspensions for this company
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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>\U0001F4D8 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:
              schema:
                "$ref": "#/components/schemas/Company-Suspension-List"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: companies.suspensions
      x-speakeasy-name-override: get
    post:
      summary: Suspend a company's account
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `company_suspensions:write`
      tags:
        - Companies
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Company-Suspension"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/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> \U0001F6A7 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
                    - other_peo
                    - oyster
                    - patriot
                    - paychex
                    - paycom
                    - paylocity
                    - remote
                    - rippling
                    - square
                    - surepayroll
                    - toast
                    - trinet
                    - velocity_global
                    - zenefits
                  description: "The competitor the company is switching to. Required if `reason` is `'switching_provider'`.\n\n> \U0001F6A7 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
      x-speakeasy-group: companies.suspensions
      x-speakeasy-name-override: suspend
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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
        is complete for each state. Use this to determine which states still need tax setup during company onboarding.

        scope: `company_tax_requirements:read`
      tags:
        - Tax Requirements
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Tax-Requirement-States-List"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: taxRequirements
      x-speakeasy-name-override: getAll
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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
        category (e.g., registrations, tax rates, deposit schedules), each containing individual requirements with their
        current values, labels, and metadata describing the expected input format.

        Use this to build dynamic UIs for tax setup or to read the current tax configuration for a state.

        scope: `company_tax_requirements:read`
      tags:
        - Tax Requirements
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Tax-Requirements-State"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: taxRequirements
      x-speakeasy-name-override: get
    put:
      summary: Update tax requirements for a state
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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
        by [GET /v1/companies/{company_uuid}/tax_requirements/{state}](ref:get-v1-companies-company_uuid-tax_requirements-state).

        ### Prerequisites

        1. Retrieve current requirements via [GET /v1/companies/{company_uuid}/tax_requirements/{state}](ref:get-v1-companies-company_uuid-tax_requirements-state)
        2. Ensure that each requirement set that you're updating includes the correct `key`, `state`, and `effective_from` values from the GET response

        scope: `company_tax_requirements:write`
      tags:
        - Tax Requirements
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                requirement_sets:
                  "$ref": "#/components/schemas/Tax-Requirement-Set-Update"
        required: true
      x-speakeasy-group: taxRequirements
      x-speakeasy-name-override: updateState
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `company_federal_taxes:read`
      tags:
        - Federal Tax Details
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Federal-Tax-Details"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: federalTaxDetails
      x-speakeasy-name-override: get
    put:
      summary: Update a company's federal tax details
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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
        taxation status. This information is required to onboard a company for use with Gusto Embedded Payroll.

        ### Prerequisites
        Before 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)

        ### Webhooks
        - `company.updated`: Fires when federal tax details for a company are successfully updated

        **Setup:** [POST /v1/webhook_subscriptions](ref:post-v1-webhook-subscription) with `subscription_types`: `["Company"]`

        scope: `company_federal_taxes:write`
      tags:
        - Federal Tax Details
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Federal-Tax-Details"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Forbidden-Error-Object"
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Federal-Tax-Details-Update"
        required: true
      x-speakeasy-group: federalTaxDetails
      x-speakeasy-name-override: update
  "/v1/jobs/{job_id}/compensations":
    get:
      summary: Get compensations for a job
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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:
            - all_compensations: Include all effective dated compensations for each job instead of only the current compensation
      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`.

        *Note: Currently the API does not support creating multiple compensations per job - creating a compensation with the same job_uuid as another will fail with a relevant error.*

        Use `flsa_status` to determine if an employee is eligible for overtime
        By default the API returns only the current compensation - use the `include` parameter to return all compensations.

        scope: `compensations:read`
      tags:
        - Jobs and Compensations
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Compensation"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getCompensations
      x-speakeasy-group: jobsAndCompensations
    post:
      summary: Create a compensation
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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`.

        ### Prerequisites
        Before calling this endpoint:
        1. A [job](ref:post-v1-jobs-job_id) must exist for the employee

        ### Webhooks
        - `employee_job_compensation.created`: Fires when a compensation is successfully created

        scope: `compensations:write`
      tags:
        - Jobs and Compensations
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '201':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Compensation"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Compensations-Request-Body"
        required: true
      x-speakeasy-group: jobsAndCompensations
      x-speakeasy-name-override: createCompensation
  "/v1/compensations/{compensation_id}":
    get:
      summary: Get a compensation
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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`.

        scope: `compensations:read`
      tags:
        - Jobs and Compensations
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Compensation"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: jobsAndCompensations
      x-speakeasy-name-override: getCompensation
    put:
      summary: Update a compensation
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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`.

        ### Webhooks
        - `employee_job_compensation.updated`: Fires when a compensation is successfully updated

        scope: `compensations:write`
      tags:
        - Jobs and Compensations
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Compensation"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Compensations-Update-Request-Body"
        required: true
      x-speakeasy-group: jobsAndCompensations
      x-speakeasy-name-override: updateCompensation
    delete:
      summary: Delete a compensation
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ### Webhooks
        - `employee_job_compensation.destroyed`: Fires when a compensation is successfully deleted

        scope: `compensations:write`
      tags:
        - Jobs and Compensations
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '204':
          description: No Content
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-group: jobsAndCompensations
      x-speakeasy-name-override: deleteCompensation
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `contractor_payment_methods:read`
      tags:
        - Contractor Payment Method
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Contractor-Bank-Account-List"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getBankAccounts
      x-speakeasy-group: contractorPaymentMethod
    post:
      summary: Create a contractor bank account
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Note: We currently only support one bank account per contractor. Using this endpoint on a contractor who already has a bank account will just replace it.

        scope: `contractor_payment_methods:write`
      tags:
        - Contractor Payment Method
      x-gusto-integration-type:
        - embedded
      responses:
        '201':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Contractor-Bank-Account"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Contractor-Bank-Account-Create-Request-Body"
        required: true
      x-speakeasy-group: contractorPaymentMethods
      x-speakeasy-name-override: createBankAccount
  "/v1/contractors/{contractor_uuid}/forms":
    get:
      summary: Get all contractor forms
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `contractor_forms:read`
      tags:
        - Contractor Forms
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Form_1099"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: contractorForms
      x-speakeasy-name-override: list
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `contractor_forms:read`
      tags:
        - Contractor Forms
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Form_1099"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: contractorForms
      x-speakeasy-name-override: get
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `contractor_forms:read`
      tags:
        - Contractor Forms
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Form-Pdf"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: contractorForms
      x-speakeasy-name-override: getPdf
  "/v1/contractors/{contractor_uuid}/address":
    get:
      summary: Get a contractor address
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `contractors:read`
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Contractor-Address"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getAddress
    put:
      summary: Create or update a contractor's address
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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> \U0001F6A7 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:
              schema:
                "$ref": "#/components/schemas/Contractor-Address"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Contractor-Address-Update-Body"
        required: true
      x-speakeasy-name-override: updateAddress
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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
        associated with the specified company, including their payment methods and bank account details
        if they are paid via direct deposit.

        For contractors paid by direct deposit, the response includes their bank account information
        with sensitive data masked for security. The payment details also include information about
        how their payments are split if they have multiple bank accounts configured.

        For contractors paid by check, only the basic payment method information is returned.

        ### Response Details
        - For direct deposit contractors:
          - Bank account details (masked)
          - Payment splits configuration
          - Routing numbers
          - Account types
        - For check payments:
          - Basic payment method designation

        ### Common Use Cases
        - Fetching contractor payment information for payroll processing
        - Verifying contractor payment methods
        - Reviewing payment split configurations

        `encrypted_account_number` is available only with the additional scope `contractor_payment_methods:read:account_numbers`.

        scope: `contractor_payment_methods:read`
      tags:
        - Contractors
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Contractor-Payment-Details-List"
        '404':
          description: Not Found
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        The returned `creation_token` is a required parameter in order to create the contractor payment group.

        scope: `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:
              schema:
                "$ref": "#/components/schemas/Contractor-Payment-Group-Preview"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided ID/UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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
                check_date:
                  type: string
                  format: date
                  description: Date when payments should be processed
        required: true
      x-speakeasy-group: contractorPaymentGroups
      x-speakeasy-name-override: preview
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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: "> \U0001F6A7 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:
              schema:
                "$ref": "#/components/schemas/Contractor-Payment-Group"
        '404':
          description: |
            Not Found

            The requested contractor payment group does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-name-override: fund
      x-speakeasy-group: contractorPaymentGroups
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `payrolls:read`
      tags:
        - Contractor Payment Groups
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: List of Contractor Payment Groups
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Contractor-Payment-Group-With-Blockers"
        '404':
          description: |
            Not Found

            The requested company does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getList
      x-speakeasy-group: contractorPaymentGroups
    post:
      summary: Create a contractor payment group
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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)

        scope: `payrolls:run`
      tags:
        - Contractor Payment Groups
      x-gusto-integration-type:
        - embedded
      responses:
        '201':
          description: Full contractor payment group object
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Contractor-Payment-Group"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: |
            Not Found

            The requested company does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-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
        required: true
      x-speakeasy-group: contractorPaymentGroups
      x-speakeasy-name-override: create
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `payrolls:read`
      tags:
        - Contractor Payment Groups
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Contractor-Payment-Group"
        '404':
          description: |
            Not Found

            The requested contractor payment group does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: contractorPaymentGroups
      x-speakeasy-name-override: get
    delete:
      summary: Cancel a contractor payment group
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `payrolls:run`
      tags:
        - Contractor Payment Groups
      x-gusto-integration-type:
        - embedded
      responses:
        '204':
          description: Successfully cancelled
        '404':
          description: |
            Not Found

            The requested contractor payment group does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This 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.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-name-override: delete
      x-speakeasy-group: contractorPaymentGroups
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `partner_disbursements:read`
      tags:
        - Contractor Payment Groups
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Contractor-Payment-Group-Partner-Disbursements"
        '404':
          description: |
            Not Found

            The requested contractor payment group does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `partner_disbursements:write`
      tags:
        - Contractor Payment Groups
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Contractor-Payment-Group-Partner-Disbursements"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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
                          - Historical Payment
                          - Correction Payment
                        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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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
        describes how the payment should be split across the contractor's associated
        bank accounts.

        scope: `contractor_payment_methods:read`
      tags:
        - Contractor Payment Method
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Contractor-Payment-Method"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: contractorPaymentMethod
      x-speakeasy-name-override: get
    put:
      summary: Update a contractor's payment method
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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
        bank account will also update the contractor's payment method.

        scope: `contractor_payment_methods:write`
      tags:
        - Contractor Payment Method
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Contractor-Payment-Method"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Conflict-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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
      x-speakeasy-group: contractorPaymentMethod
      x-speakeasy-name-override: update
  "/v1/contractors/{contractor_uuid}/payments":
    get:
      summary: Get contractor payments
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Results are sortable by `check_date` or `created_at`. Append `:asc` or `:desc` to control direction (e.g., `check_date:desc`).

        scope: `contractor_pay_stubs:read`
      tags:
        - Contractor Payments
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: A JSON array of contractor payments
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Contractor-Payment-Listing"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Results are returned in reverse chronological order (newest first).

        scope: `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:
              schema:
                anyOf:
                  - "$ref": "#/components/schemas/Contractor-Payment-Summary"
                  - "$ref": "#/components/schemas/Contractor-Payment-Summary-By-Dates"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided ID/UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: contractorPayments
      x-speakeasy-name-override: list
    post:
      summary: Create a contractor payment
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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)

        scope: `payrolls:run`
      tags:
        - Contractor Payments
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Contractor-Payment"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided ID/UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Contractor-Payment-Body"
        required: true
      x-speakeasy-group: contractorPayments
      x-speakeasy-name-override: create
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `payrolls:read`
      tags:
        - Contractor Payments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Contractor-Payment"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided ID/UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: get
      x-speakeasy-group: contractorPayments
    delete:
      summary: Cancel a contractor payment
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `payrolls:run`
      tags:
        - Contractor Payments
      x-gusto-integration-type:
        - embedded
      responses:
        '204':
          description: No Content
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided ID/UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-group: contractorPayments
      x-speakeasy-name-override: delete
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        If the payment method is Check or Historical payment, the debit_date will be the same as the check_date.

        scope: `payrolls:read`
      tags:
        - Contractor Payments
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Contractor-Payments-Preview"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Contractor-Payments-Preview-Body"
        required: true
      x-speakeasy-name-override: preview
      x-speakeasy-group: contractorPayments
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Notes:
        * Receipts are only available for direct deposit payments and are only available once those payments have been funded.
        * Payroll Receipt requests for payrolls which do not have receipts available (e.g. payment by check) will return a 404 status.
        * Hour and dollar amounts are returned as string representations of numeric decimals.
        * Dollar amounts are represented to the cent.
        * If no data has yet be inserted for a given field, it defaults to “0.00” (for fixed amounts).

        scope: `payrolls:read`
      tags:
        - Contractor Payments
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Contractor-Payment-Receipt"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getReceipt
      x-speakeasy-group: contractorPayments
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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: "> \U0001F6A7 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:
              schema:
                "$ref": "#/components/schemas/Contractor-Payment"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-group: contractorPayments
      x-speakeasy-name-override: fund
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `payrolls:read`
      tags:
        - Contractor Payments
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: A PDF document of the contractor payment
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided ID/UUID is valid.
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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
        Schedules a contractor rehire for a given date. Creates a new employment record for the contractor.

        ## Prerequisites
        Before calling this endpoint:
        1. The contractor must be inactive (previously dismissed)
        2. The contractor must not already have an upcoming employment

        ## Related webhooks
        - `contractor.reactivated`: Fires when the rehire is recorded
        - `contractor.reactivation_effective`: Fires when the rehire takes effect (on start_date)

        scope: `contractors:write`
      tags:
        - Contractors
      x-gusto-integration-type:
        - embedded
      responses:
        '204':
          description: no content
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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
        Cancels a pending contractor rehire. For future-dated rehires, cancellation is available anytime before the date.
        For past-dated rehires, cancellation is only available within the 2-day grace period.

        ## Prerequisites
        Before calling this endpoint:
        - The contractor must have a pending rehire (upcoming employment)

        ## Related webhooks
        - `contractor.reactivation_cancelled`: Fires when the pending rehire is cancelled

        scope: `contractors:write`
      tags:
        - Contractors
      x-gusto-integration-type:
        - embedded
      responses:
        '204':
          description: no content
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
  "/v1/contractors/{contractor_uuid}/termination":
    post:
      summary: Schedule a contractor termination
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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
        Schedules a contractor dismissal for a given date. Supports both immediate (past dates) and future-dated dismissals.

        ## Prerequisites
        Before calling this endpoint:
        1. The contractor must be active (no existing pending dismissal)
        2. The contractor must have a current employment

        ## Related webhooks
        - `contractor.deactivated`: Fires when the dismissal is recorded
        - `contractor.deactivation_effective`: Fires when the dismissal takes effect (the day after end_date)

        scope: `contractors:write`
      tags:
        - Contractors
      x-gusto-integration-type:
        - embedded
      responses:
        '204':
          description: no content
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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
        Cancels a pending contractor dismissal. For future-dated dismissals, cancellation is available anytime before the date.
        For past-dated dismissals, cancellation is only available within the 2-day grace period.

        ## Prerequisites
        Before calling this endpoint:
        - The contractor must have a pending dismissal (scheduled or within the grace period)

        ## Related webhooks
        - `contractor.deactivation_cancelled`: Fires when the pending dismissal is cancelled

        scope: `contractors:write`
      tags:
        - Contractors
      x-gusto-integration-type:
        - embedded
      responses:
        '204':
          description: no content
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
  "/v1/contractors/{contractor_uuid}":
    get:
      summary: Get a contractor
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `contractors:read`
      tags:
        - Contractors
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Contractor-Show"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: get
    put:
      summary: Update a contractor
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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> \U0001F6A7 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:
              schema:
                "$ref": "#/components/schemas/Contractor"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Contractor-Update-Request-Body"
        required: true
      x-speakeasy-name-override: update
    delete:
      summary: Delete a contractor
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `contractors:manage`
      tags:
        - Contractors
      x-gusto-integration-type:
        - embedded
      responses:
        '204':
          description: No Content
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-name-override: delete
  "/v1/companies/{company_uuid}/contractors":
    get:
      summary: Get contractors of a company
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `contractors:read`
      tags:
        - Contractors
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Show-Contractors"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: list
    post:
      summary: Create a contractor
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `contractors:manage`
      tags:
        - Contractors
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '201':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Contractor"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Contractor-Create-Request-Body"
        required: true
      x-speakeasy-name-override: create
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ## onboarding_status

        ### Admin-facilitated onboarding
        | onboarding_status | Description |
        |:------------------|------------:|
        | `admin_onboarding_incomplete` | Admin needs to enter basic information about the contractor. |
        | `admin_onboarding_review` | All information has been completed and admin needs to confirm onboarding. |
        | `onboarding_completed` | Contractor has been fully onboarded and verified. |

        ### Contractor self-onboarding

        | onboarding_status | Description |
        | --- | ----------- |
        | `admin_onboarding_incomplete` | Admin needs to enter basic information about the contractor. |
        | `self_onboarding_not_invited` | Admin has the intention to invite the contractor to self-onboard (e.g., marking a checkbox), but the system has not yet sent the invitation. |
        | `self_onboarding_invited` | Contractor has been sent an invitation to self-onboard. |
        | `self_onboarding_started` | Contractor has started the self-onboarding process. |
        | `self_onboarding_review` | Admin needs to review contractors's entered information and confirm onboarding. |
        | `onboarding_completed` | Contractor has been fully onboarded and verified. |

        ## onboarding_steps

        | onboarding_steps | Requirement(s) to be completed |
        |:-----------------|-------------------------------:|
        | `basic_details` | Add individual contractor's first name, last name, social security number or Business name and EIN depending on the contractor type |
        | `add_address` | Add contractor address. |
        | `compensation_details` | Add contractor compensation. |
        | `payment_details` | (optional) Set up contractor's direct deposit or set to check. |
        | `sign_documents` | Contractor forms (e.g., W9) are generated & signed. |
        | `file_new_hire_report` | Contractor new hire report is generated. |

        scope: `contractors:read`
      tags:
        - Contractors
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Contractor-Onboarding-Status"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getOnboardingStatus
    put:
      summary: Change the contractor's onboarding status
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Below is a list of valid onboarding status changes depending on the intended action to be performed on behalf of the contractor.

        | Action | current onboarding_status | new onboarding_status |
        |:------------------|:------------:|----------:|
        | Mark a contractor as self-onboarding | `admin_onboarding_incomplete` | `self_onboarding_not_invited` |
        | Invite a contractor to self-onboard | `admin_onboarding_incomplete` or `self_onboarding_not_invited` | `self_onboarding_invited` |
        | Cancel a contractor's self-onboarding | `self_onboarding_invited` or `self_onboarding_not_invited` | `admin_onboarding_incomplete` |
        | Review a contractor's self-onboarded info | `self_onboarding_started` | `self_onboarding_review` |
        | Finish a contractor's onboarding | `admin_onboarding_review` or `self_onboarding_review` | `onboarding_completed` |

        scope: `contractors:write`
      tags:
        - Contractors
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Contractor-Onboarding-Status"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Contractor-Onboarding-Status-Update-Request-Body"
        required: true
      x-speakeasy-name-override: updateOnboardingStatus
  "/v1/departments/{department_uuid}":
    get:
      summary: Get a department
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `departments:read`
      tags:
        - Departments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Department"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: get
    put:
      summary: Update a department
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `departments:write`
      tags:
        - Departments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Department"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Conflict-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Department-Update-Request-Body"
        required: true
      x-speakeasy-name-override: update
    delete:
      summary: Delete a department
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `departments:write`
      tags:
        - Departments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '204':
          description: No Content
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-name-override: delete
  "/v1/departments/{department_uuid}/add":
    put:
      summary: Add people to a department
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `departments:write`
      tags:
        - Departments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Department"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Department-People-Request-Body"
        required: true
      x-speakeasy-name-override: addPeople
  "/v1/departments/{department_uuid}/remove":
    put:
      summary: Remove people from a department
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `departments:write`
      tags:
        - Departments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Department"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Department-People-Request-Body"
        required: true
      x-speakeasy-name-override: removePeople
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `departments:read`
      tags:
        - Departments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Department-List"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getAll
    post:
      summary: Create a department
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `departments:write`
      tags:
        - Departments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Department"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Department-Create-Request-Body"
        required: true
      x-speakeasy-name-override: create
  "/v1/contractors/{contractor_uuid}/documents":
    get:
      summary: Get all contractor documents
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `contractor_documents:read`
      tags:
        - Contractor Documents
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Document"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: contractorDocuments
      x-speakeasy-name-override: getAll
  "/v1/documents/{document_uuid}":
    get:
      summary: Get a contractor document
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `contractor_documents:read`
      tags:
        - Contractor Documents
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Document"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: get
      x-speakeasy-group: contractorDocuments
  "/v1/documents/{document_uuid}/pdf":
    get:
      summary: Get the contractor document pdf
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `contractor_documents:read`
      tags:
        - Contractor Documents
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Document-Pdf"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: contractorDocuments
      x-speakeasy-name-override: getPdf
  "/v1/documents/{document_uuid}/sign":
    put:
      summary: Sign a contractor document
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `contractor_documents:write`
      tags:
        - Contractor Documents
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Document-Signed"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-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
      x-speakeasy-group: contractorDocuments
      x-speakeasy-name-override: sign
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        #### Default Earning Type
        Certain earning types are special because they have tax considerations. Those earning types are mostly the same for every company depending on its legal structure (LLC, Corporation, etc.)

        #### Custom Earning Type
        Custom earning types are all the other earning types added specifically for a company.

        scope: `payrolls:read`
      tags:
        - Earning Types
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Earning-Type-List"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: earningTypes
      x-speakeasy-name-override: list
    post:
      summary: Create a custom earning type
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        If an inactive earning type exists with the same name, this will reactivate it instead of creating a new one.

        scope: `payrolls:write`
      tags:
        - Earning Types
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Earning-Type"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  default: Gym Membership
                  description: The name of the custom earning type.
                category:
                  type: string
                  description: The earning type category. Only settable when the company has access to categorized custom bonus earning types.
                  enum:
                    - Commission
                    - DiscretionaryBonus
                    - ServiceCharges
                    - OnCallPay
                    - Other
                included_in_overtime_pay:
                  type: boolean
                  description: Whether earnings of this type are included when calculating an employee's regular rate of pay for overtime purposes. Only settable when `category` is `Other`.
        required: true
      x-speakeasy-group: earningTypes
      x-speakeasy-name-override: create
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `payrolls:write`
      tags:
        - Earning Types
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Earning-Type"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the custom earning type.
                category:
                  type: string
                  description: The earning type category. Set at creation and immutable afterward — submitting a value that differs from the current one returns a 422. Submitting the current value (e.g. when echoing back the full resource) is allowed.
                included_in_overtime_pay:
                  type: boolean
                  description: Whether earnings of this type are included in overtime pay calculations. Editable only when the category is `Other`; otherwise immutable — submitting a value that differs from the current one returns a 422. Submitting the current value (e.g. when echoing back the full resource) is allowed.
        required: true
      x-speakeasy-group: earningTypes
      x-speakeasy-name-override: update
    delete:
      summary: Deactivate an earning type
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `payrolls:write`
      tags:
        - Earning Types
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '204':
          description: No Content
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: earningTypes
      x-speakeasy-name-override: delete
  "/v1/employees/{employee_id}/bank_accounts":
    get:
      summary: List employee bank accounts
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employee_payment_methods:read`
      tags:
        - Employee Payment Method
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Employee-Bank-Account"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: employeePaymentMethods
      x-speakeasy-name-override: getBankAccounts
    post:
      summary: Create an employee bank account
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employee_payment_methods:write`
      tags:
        - Employee Payment Method
      x-gusto-integration-type:
        - embedded
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Bank-Account"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Employee-Bank-Account-Request"
        required: true
      x-speakeasy-group: employeePaymentMethod
      x-speakeasy-name-override: create
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employee_payment_methods:write`
      tags:
        - Employee Payment Method
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Bank-Account"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Employee-Bank-Account-Request"
        required: true
      x-speakeasy-group: employeePaymentMethod
      x-speakeasy-name-override: updateBankAccount
    delete:
      summary: Delete an employee bank account
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employee_payment_methods:write`
      tags:
        - Employee Payment Method
      x-gusto-integration-type:
        - embedded
      responses:
        '204':
          description: No Content
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-group: employeePaymentMethod
      x-speakeasy-name-override: deleteBankAccount
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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:
            - 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.

        Returns an array of all employee benefits for this employee

        Benefits containing PHI are only visible to applications with the `employee_benefits:read:phi` scope.

        scope: `employee_benefits:read`
      tags:
        - Employee Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Employee-Benefit"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: employeeBenefits
      x-speakeasy-name-override: get
    post:
      summary: Create an employee benefit
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        When 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.

        scope: `employee_benefits:write`
      tags:
        - Employee Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '201':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Benefit"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Employee-Benefit-Create-Request"
        required: true
      x-speakeasy-name-override: create
      x-speakeasy-group: employeeBenefits
  "/v1/employee_benefits/{employee_benefit_id}":
    get:
      summary: Get an employee benefit
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Benefits containing PHI are only visible to applications with the `employee_benefits:read:phi` scope.

        scope: `employee_benefits:read`
      tags:
        - Employee Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Benefit"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: retrieve
      x-speakeasy-group: employeeBenefits
    put:
      summary: Update an employee benefit
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        When 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.

        scope: `employee_benefits:write`
      tags:
        - Employee Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Benefit"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Employee-Benefit-Update-Request"
        required: true
      x-speakeasy-group: employeeBenefits
      x-speakeasy-name-override: update
    delete:
      summary: Delete an employee benefit
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        When 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.

        scope: `employee_benefits:write`
      tags:
        - Employee Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '204':
          description: No Content
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-group: employeeBenefits
      x-speakeasy-name-override: delete
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employees:read`
      tags:
        - Employees
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Custom-Field-List"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getCustomFields
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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).

        scope: `employee_federal_taxes:read`
      tags:
        - Employee Tax Setup
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Federal-Tax"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: employeeTaxSetup
      x-speakeasy-name-override: getFederalTaxes
    put:
      summary: Update federal taxes for an employee
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employee_federal_taxes:write`
      tags:
        - Employee Tax Setup
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Federal-Tax"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '409':
          description: Conflict
          content:
            application/json:
              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
      x-speakeasy-group: employeeTaxSetup
      x-speakeasy-name-override: updateFederalTaxes
  "/v1/employees/{employee_id}/forms":
    get:
      summary: Get all employee forms
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `employee_forms:read`
      tags:
        - Employee Forms
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Form"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: list
      x-speakeasy-group: employeeForms
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `employee_forms:read`
      tags:
        - Employee Forms
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Form"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: employeeForms
      x-speakeasy-name-override: get
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `employee_forms:read`
      tags:
        - Employee Forms
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Form-Pdf"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: employeeForms
      x-speakeasy-name-override: getPdf
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        The optional preparer attributes are only valid for I-9 form. When a preparer is used, the
        first name, last name, street address, city, state, and zip for that preparer are all required.

        scope: `employee_forms:sign`
      tags:
        - Employee Forms
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Form"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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
      x-speakeasy-group: employeeForms
      x-speakeasy-name-override: sign
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Use the `employee_uuid` query parameter to filter for a single employee.
        Use the `payroll_uuid` query parameter to filter for employees on a specific payroll.
        Providing both `employee_uuid` and `payroll_uuid` will result in a 422 error.
        An empty array is returned if the company has no employees or if no employees match the filter criteria.

        The `encrypted_account_number` in the `splits` array is only visible if the `employee_payment_methods:read:account_number` scope is present.

        scope: `employee_payment_methods:read`
      tags:
        - Employees
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: A list of employee payment details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Payment-Details-List"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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).

        scope: `employee_payment_methods:read`
      tags:
        - Employee Payment Method
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Payment-Method"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: employeePaymentMethod
      x-speakeasy-name-override: get
    put:
      summary: Update payment method for an employee
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employee_payment_methods:write`
      tags:
        - Employee Payment Method
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Payment-Method"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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. Amount must be less than or equal to 2147483647. If split_by is Percentage, value is the percentage (e.g., 60 for 60%).
        required: true
      x-speakeasy-group: employeePaymentMethod
      x-speakeasy-name-override: update
  "/v1/employees/{employee_id}/rehire":
    get:
      summary: Get an employee rehire
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employments:read`
      tags:
        - Employee Employments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Rehire"
        '204':
          description: No Content
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: employeeEmployments
      x-speakeasy-name-override: getRehire
    post:
      summary: Create an employee rehire
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employments:write`
      tags:
        - Employee Employments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Rehire"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Rehire-Body"
        required: true
      x-speakeasy-group: employeeEmployments
      x-speakeasy-name-override: createRehire
    put:
      summary: Update an employee rehire
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employments:write`
      tags:
        - Employee Employments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Rehire"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Rehire-Update-Request-Body"
        required: true
      x-speakeasy-group: employeeEmployments
      x-speakeasy-name-override: rehire
    delete:
      summary: Delete an employee rehire
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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).

        scope: `employments:write`
      tags:
        - Employee Employments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '204':
          description: No Content
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-group: employeeEmployments
      x-speakeasy-name-override: deleteRehire
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Section 603 of the SECURE 2.0 Act applies to employees aged 50 or older whose prior-year FICA wages exceed the IRS threshold.
        These employees are classified as high earners, and their catch-up contributions to pre-tax retirement benefits must be designated as post-tax contributions.

        scope: `employee_benefits:read`
      tags:
        - Employee Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful - with records
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Section603-High-Earner-Status-List"
        '404':
          description: Not Found
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Section 603 of the SECURE 2.0 Act applies to employees aged 50 or older whose prior-year FICA wages exceed the IRS threshold.
        These employees are classified as high earners, and their catch-up contributions to pre-tax retirement benefits must be designated as post-tax contributions.

        scope: `employee_benefits:write`
      tags:
        - Employee Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '201':
          description: created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Section603-High-Earner-Status"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '409':
          description: conflict - record already exists
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '422':
          description: unprocessable entity - invalid is_high_earner
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Section 603 of the SECURE 2.0 Act applies to employees aged 50 or older whose prior-year FICA wages exceed the IRS threshold.
        These employees are classified as high earners, and their catch-up contributions to pre-tax retirement benefits must be designated as post-tax contributions.

        scope: `employee_benefits:read`
      tags:
        - Employee Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Section603-High-Earner-Status"
        '404':
          description: Not Found - employee does not exist
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: unprocessable entity - invalid effective_year
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Section 603 of the SECURE 2.0 Act applies to employees aged 50 or older whose prior-year FICA wages exceed the IRS threshold.
        These employees are classified as high earners, and their catch-up contributions to pre-tax retirement benefits must be designated as post-tax contributions.

        scope: `employee_benefits:write`
      tags:
        - Employee Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Section603-High-Earner-Status"
        '404':
          description: Not Found - employee does not exist
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: unprocessable entity - invalid is_high_earner
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

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

        Answers are represented by an array. Today, this array can only be empty or contain exactly one element, but is designed to allow for forward compatibility with effective-dated fields. The `valid_from` and `valid_up_to` fields are optional and currently ignored.

        ## About filing new hire reports
        Payroll Admins are responsible for filing a new hire report for each Employee. The `file_new_hire_report` question will only be listed if:
        - the `employee.onboarding_status` is one of the following:
          - `admin_onboarding_incomplete`
          - `self_onboarding_awaiting_admin_review`
        - that employee's work state requires filing a new hire report

        scope: `employee_state_taxes:read`
      tags:
        - Employee Tax Setup
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-State-Taxes-List"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: employeeTaxSetup
      x-speakeasy-name-override: getStateTaxes
    put:
      summary: Update an employee's state taxes
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        As described for the GET endpoint, the answers must be supplied in the effective-dated format, but currently only a single answer will be accepted. The `valid_from` and `valid_up_to` fields are optional and currently ignored.

        scope: `employee_state_taxes:write`
      tags:
        - Employee Tax Setup
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-State-Taxes-List"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Employee-State-Taxes-Request"
        required: true
      x-speakeasy-group: employeeTaxSetup
      x-speakeasy-name-override: updateStateTaxes
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employee_time_off_activities:read`
      tags:
        - Employees
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Time-Off-Activity-List"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-name-override: getTimeOffActivities
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        This 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.

        The 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.

        scope: `company_reports:write`
      tags:
        - Reports
      x-gusto-integration-type:
        - embedded
      responses:
        '202':
          description: accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employees-Annual-Fica-Wage-Report-Acceptance"
        '422':
          description: unprocessable entity - start year before minimum
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Note: 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.

        scope: `employees:read`
      tags:
        - Employees
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Show"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: get
    put:
      summary: Update an employee.
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employees:write`
      tags:
        - Employees
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee"
        '409':
          description: invalid version
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '422':
          description: invalid attributes
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-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
      x-speakeasy-name-override: update
    delete:
      summary: Delete an onboarding employee
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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
        an onboarded employee is not allowed and will return a 422 response. Please check out the Terminations api
        if you need to terminate an onboarded employee.

        scope: `employees:manage`
      tags:
        - Employees
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '204':
          description: successful
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: cannot delete onboarded employee
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-name-override: delete
  "/v1/companies/{company_id}/employees":
    get:
      summary: Get employees of a company
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Note: 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.

        scope: `employees:read`
      tags:
        - Employees
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Show-Employees"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: list
    post:
      summary: Create an employee
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employees:manage`
      tags:
        - Employees
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '201':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: invalid attributes
          content:
            application/json:
              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
      x-speakeasy-name-override: create
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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
        Retrieves an employee's onboarding status. The data returned helps inform the required onboarding steps and respective completion status.


        ## onboarding_status

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

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

        ## onboarding_steps

        | onboarding_steps | Requirement(s) to be completed |
        |:-----------------|-------------------------------:|
        | `personal_details` | Add employee's first name, last name, email, date of birth, social security number |
        | `compensation_details` | Associate employee to a job & compensation. |
        | `add_work_address` | Add employee work address. |
        | `add_home_address` | Add employee home address. |
        | `federal_tax_setup` | Set up federal tax withholdings. |
        | `state_tax_setup` | Set up state tax withholdings. |
        | `direct_deposit_setup` | (optional) Set up employee's direct deposit. |
        | `employee_form_signing` | Employee forms (e.g., W4, direct deposit authorization) are generated & signed. |
        | `file_new_hire_report` | File a new hire report for this employee. |
        | `admin_review` | Admin reviews & confirms employee details (only required for Employee self-onboarding) |

        scope: `employees:read`
      tags:
        - Employees
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Onboarding-Status"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getOnboardingStatus
    put:
      summary: Update the employee's onboarding status
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.
        Below is a list of valid onboarding status changes depending on the intended action to be performed on behalf of the employee.

        | Action | current onboarding_status | new onboarding_status |
        |:------------------|:------------:|----------:|
        | Mark an employee as self-onboarding | `admin_onboarding_incomplete` | `self_onboarding_pending_invite` |
        | Invite an employee to self-onboard | `admin_onboarding_incomplete` or `self_onboarding_pending_invite` | `self_onboarding_invited` |
        | Cancel an employee's self-onboarding | `self_onboarding_invited` or `self_onboarding_pending_invite` | `admin_onboarding_incomplete` |
        | Review an employee's self-onboarded info | `self_onboarding_completed_by_employee` | `self_onboarding_awaiting_admin_review` |
        | Finish an employee's onboarding | `admin_onboarding_incomplete` or `self_onboarding_awaiting_admin_review` | `onboarding_completed` |

        scope: `employees:manage`
      tags:
        - Employees
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Onboarding-Status"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: invalid status transition
          content:
            application/json:
              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
      x-speakeasy-name-override: updateOnboardingStatus
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.
        If included, the employee will be prompted to complete Form I-9 as part of their onboarding.

        ## Related guides
        - [Employee onboarding](doc:employee-onboarding)

        scope: `employees:manage`
      tags:
        - Employees
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Onboarding-Document"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Employee-Onboarding-Documents-Config-Request"
      x-speakeasy-name-override: updateOnboardingDocumentsConfig
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employments:read`
      tags:
        - Employee Employments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employment-History-List"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: employeeEmployments
      x-speakeasy-name-override: getHistory
  "/v1/events":
    get:
      summary: Get all events
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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\U0001F4D8 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:
              schema:
                "$ref": "#/components/schemas/Event-List"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-name-override: get
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `external_payrolls:read`
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/External-Payroll-Basic"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: externalPayrolls
      x-speakeasy-name-override: get
    post:
      summary: Create an external payroll for a company
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `external_payrolls:write`
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/External-Payroll"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/External-Payroll-Create-Request"
        required: true
      x-speakeasy-group: externalPayrolls
      x-speakeasy-name-override: create
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `external_payrolls:read`
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Tax-Liabilities-Selections"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: externalPayrolls
      x-speakeasy-name-override: listTaxLiabilities
    put:
      summary: Update tax liabilities
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `external_payrolls:write`
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Tax-Liabilities-Selections"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Tax-Liability-Selections-Request"
        required: true
      x-speakeasy-group: externalPayrolls
      x-speakeasy-name-override: updateTaxLiabilities
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ### Asynchronous processing
        This endpoint triggers an asynchronous operation. The external payrolls will be processed in the background after finalization.

        scope: `external_payrolls:write`
      responses:
        '202':
          description: Accepted
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-group: externalPayrolls
      x-speakeasy-name-override: finalizeTaxLiabilities
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `external_payrolls:read`
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/External-Payroll"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: externalPayrolls
      x-speakeasy-name-override: retrieve
    put:
      summary: Update an external payroll
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `external_payrolls:write`
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/External-Payroll"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/External-Payroll-Update-Request"
        required: true
      x-speakeasy-group: externalPayrolls
      x-speakeasy-name-override: update
    delete:
      summary: Delete an external payroll
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `external_payrolls:write`
      responses:
        '204':
          description: No Content
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-group: externalPayrolls
      x-speakeasy-name-override: delete
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `external_payrolls:read`
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/External-Payroll-Tax-Suggestions"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-group: externalPayrolls
      x-speakeasy-name-override: calculateTaxes
  "/v1/companies/{company_uuid}/flows":
    post:
      summary: Create a flow
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        You can see a list of all possible flow types in our [Flow Types](https://docs.gusto.com/embedded-payroll/docs/flow-types) guide.

        You can also mix and match flow_types in the same category to create custom flows suitable for your needs.

        For 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:

        ```json
        {
          "flow_type": "add_addresses,add_employees,sign_all_forms"
        }
        ```

        Please be mindful of data dependencies in each step to achieve the best user experience.

        For more information and in-depth guides review the [Getting Started](https://docs.gusto.com/embedded-payroll/docs/flows-getting-started) guide for flows.

        scope: `flows:write`
      tags:
        - Flows
      x-gusto-integration-type:
        - embedded
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Flow"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Create-Flow-Request"
        required: true
      x-speakeasy-name-override: create
  "/v1/employees/{employee_id}/garnishments":
    get:
      summary: Get garnishments for an employee
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `garnishments:read`
      tags:
        - Garnishments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Garnishment"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: list
    post:
      summary: Create a garnishment
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `garnishments:write`
      tags:
        - Garnishments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '201':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Garnishment"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Garnishment-Request"
        required: true
      x-speakeasy-name-override: create
  "/v1/garnishments/child_support":
    get:
      summary: Get child support garnishment data
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. 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

        scope: `garnishments:read`
      tags:
        - Garnishments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Child-Support-Data"
      x-speakeasy-name-override: getChildSupportData
  "/v1/garnishments/{garnishment_id}":
    get:
      summary: Get a garnishment
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `garnishments:read`
      tags:
        - Garnishments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Garnishment"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: get
    put:
      summary: Update a garnishment
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `garnishments:write`
      tags:
        - Garnishments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Garnishment"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Update-Garnishment-Request"
        required: true
      x-speakeasy-name-override: update
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `generated_documents:write`
      tags:
        - Payrolls
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Payroll-Check"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Printable-Payroll-Checks-Body"
        required: true
      x-speakeasy-name-override: generatePrintableChecks
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `generated_documents:read`
      tags:
        - Generated Documents
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Generated-Document"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: generatedDocuments
      x-speakeasy-name-override: get
  "/v1/companies/{company_uuid}/historical_employees":
    post:
      summary: Create a historical employee
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employees:manage`
      tags:
        - Employees
      x-gusto-integration-type:
        - embedded
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Historical-Employee-Body"
        required: true
      x-speakeasy-name-override: createHistorical
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employees:manage employees:write`
      tags:
        - Employees
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - "$ref": "#/components/schemas/Versionable-Required"
                - "$ref": "#/components/schemas/Historical-Employee-Body"
        required: true
      x-speakeasy-group: historicalEmployees
      x-speakeasy-name-override: update
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `holiday_pay_policies:read`
      tags:
        - Holiday Pay Policies
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Holiday-Pay-Policy"
        '204':
          description: no policy exists
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: holidayPayPolicies
      x-speakeasy-name-override: get
    post:
      summary: Create a holiday pay policy for a company
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `holiday_pay_policies:write`
      tags:
        - Holiday Pay Policies
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Holiday-Pay-Policy"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: company already has a policy
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Holiday-Pay-Policy-Request"
      x-speakeasy-group: holidayPayPolicies
      x-speakeasy-name-override: create
    put:
      summary: Update a company's holiday pay policy
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `holiday_pay_policies:write`
      tags:
        - Holiday Pay Policies
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Holiday-Pay-Policy"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: no policy exists
          content:
            application/json:
              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
      x-speakeasy-group: holidayPayPolicies
      x-speakeasy-name-override: update
    delete:
      summary: Delete a company's holiday pay policy
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `holiday_pay_policies:write`
      tags:
        - Holiday Pay Policies
      x-gusto-integration-type:
        - embedded
      responses:
        '204':
          description: successful
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: no policy exists
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-group: holidayPayPolicies
      x-speakeasy-name-override: delete
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `holiday_pay_policies:write`
      tags:
        - Holiday Pay Policies
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Holiday-Pay-Policy"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: no policy exists
          content:
            application/json:
              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
      x-speakeasy-group: holidayPayPolicies
      x-speakeasy-name-override: addEmployees
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `holiday_pay_policies:write`
      tags:
        - Holiday Pay Policies
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Holiday-Pay-Policy"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: no policy exists
          content:
            application/json:
              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
      x-speakeasy-group: holidayPayPolicies
      x-speakeasy-name-override: removeEmployees
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Supports home address effective dating and courtesy withholding.

        scope: `employees:read`
      tags:
        - Employee Addresses
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Address-List"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: employeeAddresses
      x-speakeasy-name-override: get
    post:
      summary: Create an employee's home address
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Supports home address effective dating and courtesy withholding.

        scope: `employees:write`
      tags:
        - Employee Addresses
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '201':
          description: created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Address"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-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
      x-speakeasy-group: employeeAddresses
      x-speakeasy-name-override: create
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Supports home address effective dating and courtesy withholding.

        scope: `employees:read`
      tags:
        - Employee Addresses
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Address"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: employeeAddresses
      x-speakeasy-name-override: retrieveHomeAddress
    put:
      summary: Update an employee's home address
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Supports home address effective dating and courtesy withholding.

        scope: `employees:write`
      tags:
        - Employee Addresses
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Address"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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
      x-speakeasy-group: employeeAddresses
      x-speakeasy-name-override: update
    delete:
      summary: Delete an employee's home address
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employees:write`
      tags:
        - Employee Addresses
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '204':
          description: successful
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-group: employeeAddresses
      x-speakeasy-name-override: delete
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        **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.

        ### Related guides
        - [I-9 employment verification](doc:i-9-employment-verification)

        scope: `i9_authorizations:read`
      tags:
        - I-9 Verification
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/I9-Authorization"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: i9Verification
      x-speakeasy-name-override: getAuthorization
    put:
      summary: Create or update an employee's I-9 authorization
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        If 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.

        Validations on this endpoint are conditional:
          * `document_type` may be required, depending on `authorization_status`.
          * Valid formats for `document_number` vary, depending on `document_type`.
          * `country` is only allowed with `document_type: 'foreign_passport'`.
          * `expiration_date` is only allowed with `authorization_status: 'alien'`.

        > ℹ️ Unneeded information is automatically removed during updates.
        >
        > If an update causes some formerly-required fields to be unneeded, the now-unneeded data will be removed automatically.
        >
        > **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'`.

        Detailed instructions for completing Form I-9 can be found at https://www.uscis.gov/sites/default/files/document/forms/i-9instr.pdf

        ### Related guides
        - [I-9 employment verification](doc:i-9-employment-verification)

        scope: `i9_authorizations:write`
      tags:
        - I-9 Verification
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/I9-Authorization"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/I9-Authorization-Request-Body"
        required: true
      x-speakeasy-name-override: update
      x-speakeasy-group: i9Verification
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ### Related guides
        - [I-9 employment verification](doc:i-9-employment-verification)

        scope: `i9_authorizations:read`
      tags:
        - I-9 Verification
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/I9-Authorization-Document-Option"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: i9Verification
      x-speakeasy-name-override: getDocumentOptions
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ### Related guides
        - [I-9 employment verification](doc:i-9-employment-verification)

        scope: `i9_authorizations:read`
      tags:
        - I-9 Verification
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/I9-Authorization-Document"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: i9Verification
      x-speakeasy-name-override: getDocuments
    put:
      summary: Create an employee's I-9 authorization verification documents
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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> \U0001F6A7 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:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/I9-Authorization-Document"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/I9-Authorization-Documents-Request-Body"
        required: true
      x-speakeasy-group: i9Verification
      x-speakeasy-name-override: createDocuments
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ### Related guides
        - [I-9 employment verification](doc:i-9-employment-verification)

        scope: `i9_authorizations:manage`
      tags:
        - I-9 Verification
      x-gusto-integration-type:
        - embedded
      responses:
        '204':
          description: No Content
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-group: i9Verification
      x-speakeasy-name-override: deleteDocument
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ### Prerequisites
        Before calling this endpoint:
        1. The employee must have a completed [I-9 authorization](ref:put-v1-employees-employee_id-i9_authorization)
        2. The employee must have signed the Form I-9
        3. [I-9 verification documents](ref:put-v1-employees-employee_id-i9_authorization-documents) must be submitted

        ### Related guides
        - [I-9 employment verification](doc:i-9-employment-verification)

        scope: `i9_authorizations:manage`
      tags:
        - I-9 Verification
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/I9-Authorization"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/I9-Authorization-Employer-Sign-Request-Body"
        required: true
      x-speakeasy-group: i9Verification
      x-speakeasy-name-override: employerSign
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `information_requests:read`
      tags:
        - Information Requests
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Information-Request"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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\U0001F4D8 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:
              schema:
                "$ref": "#/components/schemas/Invoice-Data"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-name-override: get
  "/v1/jobs/{job_id}":
    get:
      summary: Get a job
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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:
            - all_compensations: Include all effective dated compensations for each job instead of only the current compensation
      x-gusto-rswag: true
      operationId: get-v1-jobs-job_id
      security:
        - CompanyAccessAuth: []
      description: |-
        Get a job.

        Note: 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.

        Compensation data in the response requires the `compensations:read` scope.

        scope: `jobs:read`
      tags:
        - Jobs and Compensations
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Job"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: jobsAndCompensations
      x-speakeasy-name-override: getJob
    put:
      summary: Update a job
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `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:
              schema:
                "$ref": "#/components/schemas/Job"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Jobs-Update-Request-Body"
        required: true
      x-speakeasy-name-override: update
      x-speakeasy-group: jobsAndCompensations
    delete:
      summary: Delete an individual job
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `jobs:write`
      tags:
        - Jobs and Compensations
      x-gusto-integration-type:
        - embedded
      responses:
        '204':
          description: successful
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-group: jobsAndCompensations
      x-speakeasy-name-override: delete
  "/v1/employees/{employee_id}/jobs":
    get:
      summary: Get jobs for an employee
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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:
            - all_compensations: Include all effective dated compensations for each job instead of only the current compensation
      x-gusto-rswag: true
      operationId: get-v1-employees-employee_id-jobs
      security:
        - CompanyAccessAuth: []
      description: |-
        Get all of the jobs that an employee holds.
        Note: 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.

        Compensation data in the response requires the `compensations:read` scope.

        scope: `jobs:read`
      tags:
        - Jobs and Compensations
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Job"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getJobs
      x-speakeasy-group: jobsAndCompensations
    post:
      summary: Create a job
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `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:
              schema:
                "$ref": "#/components/schemas/Job"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Jobs-Create-Request-Body"
        required: true
      x-speakeasy-group: jobsAndCompensations
      x-speakeasy-name-override: createJob
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `companies:read`
      tags:
        - Locations
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Minimum-Wage-List"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getMinimumWages
  "/v1/locations/{location_id}":
    get:
      summary: Get a location
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `companies:read`
      tags:
        - Locations
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Location"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: retrieve
    put:
      summary: Update a location
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `companies:write`
      tags:
        - Locations
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Location"
        '422':
          description: Invalid state
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '409':
          description: Invalid version param
          content:
            application/json:
              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
      x-speakeasy-name-override: update
  "/v1/companies/{company_id}/locations":
    get:
      summary: Get all company locations
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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
        addresses, or work locations. A single address may serve multiple, or all, purposes.

        Since all company locations are subsets of locations, use the Locations endpoints to
        [get](ref:get-v1-locations-location_id) or [update](ref:put-v1-locations-location_id) an individual record.

        scope: `companies:read`
      tags:
        - Locations
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Company-Locations-List"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: get
    post:
      summary: Create a company location
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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
        addresses, filing addresses, or work locations. A single address may serve multiple, or all, purposes.

        Since all company locations are subsets of locations, use the Locations endpoints to
        [get](ref:get-v1-locations-location_id) or [update](ref:put-v1-locations-location_id) an individual record.

        scope: `companies:write`
      tags:
        - Locations
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Location"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Company-Location-Request"
        required: true
      x-speakeasy-name-override: create
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `member_portal_invitation:write`
      tags:
        - Member Portal Invitations
      x-gusto-integration-type:
        - embedded
      responses:
        '201':
          description: Created
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
    get:
      summary: Get an employee member portal invitation
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `member_portal_invitation:read`
      tags:
        - Member Portal Invitations
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Member-Portal-Invitation"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Note: 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.

        scope: `member_portal_invitation:write`
      tags:
        - Member Portal Invitations
      x-gusto-integration-type:
        - embedded
      responses:
        '204':
          description: No Content
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `member_portal_invitation:write`
      tags:
        - Member Portal Invitations
      x-gusto-integration-type:
        - embedded
      responses:
        '201':
          description: Created
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
    get:
      summary: Get a contractor member portal invitation
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `member_portal_invitation:read`
      tags:
        - Member Portal Invitations
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Member-Portal-Invitation"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Note: 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.

        scope: `member_portal_invitation:write`
      tags:
        - Member Portal Invitations
      x-gusto-integration-type:
        - embedded
      responses:
        '204':
          description: No Content
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
  "/v1/notifications/{notification_uuid}":
    get:
      summary: Get a notification's details
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Note: partners are responsible for the delivery and any custom state management of notifications in their application. Refer to our [partner notification guide](https://docs.gusto.com/embedded-payroll/docs/partner-notifications) for more details.

        If the notification UUID is not found, the response will be 404 Not Found. If the notification's supporting data is no longer valid, the response will be 422 Unprocessable Entity.

        scope: `notifications:read`
      tags:
        - Notifications
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Notification"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-name-override: getDetails
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        If a year is passed, paid holidays for that year will be returned. Otherwise, paid holidays for the next three years will be returned.

        scope: `holiday_pay_policies:read`
      tags:
        - Holiday Pay Policies
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Paid-Holiday"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: holidayPayPolicies
      x-speakeasy-name-override: previewPaidHolidays
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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\U0001F4D8 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:
              schema:
                "$ref": "#/components/schemas/Partner-Managed-Company-Disassociate-Response"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ### Prerequisites
        Before calling this endpoint:
        1. The customer must connect their Gusto account to your application using [OAuth2](doc:oauth2)
        2. The customer must view and [accept the Embedded Payroll Terms of Service](ref:post-partner-managed-companies-company_uuid-accept_terms_of_service)

        ### Related guides
        - [Migrate an existing company](doc:migrate-existing-company)

        scope: `partner_managed_companies:write`
      tags:
        - Companies
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Partner-Managed-Company-Migrate-Response"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Partner-Managed-Company-Migrate-Request"
        required: true
      x-speakeasy-name-override: migrate
  "/v1/partner_managed_companies":
    post:
      summary: Create a partner managed company
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. 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\U0001F4D8 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:
              schema:
                "$ref": "#/components/schemas/Partner-Managed-Company"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Partner-Managed-Company-Create-Request"
        required: true
      x-speakeasy-name-override: createPartnerManaged
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `partner_managed_companies:read`
      tags:
        - Companies
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Partner-Managed-Company-Migration-Readiness-Response"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              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 a company user
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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: []
      description: |-
        Accept the Gusto Embedded Payroll's [Terms of Service](https://flows.gusto.com/terms).
        The user must have a role in the company in order to accept the Terms of Service.

        scope: `terms_of_services:write`
      tags:
        - Companies
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Partner-Managed-Company-Terms-Of-Service-Response"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Partner-Managed-Company-Accept-Terms-Of-Service-Request"
        required: true
      x-speakeasy-name-override: acceptTermsOfService
  "/v1/partner_managed_companies/{company_uuid}/retrieve_terms_of_service":
    post:
      summary: Retrieve terms of service status for a company user
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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: []
      description: |-
        Retrieve the user acceptance status of the Gusto Embedded Payroll's [Terms of Service](https://flows.gusto.com/terms).

        scope: `terms_of_services:read`
      tags:
        - Companies
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Partner-Managed-Company-Terms-Of-Service-Response"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Partner-Managed-Company-Retrieve-Terms-Of-Service-Request"
        required: true
      x-speakeasy-name-override: retrieveTermsOfService
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        To begin submitting information for a given payroll, we need to agree on the time period.

        By default, this endpoint returns pay periods starting from 6 months ago to the date today. Use the `start_date` and `end_date` parameters to change the scope of the response. End dates can be up to 3 months in the future and there is no limit on start dates.

        Starting in version 2023-04-01, the `eligible_employees` attribute was removed from the response. The eligible employees for a payroll are determined by the employee_compensations returned from the [PUT /v1/companies/{company_id}/payrolls/{payroll_id}/prepare](ref:put-v1-companies-company_id-payrolls-payroll_id-prepare) endpoint.

        scope: `payrolls:read`
      tags:
        - Payrolls
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Pay-Period"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-group: paySchedules
      x-speakeasy-name-override: getPayPeriods
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        This endpoint returns the unprocessed pay periods for past and future terminated employees in a given company.

        scope: `payrolls:read`
      tags:
        - Pay Schedules
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Unprocessed-Termination-Pay-Period"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: paySchedules
      x-speakeasy-name-override: getUnprocessedTerminationPeriods
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `pay_schedules:read`
      tags:
        - Pay Schedules
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Pay-Schedule-Show-Response"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: paySchedules
      x-speakeasy-name-override: getAll
    post:
      summary: Create a new pay schedule
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        If a company has an existing active pay schedule and want to support multiple pay schedules, this endpoint will create a pay schedule that is not assigned to any employee.

        Be sure to **[check state laws](https://www.dol.gov/agencies/whd/state/payday)** to know what schedule is right for your customers.

        > If an onboarded company misses their first pay date, Gusto will automatically adjust the pay schedule to the next available pay date.

        ### Webhooks
        - `pay_schedule.created`: Fires when a pay schedule is successfully created.

        ### Related guides
        - [Create a pay schedule](doc:create-a-pay-schedule)
        - [Pay Schedules](doc:pay-schedule-info)
        - [Manage Pay Schedules via API](doc:manage-pay-schedules-api)

        scope: `pay_schedules:write`
      tags:
        - Pay Schedules
      x-gusto-integration-type:
        - embedded
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Pay-Schedule-Show"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Pay-Schedule-Create-Request"
        required: true
      x-speakeasy-group: paySchedules
      x-speakeasy-name-override: create
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ### Related guides
        - [Create a pay schedule](doc:create-a-pay-schedule)
        - [Manage Pay Schedules via API](doc:manage-pay-schedules-api)

        scope: `pay_schedules:write`
      tags:
        - Pay Schedules
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Pay-Schedule-Preview"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-group: paySchedules
      x-speakeasy-name-override: getPreview
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `pay_schedules:read`
      tags:
        - Pay Schedules
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Pay-Schedule-Show"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: get
      x-speakeasy-group: paySchedules
    put:
      summary: Update a pay schedule
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ### Effect on payrolls
        Updating 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.

        ### Pay schedules may be automatically adjusted
        If an onboarded company misses their first pay date, Gusto will automatically adjust the pay schedule to the next available pay date.

        ### Webhooks
        - `pay_schedule.updated`: Fires when a pay schedule is successfully updated.

        ### Related guides
        - [Create a pay schedule](doc:create-a-pay-schedule)
        - [Manage Pay Schedules via API](doc:manage-pay-schedules-api)

        scope: `pay_schedules:write`
      tags:
        - Pay Schedules
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Pay-Schedule-Show"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Pay-Schedule-Update-Request"
        required: true
      x-speakeasy-group: paySchedules
      x-speakeasy-name-override: update
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `pay_schedules:write`
      tags:
        - Pay Schedules
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Pay-Schedule-Assignment-Preview"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Pay-Schedule-Assignment-Body"
        required: true
      x-speakeasy-group: paySchedules
      x-speakeasy-name-override: previewAssignment
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.
        For `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).

        scope: `pay_schedules:write`
      tags:
        - Pay Schedules
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: No Content
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Pay-Schedule-Assignment-Body"
        required: true
      x-speakeasy-group: paySchedules
      x-speakeasy-name-override: assign
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `pay_schedules:read`
      tags:
        - Pay Schedules
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Pay-Schedule-Assignment"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: paySchedules
      x-speakeasy-name-override: getAssignments
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Results are returned in reverse chronological order (newest first).

        scope: `pay_stubs:read`
      x-gusto-integration-type:
        - embedded
      tags:
        - Payrolls
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Pay-Stubs-List"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getPayStubs
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `pay_stubs:read`
      tags:
        - Payrolls
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getPayStub
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `partner_disbursements:read`
      tags:
        - Payrolls
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Payroll-Partner-Disbursements"
        '404':
          description: Not Found
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `partner_disbursements:write`
      tags:
        - Payrolls
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Payroll-Partner-Disbursements"
        '422':
          description: mixed single and multiple errors example
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. 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\U0001F4D8 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:
              schema:
                "$ref": "#/components/schemas/Payroll-Batch"
        '409':
          description: conflict - idempotency key already used by this partner
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Payroll-Batch-Conflict-Error"
        '422':
          description: unprocessable entity - validation errors
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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\U0001F4D8 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:
              schema:
                "$ref": "#/components/schemas/Payroll-Batch-Results"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '410':
          description: Gone - results have expired from Redis
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. 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\U0001F4D8 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:
              schema:
                "$ref": "#/components/schemas/Payroll-Digest"
        '409':
          description: conflict - idempotency key already used by this partner
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Payroll-Digest-Conflict-Error"
        '422':
          description: unprocessable entity - validation errors
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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\U0001F4D8 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:
              schema:
                "$ref": "#/components/schemas/Payroll-Digest-Results"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '410':
          description: Gone - results have expired from Redis
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `payrolls:read`
      tags:
        - Payrolls
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Payroll-Reversal-List"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getApprovedReversals
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Results are paginated, with a maximum page size of 100 employee_compensations.

        Notes:
        * Hour and dollar amounts are returned as string representations of numeric decimals.
        * Hours are represented to the thousands place; dollar amounts are represented to the cent.
        * Every eligible compensation is returned for each employee. If no data has yet be inserted for a given field, it defaults to "0.00" (for fixed amounts) or "0.000" (for hours ).
        * When include parameter with benefits value is passed, employee_benefits:read scope is required to return benefits
          * Benefits containing PHI are only visible with the `employee_benefits:read:phi` scope

        scope: `payrolls:read`
      tags:
        - Payrolls
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful with wait_for_reverse_wire credit blocker
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Payroll-Show"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: get
    put:
      summary: Update a payroll by ID
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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**
        payroll object as a template of fields that you can update.  You cannot modify the structure of the payroll object through this endpoint, only values
        of the fields included in the payroll.  If you do not include specific employee compensations, fixed/hourly compensations, or deductions in your request body, they
        will 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
        inputted will be returned.

        scope: `payrolls:write`
      tags:
        - Payrolls
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Payroll-Prepared"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '409':
          description: Conflict (lock contention)
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Conflict-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Payroll-Update"
        required: true
      x-speakeasy-name-override: update
    delete:
      summary: Delete a payroll
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        By default the payroll and associated data is deleted synchronously. To request an asynchronous delete, use the `async=true` query parameter. In both cases validation of ability to delete will be performed and an Unprocessable Entity error will be returned if the payroll is not able to be deleted. A successful synchronous delete will return `204/No Content`. When a payroll has been enqueued for asynchronous deletion, `202/Accepted` will be returned.

        scope: `payrolls:run`
      tags:
        - Payrolls
      x-gusto-integration-type:
        - embedded
      responses:
        '204':
          description: no content
        '202':
          description: Accepted
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: delete
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        By default, will return processed, regular payrolls for the past 6 months.

        Notes:
        * Dollar amounts are returned as string representations of numeric decimals, are represented to the cent.
        * end_date can be at most 3 months in the future and start_date and end_date can't be more than 1 year apart.
        * Results are paginated. Maximum page size is 100 payrolls per request; the default page size is 25.

        scope: `payrolls:read`
      tags:
        - Payrolls
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Payroll-List"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: list
    post:
      summary: Create an off-cycle payroll
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ## `off_cycle_reason`
        By default:
        - External benefits and deductions will be included when the `off_cycle_reason` is set to `Correction`.
        - All benefits and deductions are blocked when the `off_cycle_reason` is set to `Bonus`.

        These elections can be overridden with the `skip_regular_deductions` boolean.

        scope: `payrolls:run`
      tags:
        - Payrolls
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Payroll-Unprocessed"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-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.
                  type:
                    - array
                    - 'null'
                  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
      x-speakeasy-name-override: createOffCycle
  "/v1/payrolls/{payroll_uuid}/receipt":
    get:
      summary: Get a single payroll receipt
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Notes:
        * Hour and dollar amounts are returned as string representations of numeric decimals.
        * Dollar amounts are represented to the cent.
        * If no data has yet be inserted for a given field, it defaults to "0.00" (for fixed amounts).
        * Pagination is optional. Supplying `page` and/or `per` returns only the requested page of employee compensations and includes the `X-Page`, `X-Total-Count`, `X-Total-Pages`, and `X-Per-Page` response headers. Without either parameter, all employee compensations are returned without pagination headers.
        * Maximum page size is 100 employee compensations per request.

        scope: `payrolls:read`
      tags:
        - Payrolls
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Payroll-Receipt"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getReceipt
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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:

        - `processed` is `true`
        - Current time is earlier than 4pm PT on the `payroll_deadline`

        scope: `payrolls:run`
      tags:
        - Payrolls
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessed-Payroll"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-name-override: cancel
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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 eligible employees to off-cycle payrolls that support multiple employees (`Bonus`, `Correction`, and `Adhoc`),
        and updating `check_date`, `payroll_deadline`, and `payroll_status_meta` dates and times.

        Use this endpoint before calling [PUT /v1/companies/{company_id}/payrolls/{payroll_id}](ref:put-v1-companies-company_id-payrolls).

        ### Notes

        * Nullifies `calculated_at` and `totals` if the payroll was previously calculated
        * Returns the `version` parameter required for [updating the payroll](ref:put-v1-companies-company_id-payrolls)
        * `employees:read` scope is required to include employee compensations data in the response.
        * Results are paginated, with a maximum page size of 100 employee compensations.

        scope: `payrolls:write employees:read`
      tags:
        - Payrolls
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Payroll-Prepared"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                employee_uuids:
                  type:
                    - array
                    - 'null'
                  description: |-
                    The employees to prepare, identified by UUID. If omitted, every employee currently on the payroll is prepared.

                    **Off-cycle payrolls that support multiple employees (`Bonus`, `Correction`, `Adhoc`):** passing `employee_uuids` also adds eligible employees who aren't yet on the payroll - a listed employee not on the payroll is added, while one already on it is simply prepared. A request may include up to 100 UUIDs, of which at most 25 may be employees not already on the payroll; an ineligible or unknown UUID, or more than 25 new employees, is rejected with a 422.

                    **All other payrolls:** `employee_uuids` selects which of the payroll's existing employees to prepare; a UUID for an employee not on the payroll is rejected with a 422.
                  items:
                    type: string
      x-speakeasy-name-override: prepare
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        This calculation is asynchronous and a successful request responds with a 202 HTTP status. To view the details of the calculated payroll, use the GET /v1/companies/{company_id}/payrolls/{payroll_id} endpoint with *include=taxes,benefits,deductions* params.

        If the company is blocked from running payroll due to issues like incomplete setup, missing information or other compliance issues, the response will be 422 Unprocessable Entity with a categorization of the blockers as described in the error responses.

        scope: `payrolls:run`
      tags:
        - Payrolls
      x-gusto-integration-type:
        - embedded
      responses:
        '202':
          description: Accepted
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-name-override: calculate
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `payrolls:run`
      tags:
        - Payrolls
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Payroll-Blocker"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getBlockers
  "/v1/companies/{company_uuid}/payrolls/skip":
    post:
      summary: Skip a payroll
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        If the company is blocked from running payroll due to issues like incomplete setup, missing information or other compliance issues, the response will be 422 Unprocessable Entity with a categorization of the blockers as described in the error responses.

        scope: `payrolls:run`
      tags:
        - Payrolls
      x-gusto-integration-type:
        - embedded
      responses:
        '202':
          description: Accepted
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Payroll-Blockers-Error"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Conflict-Error-Object"
      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.
                pay_schedule_uuid:
                  type: string
                  description: The UUID of the pay schedule
                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
      x-speakeasy-name-override: skip
  "/v1/companies/{company_id}/payrolls/{payroll_id}/submit":
    put:
      summary: Submit payroll
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        You should poll to ensure that payroll is processed successfully, as async errors only occur after async processing is complete.

        If the company is blocked from running payroll due to issues like incomplete setup, missing information or other compliance issues, the response will be 422 Unprocessable Entity with a categorization of the blockers as described in the error responses.

        scope: `payrolls:run`
      tags:
        - Payrolls
      x-gusto-integration-type:
        - embedded
      responses:
        '202':
          description: Accepted
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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"
      x-speakeasy-name-override: submit
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        The gross up amount must then be mapped to the corresponding fixed compensation earning type to get the correct payroll amount. For example, for bonus off-cycles, the gross up amount should be set with the Bonus earning type in the payroll `fixed_compensations` field.

        scope: `payrolls:run`
      tags:
        - Payrolls
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Payroll-Gross-Up-Response"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Payroll-Gross-Up-Request"
        required: true
      x-speakeasy-name-override: calculateGrossUp
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Factors affecting the accrued hours:

        - the time off policy accrual method (whether they get pay per hour worked, per hour paid, with / without overtime, accumulate time off based on pay period / calendar year / anniversary)
        - how many hours of work during this pay period
        - how many hours of PTO / sick hours taken during this pay period (for per hour paid policies only)
        - company pay schedule frequency (for per pay period)

        If none of the parameters is passed in, the accrued time off hour will be 0.

        scope: `payrolls:read`
      tags:
        - Time Off Policies
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Payroll-Calculate-Accruing-Time-Off-Hours-Response"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Payroll-Calculate-Accruing-Time-Off-Hours-Request"
      x-speakeasy-group: timeOffPolicies
      x-speakeasy-name-override: calculateAccruingTimeOffHours
  "/v1/companies/{company_id}/people_batches":
    post:
      summary: Create a people batch
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        The batch is processed asynchronously. Use the returned batch UUID to poll for status and results.

        scope: `people_batches:write`
      tags:
        - People Batches
      x-gusto-integration-type:
        - embedded
      responses:
        '201':
          description: created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/People-Batch"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '409':
          description: conflict - idempotency key already used
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/People-Batch-Conflict-Error"
        '422':
          description: unprocessable entity - validation errors
          content:
            application/json:
              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`.
                          If 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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Poll this endpoint to check the batch processing status and retrieve results.

        scope: `people_batches:read`
      tags:
        - People Batches
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/People-Batch-Results"
        '404':
          description: Not Found
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. 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> \U0001F4D8\n> To create a token please use the [plaid api](https://plaid.com/docs/api/processors/#processortokencreate) and select \"gusto\" as processor.\n\n> \U0001F6A7 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:
              schema:
                "$ref": "#/components/schemas/Company-Bank-Account"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Plaid-Processor-Token-Request"
        required: true
      x-speakeasy-group: bankAccounts
      x-speakeasy-name-override: createFromPlaidToken
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `recovery_cases:read`
      tags:
        - Recovery Cases
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Recovery-Case"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: recoveryCases
      x-speakeasy-name-override: get
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        It may take up to four business days for the ACH debit to process; in the meantime, the status of the recovery case will be in the `initiated_redebit` state. When funds are successfully redebited, the recovery case is transitioned to the `recovered` state.

        If the company has exceeded maximum redebit attempts, or if the recovery case is not in a redebitable state, the response will be 422 Unprocessable Entity.

        scope: `recovery_cases:write`
      tags:
        - Recovery Cases
      x-gusto-integration-type:
        - embedded
      responses:
        '202':
          description: Accepted
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-group: recoveryCases
      x-speakeasy-name-override: redebit
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `reimbursements:read`
      tags:
        - Reimbursements
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Recurring-Reimbursement-List"
        '404':
          description: Not Found
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `reimbursements:write`
      tags:
        - Reimbursements
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '201':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Recurring-Reimbursement"
        '422':
          description: invalid attributes
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '404':
          description: Not Found
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `reimbursements:read`
      tags:
        - Reimbursements
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Recurring-Reimbursement"
        '404':
          description: Not Found
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `reimbursements:write`
      tags:
        - Reimbursements
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Recurring-Reimbursement"
        '409':
          description: invalid version
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: invalid attributes
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '404':
          description: Not Found
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `reimbursements:write`
      tags:
        - Reimbursements
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '204':
          description: successful
        '404':
          description: Not Found
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `company_reports:write`
      tags:
        - Reports
      x-gusto-integration-type:
        - embedded
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Create-Report"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Create-Report-Body"
        required: true
      x-speakeasy-name-override: createCustom
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Use 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.

        scope: `company_reports:write`
      tags:
        - Reports
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/General-Ledger-Report"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Reports containing PHI are inaccessible with `company_reports:read:tier_2_only` data scope

        scope: `company_reports:read`
      tags:
        - Reports
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Report"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `company_reports:write`
      tags:
        - Reports
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Report-Template"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-name-override: getTemplate
  "/v1/companies/{company_uuid}/reverse_wire_transactions":
    get:
      summary: Get all reverse wire transactions for a company
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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: payroll_uuid
          in: query
          required: false
          description: Filter results to reverse wires associated with a specific 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-reverse-wire-transactions
      security:
        - CompanyAccessAuth: []
      description: |-
        Returns a paginated list of reverse wire (drawdown) transactions for a company. Reverse wires are debit transactions initiated by Gusto to pull funds from a partner's bank account to cover payroll or contractor payment obligations. Pagination is returned via the `x-page`, `x-per-page`, `x-total-count`, and `x-total-pages` response headers.

        scope: `reverse_wire_transactions:read`
      tags:
        - Reverse Wire Transactions
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Example response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Reverse-Wire-Transaction-List"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        A salary estimate must include:
        - Annual net revenue of the business
        - ZIP code for location-based salary data
        - One or more occupations with experience levels and time percentages (must sum to 100%)

        Only 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.

        scope: `salary_estimates:write`
      tags:
        - Salary Estimates
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '201':
          description: successfully created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Salary-Estimate"
        '422':
          description: unprocessable entity - invalid parameters
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `salary_estimates:read`
      tags:
        - Salary Estimates
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Salary-Estimate"
        '404':
          description: Not Found
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        The salary estimate must not be finalized (accepted). Once accepted, salary estimates become read-only for record-keeping purposes.

        scope: `salary_estimates:write`
      tags:
        - Salary Estimates
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Salary-Estimate"
        '422':
          description: unprocessable entity - already finalized
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Once 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.

        scope: `salary_estimates:write`
      tags:
        - Salary Estimates
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Salary-Estimate"
        '422':
          description: unprocessable entity - invalid employee job
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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\U0001F4D8 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:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/BLS-Occupation"
        '422':
          description: unprocessable entity - search term too short
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. 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: "> \U0001F6A7 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:
              schema:
                "$ref": "#/components/schemas/Form"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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.

'
              required:
                - employee_id
        required: true
      x-speakeasy-group: employeeForms
      x-speakeasy-name-override: generateW2
  "/v1/sandbox/generate_1099":
    post:
      summary: Generate a 1099 form [DEMO]
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. 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: "> \U0001F6A7 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:
              schema:
                "$ref": "#/components/schemas/Form_1099"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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.

'
              required:
                - contractor_id
        required: true
      x-speakeasy-group: contractorForms
      x-speakeasy-name-override: generate1099
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ## Related guides
        - [Signatory Events](doc:signatory-events)

        scope: `signatories:read`
      tags:
        - Signatories
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Signatory"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: list
    post:
      summary: Create a signatory
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        A 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.

        ### Webhooks
        - `signatory.created`: Fires when a signatory is successfully created.

        ### Related guides
        - [Signatory Events](doc:signatory-events)

        scope: `signatories:manage`
      tags:
        - Signatories
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Signatory"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Signatory-Create-Request"
        required: true
      x-speakeasy-name-override: create
  "/v1/companies/{company_uuid}/signatories/invite":
    post:
      summary: Invite a signatory
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ## Related guides
        - [Signatory Events](doc:signatory-events)

        scope: `signatories:manage`
      tags:
        - Signatories
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Signatory"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Signatory-Invite-Request"
        required: true
      x-speakeasy-name-override: invite
  "/v1/companies/{company_uuid}/signatories/{signatory_uuid}":
    put:
      summary: Update a signatory
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ## Related guides
        - [Signatory Events](doc:signatory-events)

        scope: `signatories:write`
      tags:
        - Signatories
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Signatory"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Signatory-Update-Request"
        required: true
      x-speakeasy-name-override: update
    delete:
      summary: Delete a signatory
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        ## Related guides
        - [Signatory Events](doc:signatory-events)

        scope: `signatories:manage`
      tags:
        - Signatories
      x-gusto-integration-type:
        - embedded
      responses:
        '204':
          description: No Content
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: delete
  "/v1/companies/{company_uuid}/tax_payments":
    get:
      summary: Get all tax payments for a company
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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: jurisdiction
          in: query
          required: false
          explode: false
          schema:
            type: array
            items:
              type: string
          description: Filter by tax jurisdiction. Accepts one or more two-letter state codes, or `US` for federal, as a comma-separated list (e.g. `IL,CA`). Codes are case-insensitive.
        - name: payroll_uuids
          in: query
          required: false
          explode: false
          schema:
            type: array
            items:
              type: string
          description: Filter to tax payments associated with one or more payrolls, given as a comma-separated list of payroll UUIDs.
        - name: due_date_from
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Lower-bound (inclusive) date filter on due_date.
        - name: due_date_to
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Upper-bound (inclusive) date filter on due_date.
        - name: payment_sent_on_from
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Lower-bound (inclusive) date filter on payment_sent_on.
        - name: payment_sent_on_to
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Upper-bound (inclusive) date filter on payment_sent_on.
        - name: period_start_from
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Lower-bound (inclusive) date filter on period_start.
        - name: period_start_to
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Upper-bound (inclusive) date filter on period_start.
        - name: period_end_from
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Lower-bound (inclusive) date filter on period_end.
        - name: period_end_to
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Upper-bound (inclusive) date filter on period_end.
        - name: amount_min
          in: query
          required: false
          schema:
            type: number
            format: float
          description: Lower-bound (inclusive) filter on amount.
        - name: amount_max
          in: query
          required: false
          schema:
            type: number
            format: float
          description: Upper-bound (inclusive) filter on amount.
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
            pattern: "^(amount|due_date|payment_sent_on|period_end|period_start)(:(asc|desc))?(,(amount|due_date|payment_sent_on|period_end|period_start)(:(asc|desc))?)*$"
            example: amount:asc
          description: 'Sort by one or more fields. Options: amount, due_date, payment_sent_on, period_end, period_start. Append `:asc` or `:desc` to specify direction (e.g., `amount: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-tax-payments
      security:
        - CompanyAccessAuth: []
      description: |-
        Fetches all tax payments Gusto has made (or scheduled) to tax agencies on behalf of a company.

        scope: `tax_payments:read`
      tags:
        - Tax Payments
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Tax-Payment-List"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
  "/v1/companies/{company_uuid}/tax_payments/{uuid}":
    get:
      summary: Get a tax payment for a company
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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: uuid
          in: path
          required: true
          description: The UUID of the tax payment
          schema:
            type: string
      x-gusto-rswag: true
      operationId: get-tax-payment
      security:
        - CompanyAccessAuth: []
      description: |-
        Fetches a single tax payment by UUID, including the payroll tax liabilities that make up the payment.

        scope: `tax_payments:read`
      tags:
        - Tax Payments
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Tax-Payment"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Note that some states require employees to receive their final wages within 24 hours (unless they consent otherwise,) in which case running a one-off payroll may be the only option.

        scope: `employments:read`
      tags:
        - Employee Employments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Termination"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: employeeEmployments
      x-speakeasy-name-override: getTerminations
    post:
      summary: Create an employee termination
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Note that some states require employees to receive their final wages within 24 hours (unless they consent otherwise,) in which case running a one-off payroll may be the only option.

        scope: `employments:write`
      tags:
        - Employee Employments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Termination"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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
      x-speakeasy-name-override: createTermination
      x-speakeasy-group: employeeEmployments
    delete:
      summary: Delete an employee termination
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employments:write`
      tags:
        - Employee Employments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '204':
          description: No Content
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-group: employeeEmployments
      x-speakeasy-name-override: deleteTermination
  "/v1/terminations/{employee_id}":
    get:
      summary: Get an employee termination
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Note that some states require employees to receive their final wages within 24 hours (unless they consent otherwise,) in which case running a one-off payroll may be the only option.

        scope: `employments:read`
      tags:
        - Employee Employments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Termination"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Note that some states require employees to receive their final wages within 24 hours (unless they consent otherwise,) in which case running a one-off payroll may be the only option.

        scope: `employments:write`
      tags:
        - Employee Employments
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Termination"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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
      x-speakeasy-group: employeeEmployments
      x-speakeasy-name-override: updateTermination
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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).
        The request is always created with approved status.

        scope: `time_off_requests:manage`
      tags:
        - Time Off Requests
      x-gusto-integration-type:
        - embedded
      responses:
        '201':
          description: created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Embedded-Time-Off-Request"
        '404':
          description: Not Found
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `time_off_requests:read`
      tags:
        - Time Off Requests
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Embedded-Time-Off-Balance"
        '404':
          description: Not Found
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Possible statuses:
        - `pending` — awaiting approval
        - `approved` — approved by an admin but not yet processed in a payroll
        - `declined` — declined by an admin
        - `consumed` — processed in a completed payroll

        Allowed values for `status`: pending, approved, declined, consumed.

        scope: `time_off_requests:read`
      tags:
        - Time Off Requests
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Embedded-Time-Off-Request"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
    post:
      summary: Create a time off request
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `time_off_requests:write`
      tags:
        - Time Off Requests
      x-gusto-integration-type:
        - embedded
      responses:
        '201':
          description: created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Embedded-Time-Off-Request"
        '404':
          description: Not Found
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `time_off_requests:read`
      tags:
        - Time Off Requests
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Embedded-Time-Off-Request-Preview"
        '404':
          description: Not Found
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `time_off_requests:read`
      tags:
        - Time Off Requests
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Embedded-Time-Off-Request"
        '404':
          description: Not Found
          content:
            application/json:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `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:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        Only 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.

        scope: `time_off_requests:manage`
      tags:
        - Time Off Requests
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Embedded-Time-Off-Request"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `time_off_requests:manage`
      tags:
        - Time Off Requests
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Embedded-Time-Off-Request"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `time_off_policies:read`
      tags:
        - Time Off Policies
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Time-Off-Policy"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: timeOffPolicies
      x-speakeasy-name-override: getAll
    post:
      summary: Create a time off policy
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `time_off_policies:write`
      tags:
        - Time Off Policies
      x-gusto-integration-type:
        - embedded
      responses:
        '201':
          description: created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Time-Off-Policy"
        '422':
          description: Policy name required
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Time-Off-Policy-Request"
        required: true
      x-speakeasy-name-override: create
      x-speakeasy-group: timeOffPolicies
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `time_off_policies:read`
      tags:
        - Time Off Policies
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Time-Off-Policy"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: timeOffPolicies
      x-speakeasy-name-override: get
    put:
      summary: Update a time off policy
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `time_off_policies:write`
      tags:
        - Time Off Policies
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Time-Off-Policy"
        '422':
          description: Unlimited Policy updated with accrual rate
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - "$ref": "#/components/schemas/Versionable-Required"
                - "$ref": "#/components/schemas/Time-Off-Policy-Update-Request"
        required: true
      x-speakeasy-group: timeOffPolicies
      x-speakeasy-name-override: update
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `time_off_policies:write`
      tags:
        - Time Off Policies
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Time-Off-Policy"
        '422':
          description: Policy has pending time off requests
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: timeOffPolicies
      x-speakeasy-name-override: deactivate
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `time_off_policies:write`
      tags:
        - Time Off Policies
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Time-Off-Policy"
        '422':
          description: Add employees with no employees
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-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
      x-speakeasy-group: timeOffPolicies
      x-speakeasy-name-override: addEmployees
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `time_off_policies:write`
      tags:
        - Time Off Policies
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Time-Off-Policy"
        '422':
          description: Remove employees with no employees
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-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
      x-speakeasy-group: timeOffPolicies
      x-speakeasy-name-override: removeEmployees
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `time_off_policies:write`
      tags:
        - Time Off Policies
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Time-Off-Policy"
        '422':
          description: Unlimited policy balance update
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-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
      x-speakeasy-group: timeOffPolicies
      x-speakeasy-name-override: updateBalance
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. 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:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. 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:
        * Resource (company, employee, contractor, or application) and resource owner
        * Access level
      tags:
        - Introspection
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Token-Info"
      x-speakeasy-name-override: getInfo
  "/v1/webhook_subscriptions":
    get:
      summary: List webhook subscriptions
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. 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\U0001F4D8 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:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Webhook-Subscription"
      x-speakeasy-name-override: listSubscriptions
    post:
      summary: Create a webhook subscription
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. 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\U0001F4D8 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:
              schema:
                "$ref": "#/components/schemas/Webhook-Subscription"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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
      x-speakeasy-name-override: createSubscription
  "/v1/webhook_subscriptions/{webhook_subscription_uuid}":
    get:
      summary: Get a webhook subscription
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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\U0001F4D8 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:
              schema:
                "$ref": "#/components/schemas/Webhook-Subscription"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: getSubscription
    put:
      summary: Update a webhook subscription
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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\U0001F4D8 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:
              schema:
                "$ref": "#/components/schemas/Webhook-Subscription"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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
      x-speakeasy-name-override: updateSubscription
    delete:
      summary: Delete a webhook subscription
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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\U0001F4D8 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

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: deleteSubscription
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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\U0001F4D8 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:
              schema:
                "$ref": "#/components/schemas/Webhook-Verification-Token-Response"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-name-override: requestVerificationToken
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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\U0001F4D8 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:
              schema:
                "$ref": "#/components/schemas/Webhook-Subscription"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      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
      x-speakeasy-name-override: verify
  "/v1/webhooks/health_check":
    get:
      summary: Get the webhooks health status
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. 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\U0001F4D8 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:
              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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `payrolls:read`
      tags:
        - Wire In Requests
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Wire-In-Request"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: wireInRequests
      x-speakeasy-name-override: get
    put:
      summary: Submit a wire in request
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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

        scope: `payrolls:run`
      tags:
        - Wire In Requests
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Wire-In-Request"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Wire-In-Request-Update-Request-Body"
        required: true
      x-speakeasy-group: wireInRequests
      x-speakeasy-name-override: submit
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `payrolls:read`
      tags:
        - Wire In Requests
      x-gusto-integration-type:
        - embedded
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Wire-In-Request-List"
      x-speakeasy-group: wireInRequests
      x-speakeasy-name-override: 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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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
        date and a boolean signifying if it is the currently active work address.

        scope: `employees:read`
      tags:
        - Employee Addresses
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: List of employee work addresses
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Work-Addresses-List"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: employeeAddresses
      x-speakeasy-name-override: getWorkAddresses
    post:
      summary: Create an employee work address
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employees:manage`
      tags:
        - Employee Addresses
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '201':
          description: created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Work-Address"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: unprocessable entity
          content:
            application/json:
              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
      x-speakeasy-group: employeeAddresses
      x-speakeasy-name-override: createWorkAddress
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employees:read`
      tags:
        - Employee Addresses
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Work-Address"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: employeeAddresses
      x-speakeasy-name-override: retrieveWorkAddress
    put:
      summary: Update an employee work address
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employees:manage`
      tags:
        - Employee Addresses
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Employee-Work-Address"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: unprocessable entity
          content:
            application/json:
              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
      x-speakeasy-group: employeeAddresses
      x-speakeasy-name-override: updateWorkAddress
    delete:
      summary: Delete an employee's work address
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        scope: `employees:manage`
      tags:
        - Employee Addresses
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '204':
          description: no content
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: unprocessable entity
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      x-speakeasy-group: employeeAddresses
      x-speakeasy-name-override: deleteWorkAddress
  "/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:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.
        Returns benefit amounts for the requested tax year (defaults to current year if not specified).

        This endpoint only supports retrieving outside contributions for 401(k) benefits.

        scope: `employee_benefits:read`
      tags:
        - Employee Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Ytd-Benefit-Amounts-From-Different-Company"
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
      x-speakeasy-group: employeeBenefits
      x-speakeasy-name-override: getYtdBenefitAmountsFromDifferentCompany
    post:
      summary: Create year-to-date benefit amounts from a different company
      parameters:
        - name: X-Gusto-API-Version
          in: header
          schema:
            type: string
            enum:
              - '2025-06-15'
            default: '2025-06-15'
          description: Determines the date-based API version associated with your API call. If 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.

        This endpoint only supports passing outside contributions for 401(k) benefits.

        scope: `employee_benefits:write`
      tags:
        - Employee Benefits
      x-gusto-integration-type:
        - embedded
        - app-integrations
      responses:
        '204':
          description: No Content
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Not-Found-Error-Object"
        '422':
          description: |
            Unprocessable Entity

            This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Ytd-Benefit-Amounts-From-Different-Company-Body"
        required: true
      x-speakeasy-group: employeeBenefits
      x-speakeasy-name-override: createYtdBenefitAmountsFromDifferentCompany
  "/v1/information_requests/{information_request_uuid}/submit":
    put:
      x-gusto-integration-type:
        - embedded
      summary: Submit information request responses
      tags:
        - Information Requests
      operationId: submit-information-request
      x-speakeasy-group: informationRequests
      x-speakeasy-name-override: submit
      description: |-
        Submit responses to an information request.
        Supports both text responses and file uploads (multipart/form-data).
        Maximum file size: 120MB.

        scope: `information_requests:write`
      parameters:
        - name: information_request_uuid
          in: path
          required: true
          schema:
            type: string
          description: The UUID of the information request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                required_questions:
                  type: array
                  items:
                    type: object
                    required:
                      - question_uuid
                      - response_type
                    properties:
                      question_uuid:
                        type: string
                        format: uuid
                        description: UUID of the question being answered
                      response_type:
                        type: string
                        enum:
                          - text
                          - document
                        description: Type of response - matches the question's response_type from GET
                      text_response:
                        type: string
                        description: Text response (required when response_type is text)
                      file_response:
                        type: string
                        description: Data URL with base64-encoded file (e.g., "data:image/png;base64,..."). Required when response_type is document.
                      file_name:
                        type: string
                        description: Original filename with extension (e.g., "document.pdf"). Used for document uploads.
      responses:
        '200':
          description: Information request successfully submitted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Information-Request"
        '422':
          description: Validation error - invalid responses or missing required answers
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object"
              examples:
                Basic:
                  value:
                    errors:
                      - error_key: base
                        category: payroll_blocker
                        message: Company must complete all onboarding requirements in order to run payroll.
                        metadata:
                          key: needs_onboarding
                Resource:
                  value:
                    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:
                  value:
                    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
        '404':
          description: |
            Not Found

            The requested resource does not exist. Make sure the provided UUID is valid.