Gusto App Integrations API

https://docs.gusto.com/app-integrations
Admin
Gusto App Integrations API enables developers to build payroll applications and integrations with...
Tokens:337,737
Snippets:1,268
Trust Score:9.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Provisioning Response Example

Source: https://docs.gusto.com/app-integrations/reference/post-v1-provision

Example JSON response containing the account claim URL for the user.

```json
{
  "account_claim_url": "https://app.gusto.com/claim_account/3456789"
}
```

--------------------------------

### Employee Address List Example

Source: https://docs.gusto.com/app-integrations/reference/get-v1-employees-employee_id-home_addresses

Example of a list of employee addresses.

```json
{
  "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
}
```

--------------------------------

### Department JSON Example

Source: https://docs.gusto.com/app-integrations/reference/get-department

Example JSON structure for a department resource.

```json
{
  "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"
    }
  ]
}
```

```json
{
  "uuid": "56260b3d-c375-415c-b77a-75d99f717193",
  "company_uuid": "7087a288-8349-4632-b92e-bc94fb79f29e",
  "title": "Stage Hand",
  "version": "d90440dd464601d1c8f4e9e240dfb7a6",
  "employees": [],
  "contractors": []
}
```

--------------------------------

### Provisioning Request Example

Source: https://docs.gusto.com/app-integrations/reference/post-v1-provision

Example JSON payload for provisioning a new company and primary payroll admin.

```json
{
  "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"
      }
    ]
  }
}
```

--------------------------------

### Get Contribution Exclusions Response Example

Source: https://docs.gusto.com/app-integrations/reference/get-v1-company_benefits-company_benefit_id-contribution_exclusions

Example of a successful response containing a list of contribution exclusions.

```json
[
  {
    "contribution_uuid": "60191999-004a-49d9-b163-630574433653",
    "contribution_type": "Commission",
    "excluded": false
  },
  {
    "contribution_uuid": "75a7a827-1f2d-4d6f-94f2-514c1fc32b13",
    "contribution_type": "Regular",
    "excluded": false
  },
  {
    "contribution_uuid": "eead3c7c-7964-4e3c-b609-670456127b09",
    "contribution_type": "Life insurance imputed benefit",
    "excluded": true
  }
]
```

--------------------------------

### Rehire Response Example

Source: https://docs.gusto.com/app-integrations/reference/post-v1-employees-employee_id-rehire

Example of the JSON structure returned upon successfully creating an employee rehire.

```json
{
            "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
          }
```

--------------------------------

### Job Object Example Payloads

Source: https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-employees

JSON examples representing primary and secondary job structures in Gusto.

```json
{
  "uuid": "d6d1035e-8a21-4e1d-89d5-fa894f9aff97",
  "version": "gr78930htutrz444kuytr3s5hgxykuveb523fwl8sir",
  "employee_uuid": "948daac8-4355-4ece-9e2a-229898accb22",
  "hire_date": "2020-01-20",
  "title": "Account Director",
  "primary": true,
  "rate": "78000.00",
  "payment_unit": "Year",
  "current_compensation_uuid": "ea8b0b90-1112-4f9d-bb93-bf029bc8537a",
  "two_percent_shareholder": false,
  "state_wc_covered": null,
  "state_wc_class_code": null,
  "compensations": [
    {
      "uuid": "ea8b0b90-1112-4f9d-bb93-bf029bc8537a",
      "version": "98jr3289h3298hr9329gf9egskt3tjaj",
      "job_uuid": "d6d1035e-8a21-4e1d-89d5-fa894f9aff97",
      "employee_uuid": "948daac8-4355-4ece-9e2a-229898accb22",
      "rate": "78000.00",
      "payment_unit": "Year",
      "flsa_status": "Exempt",
      "effective_date": "2020-01-20",
      "adjust_for_minimum_wage": false,
      "minimum_wages": []
    }
  ]
}
```

