Skip to content
Changelog

Report a bug

Gusto integration: operations for AI agents

Gusto connects to Type.com as an integration. This page lists the 137 operations documented for Claude and Codex in Type.com: 70 read, 49 write, 18 destructive.

About Gusto

Modern payroll, benefits, and HR management platform for small and medium businesses

Categories: HR & Recruiting

How to connect Gusto to Type.com

Access
Organization connection: one shared account for the workspace.

To add the connection, follow the steps in Space connections.

Documented operations

137 operations. Your connection's permissions determine which operations are available. API references describe the vendor surface; they do not expand your connection's credentials or access.

137 operations listed.

Departments

  • Read

    Get all departments of a company

    Get all of the departments for a given company with the employees and contractors assigned to that department. scope: `departments:read`

    GET /v1/companies/{company_uuid}/departments

  • Read

    Get a department

    Get a department given the UUID scope: `departments:read`

    GET /v1/departments/{department_uuid}

  • Write

    Create a department

    Create a department scope: `departments:write`

    POST /v1/companies/{company_uuid}/departments

  • Write

    Add people to a department

    Add employees and contractors to a department scope: `departments:write`

    PUT /v1/departments/{department_uuid}/add

  • Write

    Update a department

    Update a department scope: `departments:write`

    PUT /v1/departments/{department_uuid}

  • Destructive

    Delete a department

    Delete a department. You cannot delete a department until all employees and contractors have been removed. scope: `departments:write`

    DELETE /v1/departments/{department_uuid}

  • Destructive

    Remove people from a department

    Remove employees and contractors from a department scope: `departments:write`

    PUT /v1/departments/{department_uuid}/remove

Time Tracking

  • Read

    Get all time sheets for a company

    Fetch all company's time sheets. Time sheets represent the time worked by an employee or contractor for a given time range. Hours are classified by pay classification, and can be regular, overtime, or double overtime. scope: `time_sheet:read`

    GET /v1/companies/{company_uuid}/time_tracking/time_sheets

  • Read

    Get a payroll sync

    Fetch a payroll sync. A payroll sync represents the result of syncing approved time sheet data to payroll. Use this endpoint to check the status of a previously initiated sync. scope: `payroll_syncs:read`

    GET /v1/time_tracking/payroll_syncs/{payroll_sync_uuid}

  • Read

    Get a time sheet

    Fetch a time sheet. Time sheets represent the time worked by an employee or contractor for a given time range. Hours are classified by pay classification, and can be regular, overtime, or double overtime. scope: `time_sheet:read`

    GET /v1/time_tracking/time_sheets/{time_sheet_uuid}

  • Read

    Get a batch of time sheets

    Fetch a batch of up to 500 time sheets. When the batch is completed, `results` contains the outcome of each time sheet, matched by `external_id`. scope: `time_sheet:read`

    GET /v1/time_tracking/time_sheets_batches/{time_sheets_batch_uuid}

  • Write

    Create a payroll sync

    Initiate a payroll sync for a company. A payroll sync takes approved time sheet data and syncs it to the company's payroll. ### Asynchronous processing This endpoint triggers an asynchronous operation — the response will return immediately with a status of `pending` while the sync processes in the background. **To track completion:** Subscribe (via POST /v1/webhook_subscriptions) to `PayrollSync` webhook events scope: `payroll_syncs:write`

    POST /v1/companies/{company_id}/time_tracking/payroll_syncs

  • Write

    Create a time sheet

    Create a time sheet for a company. Time sheets represent the time worked by an employee or contractor for a given time range. Hours are classified by pay classification, and can be regular, overtime, or double overtime. scope: `time_sheet:write`

    POST /v1/companies/{company_uuid}/time_tracking/time_sheets

  • Write

    Create a batch of time sheets

    Create or update up to 500 time sheets for a company in one request. Set `batch_action` to `create` to create new time sheets, or to `update` to update existing time sheets. One action applies to the whole batch. Gusto validates every time sheet when it receives the request. If one time sheet is invalid, Gusto rejects the whole batch with a 422 response and processes no time sheets. Gusto also rejects the batch if two time sheets for the same employee or contractor have overlapping shifts. ### Asynchronous processing This endpoint triggers an asynchronous operation—the response will return immediately with a status of `pending` while the batch processes in the background. **To track completion:** Subscribe (via POST /v1/webhook_subscriptions) to `TimeSheetsBatch` webhook events Use the returned batch UUID when calling Get a batch of time sheets. scope: `time_sheet:write`

    POST /v1/companies/{company_uuid}/time_tracking/time_sheets_batches

  • Write

    Update a time sheet

    Update a time sheet. Time sheets represent the time worked by an employee or contractor for a given time range. Hours are classified by pay classification, and can be regular, overtime, or double overtime. scope: `time_sheet:write`

    PUT /v1/time_tracking/time_sheets/{time_sheet_uuid}

  • Destructive

    Delete a time sheet

    Delete a company's time sheet. Time sheets represent the time worked by an employee or contractor for a given time range. Hours are classified by pay classification, and can be regular, overtime, or double overtime. scope: `time_sheet:write`

    DELETE /v1/time_tracking/time_sheets/{time_sheet_uuid}

