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
No operations match.
See How connections work for access and permissions, or browse all integrations.