```json
{
  "uuid": "a1b2c3d4-5678-9012-abcd-ef1234567890",
  "version": "hj29fh3298hf9832hf98h32f89h32f89h32f9832",
  "employee_uuid": "948daac8-4355-4ece-9e2a-229898accb22",
  "hire_date": "2020-01-20",
  "title": "Senior Consultant",
  "primary": false,
  "rate": "25.00",
  "payment_unit": "Hour",
  "current_compensation_uuid": "b2c3d4e5-6789-0123-bcde-f12345678901",
  "two_percent_shareholder": false,
  "state_wc_covered": null,
  "state_wc_class_code": null,
  "compensations": [
    {
      "uuid": "b2c3d4e5-6789-0123-bcde-f12345678901",
      "version": "93jr2398h23r9832rg9832rg98ewrg98e",
      "job_uuid": "a1b2c3d4-5678-9012-abcd-ef1234567890",
      "employee_uuid": "948daac8-4355-4ece-9e2a-229898accb22",
      "rate": "25.00",
      "payment_unit": "Hour",
      "flsa_status": "Nonexempt",
      "effective_date": "2020-01-20",
      "adjust_for_minimum_wage": false,
      "minimum_wages": []
    }
  ]
}
```

--------------------------------

### Garnishment Data Examples

Source: https://docs.gusto.com/app-integrations/reference/post-v1-employees-employee_id-garnishments

Examples of individual garnishment objects and a list of garnishments.

```json
{
  "uuid": "4c7841a2-1363-497e-bc0f-664703c7484f",
  "version": "52b7c567242cb7452e89ba2bc02cb476",
  "employee_uuid": "a6b53294-f871-4db2-bbd4-8c3d1fe56440",
  "active": true,
  "amount": "8.00",
  "description": "Company loan to employee",
  "court_ordered": false,
  "times": 5,
  "recurring": false,
  "annual_maximum": null,
  "total_amount": null,
  "pay_period_maximum": "100.00",
  "deduct_as_percentage": true,
  "garnishment_type": null,
  "child_support": null
}
```

```json
{
  "uuid": "4c7841a2-1363-497e-bc0f-664703c7484f",
  "version": "52b7c567242cb7452e89ba2bc02cb476",
  "employee_uuid": "a6b53294-f871-4db2-bbd4-8c3d1fe56440",
  "active": true,
  "amount": "150.00",
  "description": "Back taxes",
  "court_ordered": true,
  "times": null,
  "recurring": true,
  "annual_maximum": null,
  "total_amount": null,
  "pay_period_maximum": null,
  "deduct_as_percentage": false,
  "garnishment_type": null,
  "child_support": null
}
```

```json
{
  "uuid": "4c7841a2-1363-497e-bc0f-664703c7481a",
  "version": "52b7c567242cb7452e89ba2bc02cb383",
  "employee_uuid": "a6b53294-f871-4db2-bbd4-8c3d1fe56440",
  "active": true,
  "amount": "40.00",
  "description": "Child support - AZ28319",
  "court_ordered": true,
  "times": null,
  "recurring": true,
  "annual_maximum": null,
  "total_amount": null,
  "pay_period_maximum": "400.00",
  "deduct_as_percentage": true,
  "garnishment_type": "child_support",
  "child_support": {
    "state": "AZ",
    "payment_period": "Monthly",
    "case_number": "AZ28319",
    "order_number": null,
    "remittance_number": null,
    "fips_code": "04000"
  }
}
```

```json
[
  {
    "uuid": "4c7841a2-1363-497e-bc0f-664703c7484f",
    "version": "52b7c567242cb7452e89ba2bc02cb476",
    "employee_uuid": "a6b53294-f871-4db2-bbd4-8c3d1fe56440",
    "active": true,
    "amount": "8.00",
    "description": "Company loan to employee",
    "court_ordered": false,
    "times": 5,
    "recurring": false,
    "annual_maximum": null,
    "total_amount": null,
    "pay_period_maximum": "100.00",
    "deduct_as_percentage": true,
    "garnishment_type": null,
    "child_support": null
  },
  {
    "uuid": "4c7841a2-1363-497e-bc0f-664703c7481a",
    "version": "52b7c567242cb7452e89ba2bc02cb383",
    "employee_uuid": "a6b53294-f871-4db2-bbd4-8c3d1fe56440",
    "active": true,
    "amount": "40.00",
    "description": "Child support - AZ28319",
    "court_ordered": true,
    "times": null,
    "recurring": true,
    "annual_maximum": null,
    "total_amount": null,
    "pay_period_maximum": "400.00",
    "deduct_as_percentage": true,
    "garnishment_type": "child_support",
    "child_support": {
      "state": "AZ",
      "payment_period": "Monthly",
      "case_number": "AZ28319"
    }
  }
]
```