Earning Types

  • Read

    Get all earning types for a company

    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`

    GET /v1/companies/{company_id}/earning_types

  • Write

    Create a custom earning type

    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`

    POST /v1/companies/{company_id}/earning_types

  • Write

    Update an earning type

    Update an earning type. scope: `payrolls:write`

    PUT /v1/companies/{company_id}/earning_types/{earning_type_uuid}

  • Destructive

    Deactivate an earning type

    Deactivate an earning type. scope: `payrolls:write`

    DELETE /v1/companies/{company_id}/earning_types/{earning_type_uuid}

Company Benefits

  • Read

    Get a supported benefit

    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`

    GET /v1/benefits/{benefit_id}

  • Read

    Get benefit fields requirements by benefit type

    Returns the field requirements for a given benefit type. scope: `benefits:read`

    GET /v1/benefits/{benefit_id}/requirements

  • Read

    Get company benefit summary by company benefit id.

    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`

    GET /v1/company_benefits/{company_benefit_id}/summary

  • Read

    Get all supported benefits

    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`

    GET /v1/benefits

  • Read

    Get benefits for a company

    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`

    GET /v1/companies/{company_id}/company_benefits

  • Read

    Get contribution exclusions for a company benefit

    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`

    GET /v1/company_benefits/{company_benefit_id}/contribution_exclusions

  • Read

    Get all employee benefits for a company benefit

    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`

    GET /v1/company_benefits/{company_benefit_id}/employee_benefits

  • Read

    Get a company benefit

    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`

    GET /v1/company_benefits/{company_benefit_id}

  • Write

    Create a company benefit

    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`

    POST /v1/companies/{company_id}/company_benefits

  • Write

    Update contribution exclusions for a company benefit

    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`

    PUT /v1/company_benefits/{company_benefit_id}/contribution_exclusions

  • Write

    Bulk update employee benefits for a company benefit

    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`

    PUT /v1/company_benefits/{company_benefit_id}/employee_benefits

  • Write

    Update a company benefit

    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`

    PUT /v1/company_benefits/{company_benefit_id}

  • Destructive

    Delete a company benefit

    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`

    DELETE /v1/company_benefits/{company_benefit_id}

Jobs and Compensations

  • Read

    Get a compensation

    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`

    GET /v1/compensations/{compensation_id}

  • Read

    Get compensations for a job

    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`

    GET /v1/jobs/{job_id}/compensations

  • Write

    Create a compensation

    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 must exist for the employee ### Webhooks - `employee_job_compensation.created`: Fires when a compensation is successfully created scope: `compensations:write`

    POST /v1/jobs/{job_id}/compensations

  • Write

    Update a compensation

    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`

    PUT /v1/compensations/{compensation_id}

  • Destructive

    Delete a compensation

    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`

    DELETE /v1/compensations/{compensation_id}

