### Create Time Sheet Example Source: https://docs.gusto.com/app-integrations/reference/post-companies-company_uuid-time_tracking-time_sheets This example demonstrates how to create a time sheet with regular hours. Ensure the `company_uuid` is correctly set in the URL. ```json { "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 } ] } ``` -------------------------------- ### Example Create Garnishment Source: https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-employees An example of a garnishment object suitable for creation, demonstrating required fields and common values. ```APIDOC ## Example Create Garnishment ### Description This example illustrates the structure for creating a new garnishment, such as for back taxes. ### Request Example ```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 } ``` ``` -------------------------------- ### Cursor-based Pagination Example Source: https://docs.gusto.com/app-integrations/docs/pagination Use `starting_after_uuid` and `limit` parameters for cursor-based pagination, suitable for real-time data. This example fetches 5 records after a specific UUID. ```url https://api.gusto.com/v1/events?starting_after_uuid=10ac74e7-d6f0-46c0-9697-8ec77ab475ba&limit=5 ``` -------------------------------- ### Example Employee Benefit Response Source: https://docs.gusto.com/app-integrations/reference/post-v1-employees-employee_id-employee_benefits This is an example of a successful response when creating a standard employee benefit. ```json { "uuid": "e91ca856-a915-4339-9b18-29f9cd66b031", "employee_uuid": "73274962-63ce-4e5c-b689-1df8d4df09f4", "company_benefit_uuid": "54e37c27-43e6-4ae5-a5b2-e29895a133be", "active": true, "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 } ``` -------------------------------- ### Example Supported Benefit Object Source: https://docs.gusto.com/app-integrations/reference/get-v1-benefits-benefit_id This JSON object represents an example of a supported benefit, illustrating its properties and structure. ```json { "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" } ``` -------------------------------- ### OpenAPI Example for Employee Termination Source: https://docs.gusto.com/app-integrations/reference/put-v1-terminations-employee_id Provides an example of a valid employee termination request payload. It includes version, effective date, and a flag for running termination payroll. ```json { "version": "d487dd0b55dfcacdd920ccbdaeafa351", "effective_date": "2020-06-30", "run_termination_payroll": false } ``` -------------------------------- ### Get Recurring Reimbursement Example Source: https://docs.gusto.com/app-integrations/reference/get-v1-recurring_reimbursements This example shows a successful response when retrieving a recurring reimbursement. It includes the reimbursement's UUID, employee UUID, description, amount, and timestamps. ```json { "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" } ``` -------------------------------- ### Create Token Example Source: https://docs.gusto.com/app-integrations/reference/oauth-access-token Example of a successful response when creating a new access token. This includes the access token, its type, creation timestamp, and expiration time. A null refresh token indicates it was not provided or applicable for this specific creation. ```json { "access_token": "As8qKfNObHbwe7abbJqF0WUF6iCQoIW2R664TFzXd-A", "token_type": "Bearer", "created_at": 1767644464, "expires_in": 7200, "refresh_token": null } ``` -------------------------------- ### Get a single contractor payment Source: https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-contractor_payment-contractor-payment This example demonstrates how to retrieve a contractor payment using its unique identifier. ```APIDOC ## GET /v1/companies/{company_id}/contractor_payments/{contractor_payment_id} ### Description Returns a single contractor payment. scope: `payrolls:read` ### Method GET ### Endpoint /v1/companies/{company_id}/contractor_payments/{contractor_payment_id} ### Parameters #### Header Parameters - **X-Gusto-API-Version** (string) - Optional - Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used. - enum: ["2026-06-15"] - default: "2026-06-15" #### Path Parameters - **company_id** (string) - Required - The UUID of the company - **contractor_payment_id** (string) - Required - The UUID of the contractor payment ### Response #### Success Response (200) - **uuid** (string) - The unique identifier for the contractor payment. - **bonus** (string) - The bonus amount in the payment. - **date** (string) - The payment date. - **hours** (string) - The number of hours worked for the payment. - **payment_method** (string) - The payment method. - enum: ["Direct Deposit", "Check", "Historical Payment", "Correction Payment"] - **reimbursement** (string) - The reimbursement amount in the payment. - **status** (string) - Contractor payment status - enum: ["Funded", "Unfunded"] - **hourly_rate** (string) - The rate per hour worked for the payment. - **may_cancel** (boolean) - Determine if the contractor payment can be cancelled. - **wage** (string) - The fixed wage of the payment, regardless of hours worked. - **wage_type** (string) - The wage type for the payment. - enum: ["Hourly", "Fixed"] - **wage_total** (string) - (hours * hourly_rate) + wage + bonus - **invoice_number** (string | null) - An optional invoice number associated with this contractor payment. This will be visible to the contractor on their paystub. Maximum 25 characters. - **memo** (string | null) - An optional note or memo for this contractor payment. This will be visible to the contractor on their paystub. ``` -------------------------------- ### Get all time off requests for a company Source: https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-time_off_requests Fetches all time off requests for a given company, with optional filtering by start and end dates. ```APIDOC ## GET /v1/companies/{company_id}/time_off_requests ### Description Get all time off requests, past and present, for a company. In order to reduce the number of time off requests returned in a single response, or to retrieve time off requests from a time period of interest, you may use the `start_date` and `end_date` parameters. You may provide both or either parameters to scope the returned data. For example: `?start_date=2019-01-01` Returns all time off requests where the request start date is equal to or after January 1, 2019. `?end_date=2019-01-01` Returns all time off requests where the request end date is equal to or before January 1, 2019. `?start_date=2019-05-01&end_date=2019-08-31` Returns all time off requests where the request start date is equal to or after May 1, 2019 and the request end date is equal to or before August 31, 2019. `scope: time_off_requests:read` scope: `time_off_requests:read` ### Method GET ### Endpoint /v1/companies/{company_id}/time_off_requests ### Parameters #### Query Parameters - **start_date** (string) - Optional - Filter time off requests starting on or after this date - **end_date** (string) - Optional - Filter time off requests ending on or before this date ### Response #### Success Response (200) - **Time-Off-Request-List** (object) - A list of time off requests. ``` -------------------------------- ### Cursor-based Pagination Example Source: https://docs.gusto.com/app-integrations/docs/pagination Illustrates how to use cursor-based pagination with `starting_after_uuid` and `limit` parameters for more consistent results on real-time data. The `X-Has-Next-Page` header indicates if more pages are available. ```APIDOC ## Cursor-based Pagination ### Description Fetch a subsequent set of records using a cursor (UUID) for more consistent results, especially with real-time data. ### Method GET ### Endpoint `/v1/events?starting_after_uuid={uuid}&limit={number_of_records}` ### Query Parameters - **starting_after_uuid** (string) - Required - The UUID of the last record from the previous response to start fetching after. - **limit** (integer) - Required - The maximum number of records to return. ### Request Example ``` https://api.gusto.com/v1/events?starting_after_uuid=10ac74e7-d6f0-46c0-9697-8ec77ab475ba&limit=5 ``` ### Response Headers - **X-Has-Next-Page** (boolean) - `true` if there are more pages of results, `false` otherwise. ``` -------------------------------- ### Example Time Sheet Object Source: https://docs.gusto.com/app-integrations/reference/get-companies-company_uuid-time_tracking-time_sheets This is an example of a time sheet object returned by the API. It includes details such as UUID, company UUID, status, time zone, entity type, job UUID, entity UUID, shift start and end times, creation and update timestamps, and a list of entries detailing hours worked and pay classification. ```json { "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" } ] } ``` -------------------------------- ### Employment History Example Response Source: https://docs.gusto.com/app-integrations/reference/get-v1-employees-employee_id-employment_history This example shows the structure of a successful response when retrieving an employee's employment history. It includes details such as hire date, termination date, whether a new hire report was filed, if the employee is a two percent shareholder, and their employment status. ```json [ { "hire_date": "2015-06-09", "termination_date": "2025-05-09", "file_new_hire_report": false, "two_percent_shareholder": false, "employment_status": "full_time" } ] ``` -------------------------------- ### OpenAPI Definition for Pay Schedule Assignments Source: https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-pay_schedules-assignments This is the OpenAPI definition for the Get pay schedule assignments endpoint. It outlines the request and response structures, including error objects and example pay schedule assignments. ```json { "openapi": "3.1.0", "tags": [ { "name": "Pay Schedules" } ], "info": { "title": "Gusto API", "version": "2026-06-15", "termsOfService": "https://gusto.com/about/terms/developer-terms-of-service", "description": "Welcome to Gusto's Embedded Payroll API documentation!", "contact": { "name": "Developer Relations", "email": "developer@gusto.com" }, "x-release-status": "stable" }, "servers": [ { "url": "https://api.gusto-demo.com", "description": "Demo", "x-speakeasy-server-id": "demo" } ], "security": [ { "CompanyAccessAuth": [] } ], "components": { "schemas": { "Not-Found-Error-Object": { "description": "Not Found \n \nThe requested resource does not exist. Make sure the provided ID/UUID is valid.", "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "object", "required": [ "error_key", "category" ], "properties": { "error_key": { "type": "string", "description": "Specifies where the error occurs. Typically this key identifies the attribute/parameter related to the error." }, "category": { "type": "string", "description": "Specifies the type of error. The category provides error groupings and can be used to build custom error handling in your integration." }, "message": { "type": "string", "description": "Provides details about the error - generally this message can be surfaced to an end user." } } } } }, "x-examples": { "not_found": { "errors": [ { "error_key": "request", "category": "not_found", "message": "The requested resource was not found." } ] }, "deprecated_accept_terms_of_service": { "errors": [ { "error_key": "request", "category": "deprecated_endpoint", "message": "The requested endpoint is no longer supported in the requested API version. Use POST /v1/partner_managed_companies/:company_uuid/terms_of_service instead" } ] }, "deprecated_retrieve_terms_of_service": { "errors": [ { "error_key": "request", "category": "deprecated_endpoint", "message": "The requested endpoint is no longer supported in the requested API version. Use PUT /v1/partner_managed_companies/:company_uuid/terms_of_service instead" } ] } } }, "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 companies with a single pay schedule.", "readOnly": true }, "employees": { "type": "array", "items": { "type": "object", "required": [ "employee_uuid", "pay_schedule_uuid" ], "properties": { "employee_uuid": { "type": "string", "format": "uuid", "description": "The UUID of the employee.", "readOnly": true }, "pay_schedule_uuid": { "type": "string", "format": "uuid", "description": "The UUID of the pay schedule.", "readOnly": true } } }, "description": "A list of employee UUIDs and their associated pay schedule UUIDs.", "readOnly": true }, "departments": { "type": "array", "items": { "type": "object", "required": [ "department_uuid", "pay_schedule_uuid" ], "properties": { "department_uuid": { "type": "string", "format": "uuid", "description": "The UUID of the department.", "readOnly": true }, "pay_schedule_uuid": { "type": "string", "format": "uuid", "description": "The UUID of the pay schedule.", "readOnly": true } } }, "description": "A list of department UUIDs and their associated pay schedule UUIDs.", "readOnly": true } } } } }, "paths": { "/v1/companies/{company_id}/pay_schedules/assignments": { "get": { "tags": [ "Pay Schedules" ], "summary": "Get pay schedule assignments for a company", "operationId": "get_v1_companies_company_id_pay_schedules_assignments", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pay-Schedule-Assignment" } } } }, "404": { "description": "Not Found \nThe requested resource does not exist. Make sure the provided ID/UUID is valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Not-Found-Error-Object" } } } } }, "security": [ { "CompanyAccessAuth": [ "pay_schedules:read" ] } ] } } } } ``` -------------------------------- ### Rate Limit Exceeded Error Example Source: https://docs.gusto.com/app-integrations/docs/error-categories This JSON structure indicates a 'rate_limit_exceeded' error, meaning the API request limit has been reached. Wait before retrying the request. Refer to the Rate Limits guide for more details. ```json 429 Too Many Requests { "errors": [ { "error_key": "base", "category": "rate_limit_exceeded", "message": "Rate limit exceeded. Please wait a bit before trying again." } ] } ``` -------------------------------- ### Payroll Blocker Error Example Source: https://docs.gusto.com/app-integrations/docs/error-categories This JSON structure represents a 'payroll_blocker' error, indicating an issue with company or employee address verification. Review the Payroll Blockers guide for a full list of possible blockers. ```json 422 Unprocessable Entity { "errors": [ { "error_key": "base", "category": "payroll_blocker", "message": "Company or employee address could not be verified. Please ensure all addresses are valid.", "metadata": { "key": "geocode_error" } } ] } ``` -------------------------------- ### Example Contractor Payment Details Response Source: https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-contractors-payment_details This example shows the structure of the response for contractors paid by check and direct deposit. For direct deposit, masked bank account details and payment splits are included. For check payments, only the payment method is shown. ```json [ { "contractor_uuid": "e3d9487a-4ecb-49a3-b6ff-cf03ba7278b6", "first_name": "Yael", "last_name": "Kuvalis", "payment_method": "Check", "split_by": null, "splits": null }, { "contractor_uuid": "577b6307-66e9-4926-a769-91f5c8b578aa", "first_name": "Autumn", "last_name": "Connelly", "payment_method": "DirectDeposit", "split_by": "manual", "splits": [ { "amount": { "amount": "50.00", "currency": "USD" }, "bank_account": { "routing_number": "111000025", "account_number": "XXXXXX1234", "account_type": "checking" } }, { "amount": { "amount": "50.00", "currency": "USD" }, "bank_account": { "routing_number": "222000011", "account_number": "XXXXXX5678", "account_type": "savings" } } ] } ] ``` -------------------------------- ### Page-based Pagination Example Source: https://docs.gusto.com/app-integrations/docs/pagination Use `page` and `per` parameters to retrieve specific pages of results. The default `per` value is 25 if not specified. ```url https://api.gusto.com/v1/companies/abc123/employees?page=2&per=5 ``` -------------------------------- ### Get Pay Periods Source: https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-pay_periods Fetches pay periods for a given company. By default, it returns periods from the last 6 months up to the current date. You can customize the date range using `start_date` and `end_date` query parameters. End dates can be up to 3 months in the future, with no limit on start dates. ```APIDOC ## GET /v1/companies/{company_id}/pay_periods ### Description Retrieves a list of pay periods for a specific company. This endpoint is fundamental for payroll processing, as it defines the timeframes for compensation, taxes, and other related financial activities. ### Method GET ### Endpoint /v1/companies/{company_id}/pay_periods ### Parameters #### Path Parameters - **company_id** (string) - Required - The UUID of the company #### Query Parameters - **start_date** (string) - Optional - The start date for the pay period range (YYYY-MM-DD). Defaults to 6 months prior to the current date. - **end_date** (string) - Optional - The end date for the pay period range (YYYY-MM-DD). Defaults to the current date. Can be up to 3 months in the future. ### Scope payrolls:read ### Response #### Success Response (200) - **id** (string) - The unique identifier for the pay period. - **start_date** (string) - The start date of the pay period. - **end_date** (string) - The end date of the pay period. - **payroll_run_id** (string) - The ID of the payroll run associated with this pay period, if applicable. - **payroll_run_status** (string) - The status of the payroll run. #### Response Example ```json { "data": [ { "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "start_date": "2023-01-01", "end_date": "2023-01-15", "payroll_run_id": "p1q2r3s4-t5u6-7890-1234-567890abcdef", "payroll_run_status": "processed" } ] } ``` ### Error Handling - **404 Not Found**: Returned if the company ID is invalid or the resource does not exist. - **422 Unprocessable Entity**: Returned if the request parameters are invalid (e.g., invalid date format). ``` -------------------------------- ### Contractor Payment Example Source: https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-contractor_payment-contractor-payment This example shows the structure of a successful contractor payment response, including details like UUID, contractor information, payment amounts, and status. It is useful for understanding the data returned by the API. ```json { "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" } ``` -------------------------------- ### Garnishment List Example Source: https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-employees An example of a list containing multiple garnishment objects. ```APIDOC ## Garnishment List ### Description This example shows a JSON array containing multiple garnishment objects, representing a list of garnishments for an employee. ### Response Example ```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", "order_number": null, "remittance_number": null, "fips_code": "04000" } } ] ``` ``` -------------------------------- ### Offset-based Pagination Example Source: https://docs.gusto.com/app-integrations/docs/pagination Demonstrates how to fetch a specific page of results using `page` and `per` query parameters. The default number of records per page is 25 if `per` is not specified. ```APIDOC ## Offset-based Pagination ### Description Fetch a specific page of records from a collection. ### Method GET ### Endpoint `/v1/companies/{company_uuid}/employees?page={page_number}&per={records_per_page}` ### Query Parameters - **page** (integer) - Required - The page number to retrieve. - **per** (integer) - Optional - The number of records to return per page. Defaults to 25 if not provided. ### Request Example ``` https://api.gusto.com/v1/companies/abc123/employees?page=2&per=5 ``` ### Response Headers - **X-Page** (integer) - The current page being returned. - **X-Total-Count** (integer) - The total number of records in the full collection. - **X-Total-Pages** (integer) - Total number of pages for this collection. - **X-Per-Page** (integer) - Number of records currently being returned per page. ``` -------------------------------- ### Garnishment List Example Source: https://docs.gusto.com/app-integrations/reference/post-v1-employees An example of a list containing multiple garnishment objects for an employee. ```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", "order_number": null, "remittance_number": null, "fips_code": "04000" } } ] ``` -------------------------------- ### Employee Address Schema Example Source: https://docs.gusto.com/app-integrations/reference/get-v1-home_addresses-home_address_uuid This example demonstrates the structure of a successful employee address response, including UUID, employee UUID, effective date, and address details. ```json { "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 } ``` -------------------------------- ### Error Response Examples Source: https://docs.gusto.com/app-integrations/reference/put-v1-salary_estimates-id Examples of common error responses returned by the Salary Estimates API. ```APIDOC ## Error Response Structures This section outlines the structure of error responses you may encounter when interacting with the Salary Estimates API. ### Entity-Error-Object This object represents a single error within a larger response. It is used to detail specific issues with attributes or operations. #### Properties - **error_key** (string) - Required - Specifies where the error occurs. Typically this key identifies the attribute/parameter related to the error. - **category** (string) - Required - 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** (string) - Optional - Provides details about the error - generally this message can be surfaced to an end user. - **metadata** (object) - Optional - 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. - **errors** (array) - Optional - Will only exist if category is `nested_errors`. It is possible to have multiple levels of nested errors. - **items** (object) - Represents a nested error, with the same properties as the parent Entity-Error-Object. ### Common Error Categories and Examples #### `invalid_attribute_value` This category indicates that an attribute or parameter has a value that is not acceptable. ##### Example: `check_date` is required ```json { "errors": [ { "error_key": "check_date", "category": "invalid_attribute_value", "message": "Check date is required" } ] } ``` ##### Example: `payment_period_start_date` and `payment_period_end_date` are required ```json { "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" } ] } ``` ##### Example: Net pay less than zero ```json { "errors": [ { "error_key": "base", "category": "invalid_attribute_value", "message": "Net pay less than zero for one or more external payroll items" } ] } ``` ##### Example: Tax is required ```json { "errors": [ { "error_key": "tax_id", "category": "invalid_attribute_value", "message": "Tax is required" } ] } ``` ##### Example: Tax liability selections are not valid ```json { "errors": [ { "error_key": "tax_id", "category": "invalid_attribute_value", "message": "Tax liability selections are not valid" } ] } ``` #### `invalid_operation` This category signifies that the request cannot be processed due to an invalid operation or state. ##### Example: Invalid payload or parameters ```json { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Invalid payload or parameters" } ] } ``` ##### Example: External Payrolls have already been finalized ```json { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "External Payrolls have already been finalized or a payroll has already been processed." } ] } ``` #### `invalid_attribute_value` (Specific to Employee Bank Accounts) ##### Example: Cannot delete this bank account ```json { "errors": [ { "error_key": "base", "category": "invalid_attribute_value", "message": "Cannot delete this bank account." } ] } ``` ```