--------------------------------

### Rehire Object Example

Source: https://docs.gusto.com/app-integrations/reference/post-v1-employees-employee_id-rehire

An example of the Rehire object structure returned by the API.

```json
{
  "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
}
```

--------------------------------

### Payroll Sync JSON Examples

Source: https://docs.gusto.com/app-integrations/reference/get-time_tracking-payroll_syncs-payroll_sync_uuid

Example JSON objects representing pending and completed payroll sync states.

```json
{
  "uuid": "123e4567-e89b-12d3-a456-426655440000",
  "company_uuid": "123e4567-e89b-12d3-a456-426655440001",
  "status": "pending",
  "kind": "regular",
  "pay_schedule_uuid": "123e4567-e89b-12d3-a456-426655440002",
  "pay_period_start_date": "2025-01-01",
  "pay_period_end_date": "2025-01-15",
  "submitted_at": "2025-01-16T12:00:00Z",
  "completed_at": null
}
```

```json
{
  "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"
}
```

--------------------------------

### Error and Deprecation Response Examples

Source: https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-locations

Examples of error responses for missing resources or deprecated endpoints.

```json
{
  "errors": [
    {
      "error_key": "request",
      "category": "not_found",
      "message": "The requested resource was not found."
    }
  ]
}
```

```json
{
  "errors": [
    {
      "error_key": "request",
      "category": "deprecated_endpoint",
      "message": "The requested endpoint is no longer supported in the requested API version. Use POST /v1/partner_managed_companies/:company_uuid/terms_of_service instead"
    }
  ]
}
```

```json
{
  "errors": [
    {
      "error_key": "request",
      "category": "deprecated_endpoint",
      "message": "The requested endpoint is no longer supported in the requested API version. Use PUT /v1/partner_managed_companies/:company_uuid/terms_of_service instead"
    }
  ]
}
```

--------------------------------

### Employee Work Address Success Example

Source: https://docs.gusto.com/app-integrations/reference/post-v1-employees-employee_id-work_addresses

Example JSON response for a successful employee work address creation.

```json
{
  "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"
}
```

--------------------------------

### Department List Example

Source: https://docs.gusto.com/app-integrations/reference/get-companies-departments

A JSON array example representing a collection of department objects returned by the API.

```json
"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"
      }
    ]
  }
]
```

--------------------------------

### Termination Request Example

Source: https://docs.gusto.com/app-integrations/reference/put-v1-terminations-employee_id

Example payload for updating an employee's termination status.

```json
{
  "version": "d487dd0b55dfcacdd920ccbdaeafa351",
  "effective_date": "2020-06-30",
  "run_termination_payroll": false
}
```

--------------------------------

### Employee Benefit JSON Examples

Source: https://docs.gusto.com/app-integrations/reference/get-v1-company_benefits-company_benefit_id-employee_benefits

Standard and tiered examples of an employee benefit object representation.

```json
{
  "version": "09j3d29jqdpj92109j9j2d90dq",
  "employee_uuid": "73274962-63ce-4e5c-b689-1df8d4df09f4",
  "company_benefit_uuid": "54e37c27-43e6-4ae5-a5b2-e29895a133be",
  "active": true,
  "uuid": "e91ca856-a915-4339-9b18-29f9cd66b031",
  "employee_deduction": "100.00",
  "company_contribution": "100.00",
  "employee_deduction_annual_maximum": "200.00",
  "company_contribution_annual_maximum": "200.00",
  "limit_option": null,
  "retirement_loan_identifier": null,
  "deduct_as_percentage": false,
  "contribute_as_percentage": false,
  "catch_up": false,
  "coverage_amount": null,
  "deduction_reduces_taxable_income": null,
  "coverage_salary_multiplier": "0.00",
  "contribution": {
    "type": "amount",
    "value": "100.00"
  },
  "elective": false,
  "effective_date": "2025-01-01",
  "expiration_date": null
}
```