Employees

  • Read

    Get employees of a company

    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`

    GET /v1/companies/{company_id}/employees

  • Read

    Get an employee's custom fields

    Returns a list of the employee's custom fields. scope: `employees:read`

    GET /v1/employees/{employee_id}/custom_fields

  • Read

    Get an employee

    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`

    GET /v1/employees/{employee_id}

  • Read

    Get employee time off activities

    Get employee time off activities. scope: `employee_time_off_activities:read`

    GET /v1/employees/{employee_uuid}/time_off_activities

  • Write

    Create an employee

    Create an employee. scope: `employees:manage`

    POST /v1/companies/{company_id}/employees

  • Write

    Update an employee.

    Update an employee. scope: `employees:write`

    PUT /v1/employees/{employee_id}

  • Destructive

    Delete an onboarding employee

    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`

    DELETE /v1/employees/{employee_id}

Employee Benefits

  • Read

    Get year-to-date benefit amounts from a different company

    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`

    GET /v1/employees/{employee_id}/ytd_benefit_amounts_from_different_company

  • Read

    Get an employee benefit

    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`

    GET /v1/employee_benefits/{employee_benefit_id}

  • Read

    Get all benefits for an employee

    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`

    GET /v1/employees/{employee_id}/employee_benefits

  • Read

    Get a Section 603 high earner status for a specific year

    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`

    GET /v1/employees/{employee_uuid}/section603_high_earner_statuses/{effective_year}

  • Read

    Get all Section 603 high earner statuses for an employee

    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`

    GET /v1/employees/{employee_uuid}/section603_high_earner_statuses

  • Write

    Update a Section 603 high earner status

    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`

    PATCH /v1/employees/{employee_uuid}/section603_high_earner_statuses/{effective_year}

  • Write

    Create year-to-date benefit amounts from a different company

    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`

    POST /v1/employees/{employee_id}/ytd_benefit_amounts_from_different_company

  • Write

    Create an employee benefit

    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`

    POST /v1/employees/{employee_id}/employee_benefits

  • Write

    Create a Section 603 high earner status

    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`

    POST /v1/employees/{employee_uuid}/section603_high_earner_statuses

  • Write

    Update an employee benefit

    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`

    PUT /v1/employee_benefits/{employee_benefit_id}

  • Destructive

    Delete an employee benefit

    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`

    DELETE /v1/employee_benefits/{employee_benefit_id}

Employee Employments

  • Read

    Get employment history for an employee

    Retrieve the employment history for a given employee, which includes termination and rehire. scope: `employments:read`

    GET /v1/employees/{employee_id}/employment_history

  • Read

    Get an employee rehire

    Retrieve an employee's rehire, which contains information on when the employee returns to work. scope: `employments:read`

    GET /v1/employees/{employee_id}/rehire

  • Read

    Get terminations for an employee

    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`

    GET /v1/employees/{employee_id}/terminations

  • Read

    Get an employee termination

    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`

    GET /v1/terminations/{employee_id}

  • Write

    Create an employee rehire

    Rehire is created whenever an employee is scheduled to return to the company. scope: `employments:write`

    POST /v1/employees/{employee_id}/rehire

  • Write

    Update an employee rehire

    Update an employee's rehire. scope: `employments:write`

    PUT /v1/employees/{employee_id}/rehire

  • Destructive

    Delete an employee rehire

    Delete an employee rehire. An employee rehire cannot be deleted if it's active (past effective date). scope: `employments:write`

    DELETE /v1/employees/{employee_id}/rehire

  • Destructive

    Delete an employee termination

    Delete an employee termination. scope: `employments:write`

    DELETE /v1/employees/{employee_id}/terminations

  • Destructive

    Create an employee termination

    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`

    POST /v1/employees/{employee_id}/terminations

  • Destructive

    Update an employee termination

    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`

    PUT /v1/terminations/{employee_id}

Employee Addresses

  • Read

    Get an employee's home addresses

    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`

    GET /v1/employees/{employee_id}/home_addresses

  • Read

    Get an employee's work addresses

    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`

    GET /v1/employees/{employee_id}/work_addresses

  • Read

    Get an employee's home address

    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`

    GET /v1/home_addresses/{home_address_uuid}

  • Read

    Get an employee work address

    The work address of an employee is used for payroll tax purposes. scope: `employees:read`

    GET /v1/work_addresses/{work_address_uuid}

  • Write

    Create an employee's home address

    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`

    POST /v1/employees/{employee_id}/home_addresses

  • Write

    Create an employee work address

    The work address of an employee describes when an employee began working at an associated company location. scope: `employees:manage`

    POST /v1/employees/{employee_id}/work_addresses

  • Write

    Update an employee's home address

    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`

    PUT /v1/home_addresses/{home_address_uuid}

  • Write

    Update an employee work address

    The work address of an employee is used for payroll tax purposes. scope: `employees:manage`

    PUT /v1/work_addresses/{work_address_uuid}

  • Destructive

    Delete an employee's home address

    Used for deleting an employee's home address. Cannot delete the employee's active home address. scope: `employees:write`

    DELETE /v1/home_addresses/{home_address_uuid}

  • Destructive

    Delete an employee's work address

    Used for deleting an employee's work address. Cannot delete the employee's active work address. scope: `employees:manage`

    DELETE /v1/work_addresses/{work_address_uuid}

Reimbursements

  • Read

    Get recurring reimbursements for an employee

    Get all active recurring reimbursements for an employee. scope: `reimbursements:read`

    GET /v1/employees/{employee_id}/recurring_reimbursements

  • Read

    Get a recurring reimbursement

    Get a specific recurring reimbursement. scope: `reimbursements:read`

    GET /v1/recurring_reimbursements/{id}

  • Write

    Create a recurring reimbursement

    Create a recurring reimbursement for an employee. scope: `reimbursements:write`

    POST /v1/employees/{employee_id}/recurring_reimbursements

  • Write

    Update a recurring reimbursement

    Update a recurring reimbursement. scope: `reimbursements:write`

    PUT /v1/recurring_reimbursements/{id}

  • Destructive

    Delete a recurring reimbursement

    Delete (soft delete) a recurring reimbursement for an employee. scope: `reimbursements:write`

    DELETE /v1/recurring_reimbursements/{id}

Webhooks

  • Read

    Get a webhook subscription

    Returns the Webhook Subscription associated with the provided UUID. 📘 System Access Authentication This endpoint uses the Bearer Auth scheme with the system-level access token in the HTTP Authorization header scope: `webhook_subscriptions:read`

    GET /v1/webhook_subscriptions/{webhook_subscription_uuid}

  • Read

    Request a verification token for a webhook subscription

    Request that the webhook subscription `verification_token` be POSTed to the Subscription URL. 📘 System Access Authentication This endpoint uses the Bearer Auth scheme with the system-level access token in the HTTP Authorization header scope: `webhook_subscriptions:read`

    GET /v1/webhook_subscriptions/{webhook_subscription_uuid}/request_verification_token

  • Read

    List webhook subscriptions

    Returns all webhook subscriptions associated with the provided Partner API token. 📘 System Access Authentication This endpoint uses the Bearer Auth scheme with the system-level access token in the HTTP Authorization header scope: `webhook_subscriptions:read`

    GET /v1/webhook_subscriptions

  • Read

    Get the webhooks health status

    Returns the health status (`healthy`, `unhealthy`, or `unknown`) of the webhooks system based on the last ten minutes of activity. 📘 System Access Authentication This endpoint uses the Bearer Auth scheme with the system-level access token in the HTTP Authorization header scope: `webhook_subscriptions:read`

    GET /v1/webhooks/health_check

  • Write

    Create a webhook subscription

    Create a webhook subscription to receive events of the specified subscription_types whenever there is a state change. 📘 System Access Authentication This endpoint uses the Bearer Auth scheme with the system-level access token in the HTTP Authorization header scope: `webhook_subscriptions:write`

    POST /v1/webhook_subscriptions

  • Write

    Verify a webhook subscription

    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. Use the /v1/webhook_subscriptions/{webhook_subscription_uuid}/request_verification_token API to resend the `verification_token` to the Subscriber. 📘 System Access Authentication This endpoint uses the Bearer Auth scheme with the system-level access token in the HTTP Authorization header scope: `webhook_subscriptions:write`

    PUT /v1/webhook_subscriptions/{webhook_subscription_uuid}/verify

  • Write

    Update a webhook subscription

    Updates the Webhook Subscription associated with the provided UUID. 📘 System Access Authentication This endpoint uses the Bearer Auth scheme with the system-level access token in the HTTP Authorization header scope: `webhook_subscriptions:write`

    PUT /v1/webhook_subscriptions/{webhook_subscription_uuid}

  • Destructive

    Delete a webhook subscription

    Deletes the Webhook Subscription associated with the provided UUID. 📘 System Access Authentication This endpoint uses the Bearer Auth scheme with the system-level access token in the HTTP Authorization header scope: `webhook_subscriptions:write`

    DELETE /v1/webhook_subscriptions/{webhook_subscription_uuid}

Notifications

  • Read

    Get notifications for company

    Returns all notifications relevant for the given company. scope: `notifications:read`

    GET /v1/companies/{company_uuid}/notifications

Events

  • Read

    Get all events

    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. 📘 System Access Authentication This endpoint uses the Bearer Auth scheme with the system-level access token in the HTTP Authorization header scope: `events:read`

    GET /v1/events

Reports

  • Read

    Get a report

    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`

    GET /v1/reports/{request_uuid}

  • Write

    Create a general ledger report

    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 to poll for the status and report URL upon completion. The retrieved report will be generated in a JSON format. scope: `company_reports:write`

    POST /v1/payrolls/{payroll_uuid}/reports/general_ledger