```json
{
  "version": "09j3d29jqdpj92109j9j2d90dq",
  "employee_uuid": "73274962-63ce-4e5c-b689-1df8d4df09f4",
  "company_benefit_uuid": "54e37c27-43e6-4ae5-a5b2-e29895a133be",
  "active": true,
  "uuid": "e91ca856-a915-4339-9b18-29f9cd66b031",
  "employee_deduction": "100.00",
  "employee_deduction_annual_maximum": "200.00",
  "company_contribution_annual_maximum": "200.00",
  "limit_option": null,
  "deduct_as_percentage": false,
  "catch_up": false,
  "coverage_amount": null,
  "deduction_reduces_taxable_income": null,
  "coverage_salary_multiplier": "0.00",
  "elective": true,
  "contribution": {
    "type": "tiered",
    "value": {
      "tiers": [
        {
          "rate": "100.0",
          "threshold": "2.0",
          "threshold_delta": "2.0"
        },
        {
          "rate": "50.0",
          "threshold": "5.0",
          "threshold_delta": "3.0"
        }
      ]
    }
  },
  "effective_date": "2025-01-01",
  "expiration_date": null
}
```

--------------------------------

### Webhook Subscription Example

Source: https://docs.gusto.com/app-integrations/reference/put-v1-verify-webhook-subscription-uuid

A representation of a verified webhook subscription object.

```json
{
  "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"
  ]
}
```

--------------------------------

### Webhook Subscription Example Data

Source: https://docs.gusto.com/app-integrations/reference/get-v1-webhook-subscription-uuid

Example JSON objects representing verified and pending webhook subscription states.

```json
{
  "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"
  ]
}
```

```json
{
  "uuid": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "url": "https://partner-app.com/webhooks",
  "status": "pending",
  "subscription_types": [
    "Company",
    "Employee"
  ]
}
```

--------------------------------

### Rehire JSON Examples

Source: https://docs.gusto.com/app-integrations/reference/get-v1-employees-employee_id-rehire

Examples of rehire objects representing different states of an employee's rehire status.

```json
{
  "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
}
```

```json
{
  "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
}
```

```json
{
  "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
}
```

--------------------------------

### Token Info Response Example

Source: https://docs.gusto.com/app-integrations/reference/get-v1-me

Example JSON response body returned by the /v1/token_info endpoint for a company administrator token.

```json
{
  "scope": "companies:read public",
  "resource": {
    "type": "Company",
    "uuid": "7b1d0df1-6403-4a06-8768-c1dd7d24d27a"
  },
  "resource_owner": {
    "type": "CompanyAdmin",
    "uuid": "8fdc31f0-a8a7-4872-a9f1-dcb5e6f876e3"
  }
}
```

--------------------------------

### Not Found Error Response Example

Source: https://docs.gusto.com/app-integrations/reference/delete-v1-companies-company_id-earning_types-earning_type_uuid

Example of the JSON structure returned when the requested earning type UUID does not exist.

```json
{
  "$ref": "#/components/schemas/Not-Found-Error-Object/x-examples/not_found"
}
```

--------------------------------

### Pending Webhook Subscription Example

Source: https://docs.gusto.com/app-integrations/reference/put-v1-verify-webhook-subscription-uuid

A representation of a webhook subscription in a pending state.

```json
{
  "uuid": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "url": "https://partner-app.com/webhooks",
  "status": "pending",
  "subscription_types": [
    "Company",
    "Employee"
  ]
}
```

--------------------------------

### Webhook Subscription Error Response Examples

Source: https://docs.gusto.com/app-integrations/reference/put-v1-verify-webhook-subscription-uuid

Examples of error payloads returned when a webhook subscription verification fails or encounters business logic blockers.

```json
"error_key": "employee_uuids",
"category": "invalid_attribute_value",
"message": "Invalid Employee UUID(s).",
"metadata": {
  "entity_type": "Employee",
  "entity_uuid": "invalid-uuid-123"
}
}
```

```json
"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"
      }
    }
  ]
}
```

```json
"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"
      }
    }
  ]
}
```

```json
"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"
      }
    }
  ]
}
```

```json
"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"
      }
    }
  ]
}
```

```json
"payroll_blocker_suspended": {
  "errors": [
    {
      "error_key": "base",
      "category": "payroll_blocker",
      "message": "Company is suspended and cannot run payroll.",
      "metadata": {
        "key": "suspended"
      }
    }
  ]
}
```

```json
"submission_blocker_missing_selection": {
  "errors": [
    {
      "error_key": "submission_blockers",
      "category": "invalid_attribute_value",
      "message": "Submission blockers selections required"
    }
  ]
}
```

```json
"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"
        }
      ]
    }
  ]
}
```

```json
"invalid_version": {
  "errors": [
    {
      "error_key": "base",
      "category": "invalid_resource_version",
      "message": "You are attempting to update a resource using an out-of-date version."
    }
  ]
}
```

```json
"payroll_update_stale_employee_compensation_version": {
  "errors": [
    {
      "error_key": "base",
      "category": "invalid_resource_version",
      "message": "Supplied Version (stale-version) is invalid.",
      "metadata": {
        "entity_type": "Employee",
        "entity_uuid": "a8e9d2c6-1f3b-4d5a-9c8e-7f0b2d4c6e8a"
      }
    }
  ]
}
```

```json
"employee_create_self_onboarding_missing_email": {
  "errors": [
    {
      "error_key": "email",
      "category": "invalid_attribute_value",
      "message": "Email is required to invite the employee to self-onboard"
    }
  ]
}
```

```json
"employee_benefit_simple_ira_elective_mismatch": {
  "errors": [
    {
      "error_key": "elective",
      "category": "invalid_attribute_value",
      "message": "Elective must be true for matching Simple IRA benefits"
    }
  ]
}
```

```json
"signatory_email_required": {
  "errors": [
    {
      "error_key": "email",
      "category": "invalid_attribute_value",
    }
  ]
}
```

--------------------------------

### Compensation Object Examples

Source: https://docs.gusto.com/app-integrations/reference/put-v1-employees

JSON representations of compensation objects, including success status and hourly compensation configurations.

```json
{
            "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"
          }
```

```json
{
            "uuid": "e5f6a7b8-c9d0-1234-e5f6-a7b8c9d01234",
            "version": "98b7a6c5d4e3f2a1b0c9d8e7f6a5b4c3",
            "job_uuid": "d2e5f8a1-b4c7-4d90-a3e6-f9b2c5d8e1a4",
            "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": []
          }
```

--------------------------------

### Employee Compensation Data Structure

Source: https://docs.gusto.com/app-integrations/reference/put-v1-employees

Example JSON structure representing employee compensation details and minimum wage adjustments.

```json
"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"
              }
            ]
          }
        }
```

--------------------------------

### Employee Object Example

Source: https://docs.gusto.com/app-integrations/reference/put-v1-employees

A JSON representation of an employee record, including employment status, job details, and compensation information.

```json
{
  "uuid": "d7282d99-ab6b-42f5-ba45-f4a670e886a8",
  "first_name": "Boaty",
  "middle_initial": null,
  "last_name": "Koss",
  "email": "keena.feest@kiehn.co.uk",
  "company_uuid": "e904cc79-818a-4da8-9d37-0be0a86fdda8",
  "manager_uuid": null,
  "version": "a5cec1f1c0135feb3e76ca6ea3c46176",
  "current_employment_status": "full_time",
  "onboarding_status": "onboarding_completed",
  "preferred_first_name": null,
  "department_uuid": null,
  "employee_code": "46f036",
  "payment_method": "Direct Deposit",
  "department": null,
  "terminated": false,
  "two_percent_shareholder": false,
  "onboarded": true,
  "historical": false,
  "has_ssn": true,
  "onboarding_documents_config": {
    "uuid": null,
    "i9_document": false
  },
  "jobs": [
    {
      "uuid": "bc875f9d-adc5-40f6-99db-ed8470bda25f",
      "version": "863bcd01c51fcfa2468d604cffec7413",
      "employee_uuid": "d7282d99-ab6b-42f5-ba45-f4a670e886a8",
      "current_compensation_uuid": "2ec164d0-808b-446c-8120-8cfb500945d0",
      "payment_unit": "Year",
      "primary": true,
      "two_percent_shareholder": false,
      "state_wc_covered": null,
      "state_wc_class_code": null,
      "title": "",
      "compensations": [
        {
          "uuid": "2ec164d0-808b-446c-8120-8cfb500945d0",
          "employee_uuid": "d7282d99-ab6b-42f5-ba45-f4a670e886a8",
          "version": "db7bfb49a4f0893432cb562311bfcad9",
          "payment_unit": "Year",
          "flsa_status": "Exempt",
          "adjust_for_minimum_wage": false,
          "minimum_wages": [],
          "job_uuid": "bc875f9d-adc5-40f6-99db-ed8470bda25f",
          "effective_date": "2025-06-09",
          "rate": "80000.00"
        }
      ],
      "rate": "80000.00",
      "hire_date": "2024-06-09"
    }
  ],
  "eligible_paid_time_off": [],
  "terminations": [],
  "garnishments": [],
  "date_of_birth": "2005-06-09",
  "ssn": "",
  "phone": null,
  "work_email": null,
  "member_portal_invitation_status": {
    "status": "sent",
    "token_expired": false,
    "welcome_email_sent_at": "2024-01-15T14:30:00Z",
    "last_password_resent_at": null
  },
  "partner_portal_invitation_sent": true
}
```