Companies

  • Read

    Get all the admins at a company

    Returns a list of all the admins at a company scope: `company_admin:read`

    GET /v1/companies/{company_id}/admins

  • Read

    Get the custom fields of a company

    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`

    GET /v1/companies/{company_id}/custom_fields

  • Read

    Get a company

    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`

    GET /v1/companies/{company_id}

  • Write

    Create a company

    ### Overview The company provisioning API provides a way to create a Gusto company as part of your integration. When you successfully call the API, the API does the following: * Creates a new company in Gusto. * Creates a new user in Gusto. * Makes the new user the primary payroll administrator of the new company. * Sends a welcome email to the new user. In the response, you will receive an account claim URL. Redirect the user to this URL to complete their account setup inside of Gusto > 📘 System Access Authentication > > This endpoint uses the Bearer Auth scheme with the system-level access token in the HTTP Authorization header. 📘 System Access Authentication This endpoint uses the Bearer Auth scheme with the system-level access token in the HTTP Authorization header scope: `accounts:write`

    POST /v1/provision

  • Write

    Update a company

    Update a company. scope: `companies:write`

    PUT /v1/companies/{company_id}

Contractor Payments

  • Read

    Get a single contractor payment

    Returns a single contractor payment. scope: `payrolls:read`

    GET /v1/companies/{company_id}/contractor_payments/{contractor_payment_id}

  • Read

    Get contractor payments for a company

    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`

    GET /v1/companies/{company_id}/contractor_payments

Locations

  • Read

    Get all company locations

    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 or update an individual record. scope: `companies:read`

    GET /v1/companies/{company_id}/locations

  • Read

    Get a location

    Get a location. scope: `companies:read`

    GET /v1/locations/{location_id}

  • Read

    Get minimum wages for a location

    Get minimum wages for a location scope: `companies:read`

    GET /v1/locations/{location_uuid}/minimum_wages

  • Write

    Create a company location

    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 or update an individual record. scope: `companies:write`

    POST /v1/companies/{company_id}/locations

  • Write

    Update a location

    Update a location. scope: `companies:write`

    PUT /v1/locations/{location_id}

Payrolls

  • Read

    Get pay periods for a company

    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 endpoint. scope: `payrolls:read`

    GET /v1/companies/{company_id}/pay_periods

  • Read

    Get a single payroll

    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`

    GET /v1/companies/{company_id}/payrolls/{payroll_id}

  • Read

    Get all payrolls for a company

    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`

    GET /v1/companies/{company_id}/payrolls

  • Write

    Prepare a payroll for update

    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}. ### Notes * Nullifies `calculated_at` and `totals` if the payroll was previously calculated * Returns the `version` parameter required for updating the payroll * `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`

    PUT /v1/companies/{company_id}/payrolls/{payroll_id}/prepare

  • Write

    Update a payroll by ID

    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`

    PUT /v1/companies/{company_id}/payrolls/{payroll_id}

Pay Schedules

  • Read

    Get pay schedule assignments for a company

    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`

    GET /v1/companies/{company_id}/pay_schedules/assignments

  • Read

    Get a pay schedule

    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`

    GET /v1/companies/{company_id}/pay_schedules/{pay_schedule_id}

  • Read

    Get the pay schedules for a company

    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`

    GET /v1/companies/{company_id}/pay_schedules

  • Read

    Get termination pay periods for a company

    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`

    GET /v1/companies/{company_id}/pay_periods/unprocessed_termination_pay_periods

Time Off Requests

  • Read

    Get time off requests for a company

    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`

    GET /v1/companies/{company_id}/time_off_requests

Contractors

  • Read

    Get contractors of a company

    Get all contractors, active and inactive, individual and business, for a company. scope: `contractors:read`

    GET /v1/companies/{company_uuid}/contractors

  • Read

    Get a contractor

    Get a contractor. scope: `contractors:read`

    GET /v1/contractors/{contractor_uuid}

  • Write

    Create a contractor

    Create an individual or business contractor. scope: `contractors:manage`

    POST /v1/companies/{company_uuid}/contractors

  • Write

    Update a contractor

    Update a contractor. > 🚧 Warning > > 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 scope: `contractors:write`

    PUT /v1/contractors/{contractor_uuid}

Time Off Policies

  • Read

    Get all time off policies for a company

    Get all time off policies for a company scope: `time_off_policies:read`

    GET /v1/companies/{company_uuid}/time_off_policies

  • Read

    Get a time off policy

    Get a time off policy scope: `time_off_policies:read`

    GET /v1/time_off_policies/{time_off_policy_uuid}

  • Read

    Calculate accruing time off hours

    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`

    POST /v1/payrolls/{payroll_id}/employees/{employee_id}/calculate_accruing_time_off_hours

  • Write

    Add employees to a time off policy

    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`

    PUT /v1/time_off_policies/{time_off_policy_uuid}/add_employees

Garnishments

  • Read

    Get garnishments for an employee

    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`

    GET /v1/employees/{employee_id}/garnishments

  • Read

    Get child support garnishment data

    Agency data and requirements to be used for creating child support garnishments scope: `garnishments:read`

    GET /v1/garnishments/child_support

  • Read

    Get a garnishment

    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`

    GET /v1/garnishments/{garnishment_id}

  • Write

    Create a garnishment

    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`

    POST /v1/employees/{employee_id}/garnishments

  • Write

    Update a garnishment

    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`

    PUT /v1/garnishments/{garnishment_id}

Salary Estimates

  • Read

    Get a salary estimate

    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`

    GET /v1/salary_estimates/{uuid}

  • Read

    Search for BLS occupations

    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. Returns a list of matching occupations with their codes, titles, and descriptions. 📘 System Access Authentication This endpoint uses the Bearer Auth scheme with the system-level access token in the HTTP Authorization header scope: `salary_estimates:read`

    GET /v1/salary_estimates/occupations

  • Write

    Create a salary estimate for an employee

    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`

    POST /v1/employees/{employee_id}/salary_estimates

  • Write

    Accept a salary estimate

    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`

    POST /v1/salary_estimates/{uuid}/accept

  • Write

    Update a salary estimate

    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`

    PUT /v1/salary_estimates/{uuid}

Introspection

  • Read

    Get info about the current access token

    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

    GET /v1/token_info

  • Write

    Create a System Access Token or Refresh an Access Token

    Creates a system access token or refreshes an oauth access token

    POST /oauth/token

  • Destructive

    Disconnect an app integration

    Disconnects the given company from the App Integration associated with the current system access token. If multiple users from that company are authorized with the App Integration, then their tokens will also be revoked. 📘 System Access Authentication This endpoint uses the Bearer Auth scheme with the system-level access token in the HTTP Authorization header scope: `companies:disconnect_app_integration`

    POST /v1/companies/{company_id}/disconnect_app_integration

  • Destructive

    Revoke access token

    Revokes the given access token. After revoking, this token can no longer be used to make requests nor can it be refreshed.

    POST /oauth/revoke

See How connections work for access and permissions, or browse all integrations.