--------------------------------

### Work Address API Error Response Examples

Source: https://docs.gusto.com/app-integrations/reference/put-v1-work_addresses-work_address_uuid

A collection of JSON error objects representing different validation and operational failures.

```json
{
                "error_key": "base",
                "category": "invalid_operation",
                "message": "This form does not allow preparer information"
              }
```

```json
{
          "invoice_period_invalid_format": {
            "errors": [
              {
                "error_key": "base",
                "category": "invalid_parameter",
                "message": "Invalid invoice_period param format, should be 'YYYY-MM'"
              }
            ]
          }
```

```json
{
          "invoice_period_future": {
            "errors": [
              {
                "error_key": "base",
                "category": "invalid_parameter",
                "message": "Invalid invoice_period param, cannot be a future invoice period"
              }
            ]
          }
```

```json
{
          "invoice_company_uuids_max_exceeded": {
            "errors": [
              {
                "error_key": "base",
                "category": "invalid_parameter",
                "message": "Invalid company_uuids passed, max of 50"
              }
            ]
          }
```

```json
{
          "wire_in_request_invalid_date_sent": {
            "errors": [
              {
                "error_key": "date_sent",
                "category": "invalid_attribute_value",
                "message": "Date sent must be a valid date"
              }
            ]
          }
```

```json
{
          "wire_in_request_missing_bank_name": {
            "errors": [
              {
                "error_key": "bank_name",
                "category": "invalid_attribute_value",
                "message": "Bank name must be present"
              }
            ]
          }
```

```json
{
          "wire_in_request_invalid_amount_sent": {
            "errors": [
              {
                "error_key": "amount_sent",
                "category": "invalid_attribute_value",
                "message": "Amount sent must be a number"
              }
            ]
          }
```

```json
{
          "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"
              }
            ]
          }
```

```json
{
          "wire_in_request_not_awaiting_funds": {
            "errors": [
              {
                "error_key": "base",
                "category": "invalid_operation",
                "message": "Wire in request status must be awaiting funds"
              }
            ]
          }
```

```json
{
          "external_payroll_missing_check_date": {
            "errors": [
              {
                "error_key": "check_date",
                "category": "invalid_attribute_value",
                "message": "Check date is required"
              }
            ]
          }
```

```json
{
          "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"
              }
            ]
          }
```

```json
{
          "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"
              }
            ]
          }
```

```json
{
          "external_payroll_invalid_payroll_item": {
            "errors": [
              {
                "error_key": "base",
                "category": "invalid_operation",
                "message": "Invalid payload or parameters"
              }
            ]
          }
```

```json
{
          "external_payrolls_locked": {
            "errors": [
              {
                "error_key": "base",
                "category": "invalid_operation",
                "message": "External Payrolls have already been finalized or a payroll has already been processed."
              }
            ]
          }
```

```json
{
          "employee_bank_account_destroy_invalid": {
            "errors": [
              {
                "error_key": "base",
                "category": "invalid_attribute_value",
                "message": "Cannot delete this bank account."
              }
            ]
          }
```

```json
{
          "external_payroll_invalid_liability_selection": {
            "errors": [
              {
                "error_key": "tax_id",
                "category": "invalid_attribute_value",
                "message": "Tax is required"
              }
            ]
          }
```

```json
{
          "invalid_tax_liability_selection": {
            "errors": [
              {
```
Tokens:
Raw