# Embedded Payroll Documentation ## Guides - [ACH Codes and Transaction Types](https://docs.gusto.com/embedded-payroll/docs/ach-codes-and-transaction-types.md) - [API Clients](https://docs.gusto.com/embedded-payroll/docs/api-clients.md) - [Introduction](https://docs.gusto.com/embedded-payroll/docs/build-options-introduction.md): Learn about the available options for building with Gusto Embedded Payroll - [Customize flows](https://docs.gusto.com/embedded-payroll/docs/customize-flows.md) - [Flow events](https://docs.gusto.com/embedded-payroll/docs/flow-events.md) - [Flow types](https://docs.gusto.com/embedded-payroll/docs/flow-types.md) - [Flows quickstart](https://docs.gusto.com/embedded-payroll/docs/flows-quickstart.md) - [Gusto Flows (pre-built UI)](https://docs.gusto.com/embedded-payroll/docs/gusto-flows-pre-built-ui.md) - [Try it now](https://docs.gusto.com/embedded-payroll/docs/try-it-now.md) - [React SDK](https://docs.gusto.com/embedded-payroll/docs/react-sdk.md): A React component library for building payroll—deeply customizable and quick-to-deploy - [Introduction](https://docs.gusto.com/embedded-payroll/docs/companies-intro.md): Integrate company and employee-related data, and streamline operations - [Company forms](https://docs.gusto.com/embedded-payroll/docs/company-form.md) - [Create a department](https://docs.gusto.com/embedded-payroll/docs/create-a-department.md) - [Create company benefits](https://docs.gusto.com/embedded-payroll/docs/create-company-benefits.md) - [Manage company attachments](https://docs.gusto.com/embedded-payroll/docs/manage-company-attachments.md) - [Manage company bank accounts](https://docs.gusto.com/embedded-payroll/docs/manage-company-bank-accounts.md) - [Manage company locations](https://docs.gusto.com/embedded-payroll/docs/manage-company-locations.md): Learn how to manage company locations such as filing and mailing addresses, and work locations - [Onboard a company](https://docs.gusto.com/embedded-payroll/docs/onboard-a-company.md): Streamline company setup, ensure regulatory compliance, and prepare for payroll activation - [Migrate an existing company](https://docs.gusto.com/embedded-payroll/docs/migrate-existing-company.md): Learn how to migrate a Gusto.com company to your Embedded Payroll system - [Onboard a contractor-only company](https://docs.gusto.com/embedded-payroll/docs/onboard-a-contractor-only-company.md): Set up companies that exclusively employ contractors - [Time off requests](https://docs.gusto.com/embedded-payroll/docs/time-off-requests.md): Submit time off requests, manage admin approvals, and apply time off automatically to payroll - [API fundamentals](https://docs.gusto.com/embedded-payroll/docs/api-fundamentals.md): Learn about the Gusto API, including pagination, rate limits, and scopes - [API versioning](https://docs.gusto.com/embedded-payroll/docs/api-versioning.md): Understanding Gusto date-based versioning - [Version upgrade guide](https://docs.gusto.com/embedded-payroll/docs/version-upgrade-guide.md) - [What is a breaking change?](https://docs.gusto.com/embedded-payroll/docs/what-is-a-breaking-change.md): Understand how Gusto versions its API and what changes may require updates to your integration - [Authentication and authorization](https://docs.gusto.com/embedded-payroll/docs/authentication-and-authorization.md) - [Dev Assistant MCP](https://docs.gusto.com/embedded-payroll/docs/dev-assistant-mcp.md): Learn how to set up and test the Gusto Embedded Dev Assistant MCP server for AI-powered tools. - [Error Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories.md) - [Errors](https://docs.gusto.com/embedded-payroll/docs/errors.md) - [Partner notifications](https://docs.gusto.com/embedded-payroll/docs/partner-notifications.md): Build and manage critical notifications for your end users - [Partner Notification types](https://docs.gusto.com/embedded-payroll/docs/partner-notification-types.md): Resource table - [Testing Partner Notifications](https://docs.gusto.com/embedded-payroll/docs/testing-partner-notifications.md): Receive notification webhooks in demo - [Postman](https://docs.gusto.com/embedded-payroll/docs/postman.md): Learn how to set up and maintain your Postman environment - [Bank Account Events](https://docs.gusto.com/embedded-payroll/docs/bank-account-events.md) - [Best Practices](https://docs.gusto.com/embedded-payroll/docs/best-practices.md) - [Company Benefit Events](https://docs.gusto.com/embedded-payroll/docs/company-benefit-events.md) - [Company Events](https://docs.gusto.com/embedded-payroll/docs/company-events.md) - [Contractor Events](https://docs.gusto.com/embedded-payroll/docs/contractor-events.md) - [Contractor Payment Events](https://docs.gusto.com/embedded-payroll/docs/contractor-payment-events.md) - [Contractor Payment Group Events](https://docs.gusto.com/embedded-payroll/docs/contractor-payment-group-events.md) - [Document Events](https://docs.gusto.com/embedded-payroll/docs/document-events.md) - [Employee Benefit Events](https://docs.gusto.com/embedded-payroll/docs/employee-benefit-events.md) - [Employee Events](https://docs.gusto.com/embedded-payroll/docs/employee-events.md) - [Employee Job Compensation Events](https://docs.gusto.com/embedded-payroll/docs/employee-job-compensation-events.md) - [External Payroll Events](https://docs.gusto.com/embedded-payroll/docs/external-payroll-events.md) - [Fast Ach Config Events](https://docs.gusto.com/embedded-payroll/docs/fast-ach-config-events.md) - [Form Events](https://docs.gusto.com/embedded-payroll/docs/form-events.md) - [Generated Document Events](https://docs.gusto.com/embedded-payroll/docs/generated-document-events.md) - [Employee Home Address Events](https://docs.gusto.com/embedded-payroll/docs/home-address-events.md) - [Webhooks](https://docs.gusto.com/embedded-payroll/docs/webhooks.md) - [Location Events](https://docs.gusto.com/embedded-payroll/docs/location-events.md) - [Notification Events](https://docs.gusto.com/embedded-payroll/docs/notification-events.md) - [Pay Schedule Events](https://docs.gusto.com/embedded-payroll/docs/pay-schedule-events.md) - [Payroll Events](https://docs.gusto.com/embedded-payroll/docs/payroll-events.md) - [Signatory Events](https://docs.gusto.com/embedded-payroll/docs/signatory-events.md) - [Time Off Request Events](https://docs.gusto.com/embedded-payroll/docs/time-off-request-events.md) - [Webhook Events](https://docs.gusto.com/embedded-payroll/docs/webhook-events.md) - [Employee Work Address Events](https://docs.gusto.com/embedded-payroll/docs/work-address-events.md) - [Introduction](https://docs.gusto.com/embedded-payroll/docs/introduction.md) - [Payroll fundamentals](https://docs.gusto.com/embedded-payroll/docs/payroll-fundamentals.md) - [Platform overview](https://docs.gusto.com/embedded-payroll/docs/platform-overview.md) - [Getting started](https://docs.gusto.com/embedded-payroll/docs/getting-started.md): An expanded version of our Quickstart, follow this guide to set up an application, company, company location, and add an employee. - [Quickstart](https://docs.gusto.com/embedded-payroll/docs/quickstart.md): Get started with Gusto Embedded in under 5 minutes - [Payroll Processing Speeds](https://docs.gusto.com/embedded-payroll/docs/2-day-vs-4-day.md) - [Complete a Regular Payroll](https://docs.gusto.com/embedded-payroll/docs/complete-a-regular-payroll.md) - [Payroll Blockers](https://docs.gusto.com/embedded-payroll/docs/payroll-blockers.md) - [Payroll Processing Request](https://docs.gusto.com/embedded-payroll/docs/payroll-processing-request.md) - [Payroll Receipts](https://docs.gusto.com/embedded-payroll/docs/payroll-receipts.md) - [Payroll Statuses](https://docs.gusto.com/embedded-payroll/docs/payroll-statuses.md) - [Payroll Submission Blockers & Unblock Options](https://docs.gusto.com/embedded-payroll/docs/payroll-submission-blockers-unblock-options.md) - [Create a pay schedule](https://docs.gusto.com/embedded-payroll/docs/create-a-pay-schedule.md) - [Pay Schedules](https://docs.gusto.com/embedded-payroll/docs/pay-schedule-info.md) - [Manage Pay Schedules via API](https://docs.gusto.com/embedded-payroll/docs/manage-pay-schedules-api.md) - [Payroll Digests API](https://docs.gusto.com/embedded-payroll/docs/payroll-digests-api.md): Fetch a summary of payroll state across many companies in a single request - [Recovery Cases](https://docs.gusto.com/embedded-payroll/docs/recovery-cases-1.md) - [Contractor documents](https://docs.gusto.com/embedded-payroll/docs/contractor-documents-guide.md) - [Contractor forms](https://docs.gusto.com/embedded-payroll/docs/contractor-forms-guide.md) - [Manage contractor forms and documents](https://docs.gusto.com/embedded-payroll/docs/contractor-forms-documents.md): Get contractor forms and documents, and PDF versions - [Contractor payment group submission blockers](https://docs.gusto.com/embedded-payroll/docs/contractor-payment-group-submission-blockers.md) - [Manage contractors](https://docs.gusto.com/embedded-payroll/docs/manage-contractors.md): Simplify the management of 1099 workers, including freelance, self-employed, and contract staff - [Onboard a Contractor](https://docs.gusto.com/embedded-payroll/docs/onboard-a-contractor.md): Add a 1099 worker to your company payroll - [Contractor Payment Receipts](https://docs.gusto.com/embedded-payroll/docs/contractor-payment-receipts.md) - [Pay contractors](https://docs.gusto.com/embedded-payroll/docs/process-contractor-payments.md): Set up payments to 1099 workers - [Calculate a reasonable salary for S Corp owner-employees](https://docs.gusto.com/embedded-payroll/docs/calculate-a-reasonable-salary-for-s-corp-owner-employees.md): Give S Corp owner-employees a way to estimate BLS-compliant salaries - [Configure employee tax information](https://docs.gusto.com/embedded-payroll/docs/configure-employee-tax-information.md) - [Create a child support garnishment](https://docs.gusto.com/embedded-payroll/docs/create-a-child-support-garnishment.md): Retrieve agency information and create, update, and confirm child support garnishments - [Adjust for minimum wage](https://docs.gusto.com/embedded-payroll/docs/adjust-for-minimum-wage.md) - [Manage W-2 employees](https://docs.gusto.com/embedded-payroll/docs/manage-w-2-employees.md): Learn how to manage the onboarding, compensation, benefits, and more for W-2 employees - [Benefit effective dating](https://docs.gusto.com/embedded-payroll/docs/benefit-effective-dating.md) - [Manage employee benefits](https://docs.gusto.com/embedded-payroll/docs/manage-employee-benefits.md): Create and view the benefits assigned to an employee - [Manage recurring reimbursements](https://docs.gusto.com/embedded-payroll/docs/manage-recurring-reimbursements.md) - [Employee self-onboarding](https://docs.gusto.com/embedded-payroll/docs/employee-self-management.md): Enable employees to self-onboard into a company - [Onboard a W-2 employee](https://docs.gusto.com/embedded-payroll/docs/onboard-a-w2-employee.md): Add a new employee or invite them to self-onboard - [Onboarding Method Comparison](https://docs.gusto.com/embedded-payroll/docs/onboarding-method-comparison.md) - [Terminate a W2 Employee](https://docs.gusto.com/embedded-payroll/docs/terminate-a-w2-employee.md) - [I-9 employment verification](https://docs.gusto.com/embedded-payroll/docs/i-9-employment-verification.md) - [I-9 Verification Using Flows](https://docs.gusto.com/embedded-payroll/docs/i-9-verification-using-flows.md) - [Bank accounts and direct deposit splits](https://docs.gusto.com/embedded-payroll/docs/bank-accounts-and-direct-deposit-splits.md) - [Compensation](https://docs.gusto.com/embedded-payroll/docs/compensation.md) - [Department information](https://docs.gusto.com/embedded-payroll/docs/department-information.md) - [Home address](https://docs.gusto.com/embedded-payroll/docs/home-address.md) - [Create a people batch](https://docs.gusto.com/embedded-payroll/docs/create-people-batch.md) - [Job](https://docs.gusto.com/embedded-payroll/docs/job.md) - [Person data](https://docs.gusto.com/embedded-payroll/docs/people-data.md) - [Work address](https://docs.gusto.com/embedded-payroll/docs/work-address.md) - [ Get the status of a people batch](https://docs.gusto.com/embedded-payroll/docs/get-people-batch-status.md) - [People Batch API](https://docs.gusto.com/embedded-payroll/docs/people-batch-api.md): Create batches of employees in a single request - [People batch webhooks](https://docs.gusto.com/embedded-payroll/docs/webhook.md) - [Create a holiday pay policy](https://docs.gusto.com/embedded-payroll/docs/create-a-holiday-pay-policy.md): Define how employees get paid for holidays - [Time off policies](https://docs.gusto.com/embedded-payroll/docs/time-off-policies.md): Learn how to manage vacation, sick, and holiday time off policies - [Accrual methods](https://docs.gusto.com/embedded-payroll/docs/accrual-methods.md) - [Manage time off policies](https://docs.gusto.com/embedded-payroll/docs/manage-time-off-policies.md): Create, manage, and add employees to time off policies - [Time off management flow](https://docs.gusto.com/embedded-payroll/docs/time-off-management-flow.md) - [401(k) (Guideline)](https://docs.gusto.com/embedded-payroll/docs/401k-guideline.md) - [Health Insurance (SimplyInsured)](https://docs.gusto.com/embedded-payroll/docs/health-insurance-simplyinsured.md) - [On-Demand Pay (Clair)](https://docs.gusto.com/embedded-payroll/docs/on-demand-pay-clair.md) - [Accounting integrations (Xero and QuickBooks Online)](https://docs.gusto.com/embedded-payroll/docs/testing-accounting-integrations-xero-and-qbo.md) - [Workers' Compensation (NEXT)](https://docs.gusto.com/embedded-payroll/docs/workers-compensation-next.md) - [Generate Custom Reports](https://docs.gusto.com/embedded-payroll/docs/generate-custom-reports.md) - [Retrieve a General Ledger report](https://docs.gusto.com/embedded-payroll/docs/retrieve-a-general-ledger-report.md) ## API Reference - [Get the contractor document pdf](https://docs.gusto.com/embedded-payroll/reference/get-v1-contractor-document-pdf.md): Get the contractor document pdf. scope: `contractor_documents:read` - [Get a contractor document](https://docs.gusto.com/embedded-payroll/reference/get-v1-contractor-document.md): Get a contractor document. scope: `contractor_documents:read` - [Get all contractor documents](https://docs.gusto.com/embedded-payroll/reference/get-v1-contractor-documents.md): Get a list of all contractor's documents scope: `contractor_documents:read` - [Sign a contractor document](https://docs.gusto.com/embedded-payroll/reference/put-v1-contractor-document-sign.md): Sign a contractor document. scope: `contractor_documents:write` - [Get the contractor form pdf](https://docs.gusto.com/embedded-payroll/reference/get-v1-contractor-form-pdf.md): Get the link to the form PDF scope: `contractor_forms:read` - [Get a contractor form](https://docs.gusto.com/embedded-payroll/reference/get-v1-contractor-form.md): Get a contractor form scope: `contractor_forms:read` - [Get all contractor forms](https://docs.gusto.com/embedded-payroll/reference/get-v1-contractor-forms.md): Get a list of all contractor's forms scope: `contractor_forms:read` - [Generate a 1099 form [DEMO]](https://docs.gusto.com/embedded-payroll/reference/post-v1-sandbox-generate_1099.md): > 🚧 Demo action > > This action is only available in the Demo environment Generates a 1099 document for testing purposes. scope: `contractors:write` - [Cancel a contractor payment group](https://docs.gusto.com/embedded-payroll/reference/delete-v1-contractor_payment_groups-contractor_payment_group_id.md): Cancels a contractor payment group and all associated contractor payments. All contractor payments must be cancellable, unfunded. scope: `payrolls:run` - [Get contractor payment groups for a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-contractor_payment_groups.md): Returns a list of minimal contractor payment groups within a given time period, including totals but not associated contractor payments. scope: `payrolls:read` - [Get a contractor payment group](https://docs.gusto.com/embedded-payroll/reference/get-v1-contractor_payment_groups-contractor_payment_group_id.md): Returns a contractor payment group with all associated contractor payments. scope: `payrolls:read` - [Get partner disbursements for a contractor payment group](https://docs.gusto.com/embedded-payroll/reference/get-v1-contractor_payment_groups-id-partner_disbursements.md): Get partner disbursements for a specific contractor payment group. scope: `partner_disbursements:read` - [Update partner disbursements for a contractor payment group](https://docs.gusto.com/embedded-payroll/reference/patch-v1-contractor_payment_groups-id-partner_disbursements.md): Update partner disbursements for a specific contractor payment group. scope: `partner_disbursements:write` - [Preview a contractor payment group](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-contractor_payment_groups-preview.md): Preview a group of contractor payments. Request will validate inputs and return preview of the contractor payment group including the expected `debit_date`. The `uuid` field will be null in the response. The returned `creation_token` is a required parameter in order to create the contractor payment group. scope: `payrolls:read` - [Create a contractor payment group](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-contractor_payment_groups.md): Pay a group of contractors. Information needed depends on the contractor's wage type (hourly vs fixed) scope: `payrolls:run` - [Fund a contractor payment group [DEMO]](https://docs.gusto.com/embedded-payroll/reference/put-v1-contractor_payment_groups-contractor_payment_group_id-fund.md): > 🚧 Demo action > This action is only available in the Demo environment Simulate funding a contractor payment group. Funding only occurs automatically in the production environment when bank transactions are generated. Use this action in the demo environment to transition a contractor payment group's `status` from `Unfunded` to `Funded`. A `Funded` status is required for generating a contractor payment receipt. scope: `payrolls:run` - [Get all contractor bank accounts](https://docs.gusto.com/embedded-payroll/reference/get-v1-contractors-contractor_uuid-bank_accounts.md): Returns all contractor bank accounts. scope: `contractor_payment_methods:read` - [Get a contractor's payment method](https://docs.gusto.com/embedded-payroll/reference/get-v1-contractors-contractor_uuid-payment_method.md): Fetches a contractor's payment method. A contractor payment method describes how the payment should be split across the contractor's associated bank accounts. scope: `contractor_payment_methods:read` - [Create a contractor bank account](https://docs.gusto.com/embedded-payroll/reference/post-v1-contractors-contractor_uuid-bank_accounts.md): Creates a contractor bank account. Note: We currently only support one bank account per contractor. Using this endpoint on a contractor who already has a bank account will just replace it. scope: `contractor_payment_methods:write` - [Update a contractor's payment method](https://docs.gusto.com/embedded-payroll/reference/put-v1-contractors-contractor_id-payment_method.md): Updates a contractor's payment method. Note that creating a contractor bank account will also update the contractor's payment method. scope: `contractor_payment_methods:write` - [Cancel a contractor payment](https://docs.gusto.com/embedded-payroll/reference/delete-v1-companies-company_id-contractor_payment-contractor-payment.md): Cancels and deletes a contractor payment. If the contractor payment has already started processing ("may_cancel": true), the payment cannot be cancelled. scope: `payrolls:run` - [Preview contractor payment debit date](https://docs.gusto.com/embedded-payroll/reference/get-companies-company_uuid-contractor_payments-preview.md): Returns a debit_date dependent on the ACH payment speed of the company. If the payment method is Check or Historical payment, the debit_date will be the same as the check_date. scope: `payrolls:read` - [Get a single contractor payment](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-contractor_payment-contractor-payment.md): Returns a single contractor payment. scope: `payrolls:read` - [Get contractor payments for a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-contractor_payments.md): 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` - [List contractor payment details](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-contractors-payment_details.md): Get payment details for contractors in a company. This endpoint returns a list of all contractors associated with the specified company, including their payment methods and bank account details if they are paid via direct deposit. For contractors paid by direct deposit, the response includes their bank account information with sensitive data masked for security. The payment details also include information about how their payments are split if they have multiple bank accounts configured. For contractors paid by check, only the basic payment method information is returned. ### Response Details - For direct deposit contractors: - Bank account details (masked) - Payment splits configuration - Routing numbers - Account types - For check payments: - Basic payment method designation ### Common Use Cases - Fetching contractor payment information for payroll processing - Verifying contractor payment methods - Reviewing payment split configurations `encrypted_account_number` is available only with the additional scope `contractor_payment_methods:read:account_numbers`. scope: `contractor_payment_methods:read` - [Get a contractor payment PDF](https://docs.gusto.com/embedded-payroll/reference/get-v1-contractor_payments-contractor_payment_id-pdf.md): Get a PDF document for a single contractor payment. scope: `payrolls:read` - [Fund a contractor payment [DEMO]](https://docs.gusto.com/embedded-payroll/reference/get-v1-contractor_payments-contractor_payment_uuid-fund.md): > 🚧 Demo action > > This action is only available in the Demo environment Simulate funding a contractor payment. Funding only occurs automatically in the production environment when bank transactions are generated. Use this action in the demo environment to transition a contractor payment's `status` from `Unfunded` to `Funded`. A `Funded` status is required for generating a contractor payment receipt. scope: `payrolls:run` - [Get a single contractor payment receipt](https://docs.gusto.com/embedded-payroll/reference/get-v1-contractor_payments-contractor_payment_uuid-receipt.md): Returns a contractor payment receipt. Notes: * Receipts are only available for direct deposit payments and are only available once those payments have been funded. * Payroll Receipt requests for payrolls which do not have receipts available (e.g. payment by check) will return a 404 status. * Hour and dollar amounts are returned as string representations of numeric decimals. * Dollar amounts are represented to the cent. * If no data has yet be inserted for a given field, it defaults to “0.00” (for fixed amounts). scope: `payrolls:read` - [Get contractor payments](https://docs.gusto.com/embedded-payroll/reference/get-v1-contractors-contractor_uuid-payments.md): Returns a paginated list of payments for a single contractor. Results are sortable by `check_date` or `created_at`. Append `:asc` or `:desc` to control direction (e.g., `check_date:desc`). scope: `contractor_pay_stubs:read` - [Create a contractor payment](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-contractor_payments.md): Pay a contractor. Information needed depends on the contractor's wage type (hourly vs fixed) scope: `payrolls:run` - [Cancel a pending contractor rehire](https://docs.gusto.com/embedded-payroll/reference/delete-v1-contractors-contractor_uuid-rehire.md): ## Purpose Cancels a pending contractor rehire. For future-dated rehires, cancellation is available anytime before the date. For past-dated rehires, cancellation is only available within the 2-day grace period. ## Prerequisites Before calling this endpoint: - The contractor must have a pending rehire (upcoming employment) ## Related webhooks - `contractor.deactivated`: Fires when the contractor returns to inactive state after cancellation scope: `contractors:write` - [Cancel a pending contractor termination](https://docs.gusto.com/embedded-payroll/reference/delete-v1-contractors-contractor_uuid-termination.md): ## Purpose Cancels a pending contractor dismissal. For future-dated dismissals, cancellation is available anytime before the date. For past-dated dismissals, cancellation is only available within the 2-day grace period. ## Prerequisites Before calling this endpoint: - The contractor must have a pending dismissal (scheduled or within the grace period) ## Related webhooks - `contractor.reactivated`: Fires when the contractor becomes active again after cancellation scope: `contractors:write` - [Delete a contractor](https://docs.gusto.com/embedded-payroll/reference/delete-v1-contractors-contractor_uuid.md): A contractor can only be deleted when there are no contractor payments. scope: `contractors:manage` - [Get contractors of a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_uuid-contractors.md): Get all contractors, active and inactive, individual and business, for a company. scope: `contractors:read` - [Get a contractor address](https://docs.gusto.com/embedded-payroll/reference/get-v1-contractors-contractor_uuid-address.md): The address of a contractor is used to determine certain tax information about them. Addresses are geocoded on create and update to ensure validity. scope: `contractors:read` - [Get the contractor's onboarding status](https://docs.gusto.com/embedded-payroll/reference/get-v1-contractors-contractor_uuid-onboarding_status.md): Retrieves a contractor's onboarding status. The data returned helps inform the required onboarding steps and respective completion status. ## onboarding_status ### Admin-facilitated onboarding | onboarding_status | Description | |:------------------|------------:| | `admin_onboarding_incomplete` | Admin needs to enter basic information about the contractor. | | `admin_onboarding_review` | All information has been completed and admin needs to confirm onboarding. | | `onboarding_completed` | Contractor has been fully onboarded and verified. | ### Contractor self-onboarding | onboarding_status | Description | | --- | ----------- | | `admin_onboarding_incomplete` | Admin needs to enter basic information about the contractor. | | `self_onboarding_not_invited` | Admin has the intention to invite the contractor to self-onboard (e.g., marking a checkbox), but the system has not yet sent the invitation. | | `self_onboarding_invited` | Contractor has been sent an invitation to self-onboard. | | `self_onboarding_started` | Contractor has started the self-onboarding process. | | `self_onboarding_review` | Admin needs to review contractors's entered information and confirm onboarding. | | `onboarding_completed` | Contractor has been fully onboarded and verified. | ## onboarding_steps | onboarding_steps | Requirement(s) to be completed | |:-----------------|-------------------------------:| | `basic_details` | Add individual contractor's first name, last name, social security number or Business name and EIN depending on the contractor type | | `add_address` | Add contractor address. | | `compensation_details` | Add contractor compensation. | | `payment_details` | (optional) Set up contractor's direct deposit or set to check. | | `sign_documents` | Contractor forms (e.g., W9) are generated & signed. | | `file_new_hire_report` | Contractor new hire report is generated. | scope: `contractors:read` - [Get a contractor](https://docs.gusto.com/embedded-payroll/reference/get-v1-contractors-contractor_uuid.md): Get a contractor. scope: `contractors:read` - [Create a contractor](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_uuid-contractors.md): Create an individual or business contractor. scope: `contractors:manage` - [Schedule a contractor rehire](https://docs.gusto.com/embedded-payroll/reference/post-v1-contractors-contractor_uuid-rehire.md): ## Purpose Schedules a contractor rehire for a given date. Creates a new employment record for the contractor. ## Prerequisites Before calling this endpoint: 1. The contractor must be inactive (previously dismissed) 2. The contractor must not already have an upcoming employment ## Related webhooks - `contractor.reactivated`: Fires when the contractor becomes active again (on or after start_date) scope: `contractors:write` - [Schedule a contractor termination](https://docs.gusto.com/embedded-payroll/reference/post-v1-contractors-contractor_uuid-termination.md): ## Purpose Schedules a contractor dismissal for a given date. Supports both immediate (past dates) and future-dated dismissals. ## Prerequisites Before calling this endpoint: 1. The contractor must be active (no existing pending dismissal) 2. The contractor must have a current employment ## Related webhooks - `contractor.deactivated`: Fires when the contractor becomes inactive (on or after end_date) scope: `contractors:write` - [Create or update a contractor's address](https://docs.gusto.com/embedded-payroll/reference/put-v1-contractors-contractor_uuid-address.md): The address of a contractor is used to determine certain tax information about them. Addresses are geocoded on create and update to ensure validity. > 🚧 Contractors can only have one address. > > When a contractor is created, an address is created for them by default. Updating the address will replace the existing address. scope: `contractors:write` - [Change the contractor's onboarding status](https://docs.gusto.com/embedded-payroll/reference/put-v1-contractors-contractor_uuid-onboarding_status.md): Updates a contractor's onboarding status. Below is a list of valid onboarding status changes depending on the intended action to be performed on behalf of the contractor. | Action | current onboarding_status | new onboarding_status | |:------------------|:------------:|----------:| | Mark a contractor as self-onboarding | `admin_onboarding_incomplete` | `self_onboarding_not_invited` | | Invite a contractor to self-onboard | `admin_onboarding_incomplete` or `self_onboarding_not_invited` | `self_onboarding_invited` | | Cancel a contractor's self-onboarding | `self_onboarding_invited` or `self_onboarding_not_invited` | `admin_onboarding_incomplete` | | Review a contractor's self-onboarded info | `self_onboarding_started` | `self_onboarding_review` | | Finish a contractor's onboarding | `admin_onboarding_review` or `self_onboarding_review` | `onboarding_completed` | scope: `contractors:write` - [Update a contractor](https://docs.gusto.com/embedded-payroll/reference/put-v1-contractors-contractor_uuid.md): 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` - [Get all ACH transactions for a company](https://docs.gusto.com/embedded-payroll/reference/get-ach-transactions.md): Fetches all ACH transactions for a company. scope: `ach_transactions:read` - [Delete a company bank account](https://docs.gusto.com/embedded-payroll/reference/delete-v1-companies-company_id-bank-accounts-bank_account_id.md): This endpoint disables a company bank account. A bank account cannot be disabled if it is used for any unprocessed payments. scope: `company_bank_accounts:write` - [Get all company bank accounts](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-bank-accounts.md): Returns company bank accounts. Currently, we only support a single default bank account per company. scope: `company_bank_accounts:read` - [Create a company bank account](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-bank-accounts.md): This endpoint creates a new company bank account. Upon being created, two verification deposits are automatically sent to the bank account, and the bank account's verification_status is 'awaiting_deposits'. When the deposits are successfully transferred, the verification_status changes to 'ready_for_verification', at which point the verify endpoint can be used to verify the bank account. After successful verification, the bank account's verification_status is 'verified'. >🚧 Warning > > If a default bank account exists, it will be disabled and the new bank account will replace it as the company's default funding method. scope: `company_bank_accounts:write` - [Create a bank account from a plaid processor token](https://docs.gusto.com/embedded-payroll/reference/post-v1-plaid-processor_token.md): This endpoint creates a new **verified** bank account by using a plaid processor token to retrieve its information. > 📘 > To create a token please use the [plaid api](https://plaid.com/docs/api/processors/#processortokencreate) and select "gusto" as processor. > 🚧 Warning - Company Bank Accounts > > If a default company bank account exists, it will be disabled and the new bank account will replace it as the company's default funding method. scope: `plaid_processor:write` - [Verify a company bank account](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-bank-accounts-verify.md): Verify a company bank account by confirming the two micro-deposits sent to the bank account. Note that the order of the two deposits specified in request parameters does not matter. There's a maximum of 5 verification attempts, after which we will automatically initiate a new set of micro-deposits and require the bank account to be verified with the new micro-deposits. ### Bank account verification in demo In the demo environment, use the `POST /v1/companies/{company_id}/bank_accounts/{bank_account_uuid}/send_test_deposits` endpoint to simulate the micro-deposits transfer and return the two amounts in the response. You can call this endpoint as many times as you wish to retrieve the values of the two micro-deposits. ### Webhooks - `company.bank_account.verified`: Fires when the company bank account is successfully verified. ### Related guides - [Manage company bank accounts](doc:manage-company-bank-accounts) - [Bank Account Events](doc:bank-account-events) scope: `company_bank_accounts:write` - [Get suspensions for this company](https://docs.gusto.com/embedded-payroll/reference/get-companies-company_uuid-suspensions.md): Get existing suspension records for this company. A company may have multiple suspension records if they have suspended their Gusto account more than once. >📘 To check if company is already suspended > > To determine if a company is _currently_ suspended, use the `is_suspended` and `company_status` fields in the [Get a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies) endpoint. scope: `company_suspensions:read` - [Get all the admins at a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-admins.md): Returns a list of all the admins at a company scope: `company_admin:read` - [Get the custom fields of a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-custom_fields.md): 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 a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies.md): 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` - [Finish company onboarding](https://docs.gusto.com/embedded-payroll/reference/get-v1-company-finish-onboarding.md): Finalize a company's onboarding process. ### Approve a company in demo After a company is finished onboarding, Gusto requires an additional step to review and approve that company. The company onboarding status is "onboarding_completed": false, until the API call is made to finish company onboarding. In production environments, this step is required for risk-analysis purposes. We provide the endpoint `PUT '/v1/companies/{company_uuid}/approve'` to facilitate company approvals in the demo environment. ```shell PUT '/v1/companies/89771af8-b964-472e-8064-554dfbcb56d9/approve' # Response: Company object, with company_status: 'Approved' ``` scope: `companies:write` - [Get company onboarding status](https://docs.gusto.com/embedded-payroll/reference/get-v1-company-onboarding-status.md): Retrieves a company's onboarding status, including whether onboarding is complete and the list of required onboarding steps with their respective completion state. scope: `company_onboarding_status:read` - [Check company migration readiness](https://docs.gusto.com/embedded-payroll/reference/get-v1-partner-managed-companies-company-uuid-migration_readiness.md): Check if an existing Gusto customer is ready to be migrated to embedded payroll. This endpoint returns blockers and warnings associated with migrating the company and is recommended to be called before attempting to migrate a company. scope: `partner_managed_companies:read` - [Get the terms of service status for a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-partner-managed-companies-company-uuid-terms_of_service.md): Check if any company payroll admin has accepted the Gusto Embedded Payroll's [Terms of Service](https://flows.gusto.com/terms). This is useful for partners with multiple payroll admins who need to check TOS status at the company level rather than for a specific user. scope: `terms_of_services:read` - [Suspend a company's account](https://docs.gusto.com/embedded-payroll/reference/post-companies-company_uuid-suspensions.md): Use this endpoint to suspend a company. After suspension, company will no longer be able to run payroll but will retain access to their information, such as retrieving employee info or retrieving past payrolls. scope: `company_suspensions:write` - [Accept terms of service for an admin](https://docs.gusto.com/embedded-payroll/reference/post-partner-managed-companies-company_uuid-accept_terms_of_service.md): > Deprecated: use [POST /v1/partner_managed_companies/{company_uuid}/terms_of_service](https://docs.gusto.com/embedded-payroll/reference/post-v1-partner-managed-companies-company-uuid-terms_of_service). Accept the Gusto Embedded Payroll's [Terms of Service](https://flows.gusto.com/terms). The user must be a company admin in order to accept the Terms of Service. scope: `terms_of_services:write` - [Retrieve terms of service status for an admin](https://docs.gusto.com/embedded-payroll/reference/post-partner-managed-companies-company_uuid-retrieve_terms_of_service.md): > Deprecated: use [PUT /v1/partner_managed_companies/{company_uuid}/terms_of_service](https://docs.gusto.com/embedded-payroll/reference/put-v1-partner-managed-companies-company-uuid-terms_of_service) for user-level status, or [GET /v1/partner_managed_companies/{company_uuid}/terms_of_service](https://docs.gusto.com/embedded-payroll/reference/get-v1-partner-managed-companies-company-uuid-terms_of_service) for company-level status. Retrieve the user acceptance status of the Gusto Embedded Payroll's [Terms of Service](https://flows.gusto.com/terms). scope: `terms_of_services:read` - [Create an admin for the company](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-admins.md): Creates a new admin for a company. If the email matches an existing user, this will create an admin account for the current user. Otherwise, this will create a new user. scope: `company_admin:write` - [Accept terms of service for a specific user](https://docs.gusto.com/embedded-payroll/reference/post-v1-partner-managed-companies-company-uuid-terms_of_service.md): Accept the Gusto Embedded Payroll's [Terms of Service](https://flows.gusto.com/terms) on behalf of a specific user. The user must have a role on the company. scope: `terms_of_services:write` - [Create a partner managed company](https://docs.gusto.com/embedded-payroll/reference/post-v1-partner-managed-companies.md): Create a partner managed company. When you successfully call the API, it does the following: * Creates a new company in Gusto * Creates a new user using the provided email if the user does not already exist. * Makes the user the primary payroll administrator of the new company. In response, you will receive oauth access tokens for the created company. IMPORTANT: the returned access and refresh tokens are reserved for this company only. They cannot be used to access other companies AND previously granted tokens cannot be used to access this company. 📘 System Access Authentication This endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `partner_managed_companies:manage` - [Update a company](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies.md): Update a company. scope: `companies:write` - [Migrate company to embedded payroll](https://docs.gusto.com/embedded-payroll/reference/put-v1-partner-managed-companies-company-uuid-migrate.md): Migrate an existing Gusto customer to your embedded payroll product. ### Prerequisites Before calling this endpoint: 1. The customer must connect their Gusto account to your application using [OAuth2](doc:oauth2) 2. The customer must view and [accept the Embedded Payroll Terms of Service](ref:post-partner-managed-companies-company_uuid-accept_terms_of_service) ### Related guides - [Migrate an existing company](doc:migrate-existing-company) scope: `partner_managed_companies:write` - [Check terms of service status for a specific user](https://docs.gusto.com/embedded-payroll/reference/put-v1-partner-managed-companies-company-uuid-terms_of_service.md): Check user-specific Terms of Service acceptance for the Gusto Embedded Payroll [Terms of Service](https://flows.gusto.com/terms). The user must have a role on the company. Returns whether the specific user has accepted the latest TOS version. Uses PUT (rather than GET) to hide the email address from URL logs. scope: `terms_of_services:read` - [Get a temporary url to download the Company Attachment file](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-attachment-url.md): Retrieve a temporary url to download an attachment file uploaded by the company. ### Related guides - [Manage company attachments](doc:manage-company-attachments) scope: `company_attachments:read` - [Get Company Attachment Details](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-attachment.md): Retrieve the detail of an attachment uploaded by the company. ### Related guides - [Manage company attachments](doc:manage-company-attachments) scope: `company_attachments:read` - [Get List of Company Attachments](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-attachments.md): Retrieve a list of all the attachments uploaded by the company. ### Related guides - [Manage company attachments](doc:manage-company-attachments) scope: `company_attachments:read` - [Create Company Attachment and Upload File](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-attachment.md): Upload a file and create a company attachment. We recommend uploading PDF files for optimal compatibility. However, the following file types are allowed: .qbb, .qbm, .gif, .jpg, .png, .pdf, .xls, .xlsx, .doc and .docx. ### Related guides - [Manage company attachments](doc:manage-company-attachments) scope: `company_attachments:write` - [Delete a company benefit](https://docs.gusto.com/embedded-payroll/reference/delete-v1-company_benefits-company_benefit_id.md): 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` - [Get a supported benefit](https://docs.gusto.com/embedded-payroll/reference/get-v1-benefits-benefit_id.md): 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 benefit fields requirements by benefit type](https://docs.gusto.com/embedded-payroll/reference/get-v1-benefits-benefits_id-requirements.md): Returns the field requirements for a given benefit type. scope: `benefits:read` - [Get company benefit summary by company benefit id.](https://docs.gusto.com/embedded-payroll/reference/get-v1-benefits-company_benefit_id-summary.md): 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 all supported benefits](https://docs.gusto.com/embedded-payroll/reference/get-v1-benefits.md): 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 benefits for a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-company_benefits.md): 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 contribution exclusions for a company benefit](https://docs.gusto.com/embedded-payroll/reference/get-v1-company_benefits-company_benefit_id-contribution_exclusions.md): 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 all employee benefits for a company benefit](https://docs.gusto.com/embedded-payroll/reference/get-v1-company_benefits-company_benefit_id-employee_benefits.md): 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 a company benefit](https://docs.gusto.com/embedded-payroll/reference/get-v1-company_benefits-company_benefit_id.md): 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` - [Create a company benefit](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-company_benefits.md): 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` - [Update contribution exclusions for a company benefit](https://docs.gusto.com/embedded-payroll/reference/put-v1-company_benefits-company_benefit_id-contribution_exclusions.md): 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` - [Bulk update employee benefits for a company benefit](https://docs.gusto.com/embedded-payroll/reference/put-v1-company_benefits-company_benefit_id-employee_benefits.md): 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` - [Update a company benefit](https://docs.gusto.com/embedded-payroll/reference/put-v1-company_benefits-company_benefit_id.md): 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` - [Get a company form pdf](https://docs.gusto.com/embedded-payroll/reference/get-v1-company-form-pdf.md): Get the link to the form PDF scope: `company_forms:read` - [Get a company form](https://docs.gusto.com/embedded-payroll/reference/get-v1-company-form.md): Get a company form scope: `company_forms:read` - [Get all company forms](https://docs.gusto.com/embedded-payroll/reference/get-v1-company-forms.md): Get a list of all company's forms ### Related guides - [Company Forms](doc:company-form) scope: `company_forms:read` - [Sign a company form](https://docs.gusto.com/embedded-payroll/reference/put-v1-company-form-sign.md): Sign a company form. Company forms must be signed by the company signatory. scope: `company_forms:sign` - [Delete a department](https://docs.gusto.com/embedded-payroll/reference/delete-department.md): Delete a department. You cannot delete a department until all employees and contractors have been removed. scope: `departments:write` - [Get all departments of a company](https://docs.gusto.com/embedded-payroll/reference/get-companies-departments.md): Get all of the departments for a given company with the employees and contractors assigned to that department. scope: `departments:read` - [Get a department](https://docs.gusto.com/embedded-payroll/reference/get-department.md): Get a department given the UUID scope: `departments:read` - [Create a department](https://docs.gusto.com/embedded-payroll/reference/post-departments.md): Create a department scope: `departments:write` - [Add people to a department](https://docs.gusto.com/embedded-payroll/reference/put-add-people-to-department.md): Add employees and contractors to a department scope: `departments:write` - [Update a department](https://docs.gusto.com/embedded-payroll/reference/put-departments.md): Update a department scope: `departments:write` - [Remove people from a department](https://docs.gusto.com/embedded-payroll/reference/put-remove-people-from-department.md): Remove employees and contractors from a department scope: `departments:write` - [Get a company's federal tax details](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-federal_tax_details.md): Retrieves a company's federal tax details including EIN verification status, tax payer type, filing form, and other federal tax configuration. scope: `company_federal_taxes:read` - [Update a company's federal tax details](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-federal_tax_details.md): Updates a company's federal tax details including EIN, legal name, tax payer type, filing form, and S-Corp taxation status. This information is required to onboard a company for use with Gusto Embedded Payroll. ### Prerequisites Before calling this endpoint, retrieve the current federal tax details and `version` via [GET /v1/companies/{company_id}/federal_tax_details](ref:get-v1-companies-company_id-federal_tax_details) ### Webhooks - `company.updated`: Fires when federal tax details for a company are successfully updated **Setup:** [POST /v1/webhook_subscriptions](ref:post-v1-webhook-subscription) with `subscription_types`: `["Company"]` scope: `company_federal_taxes:write` - [Get a company industry selection](https://docs.gusto.com/embedded-payroll/reference/get-v1-company-industry.md): Returns the industry classification for a company, including NAICS code, SIC codes, and industry title. scope: `companies:read` - [Update a company industry selection](https://docs.gusto.com/embedded-payroll/reference/put-v1-company-industry.md): Update the industry classification for a company by passing in a [NAICS code](https://www.naics.com). Optionally provide an industry title and [SIC codes](https://siccode.com/). If you do not provide SIC codes, we will use the NAICS code to perform an internal lookup. Our UI leverages [Middesk API](https://docs.middesk.com/reference/introduction) to determine industry classification codes. scope: `companies:write` - [Get all company locations](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-locations.md): Retrieves all company locations (addresses) associated with a company: mailing addresses, filing addresses, or work locations. A single address may serve multiple, or all, purposes. Since all company locations are subsets of locations, use the Locations endpoints to [get](ref:get-v1-locations-location_id) or [update](ref:put-v1-locations-location_id) an individual record. scope: `companies:read` - [Get a location](https://docs.gusto.com/embedded-payroll/reference/get-v1-locations-location_id.md): Get a location. scope: `companies:read` - [Get minimum wages for a location](https://docs.gusto.com/embedded-payroll/reference/get-v1-locations-location_uuid-minimum_wages.md): Get minimum wages for a location scope: `companies:read` - [Create a company location](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-locations.md): Create a company location, which represents any address associated with a company: mailing addresses, filing addresses, or work locations. A single address may serve multiple, or all, purposes. Since all company locations are subsets of locations, use the Locations endpoints to [get](ref:get-v1-locations-location_id) or [update](ref:put-v1-locations-location_id) an individual record. scope: `companies:write` - [Update a location](https://docs.gusto.com/embedded-payroll/reference/put-v1-locations-location_id.md): Update a location. scope: `companies:write` - [Get a company's payment configs](https://docs.gusto.com/embedded-payroll/reference/get-v1-company-payment-configs.md): Get payment speed configurations for the company: payment speed (1-day, 2-day, or 4-day ACH), fast payment limit, partner-owned disbursement setting, and earned fast ACH blockers when applicable. 1-day is only available to partners that opt in. ### Related guides - [Payroll Processing Speeds](doc:2-day-vs-4-day) scope: `company_payment_configs:read` - [Update a company's payment configs](https://docs.gusto.com/embedded-payroll/reference/put-v1-company-payment-configs.md): Update payment speed, fast payment limit, and/or partner-owned disbursement for a company. At least one of `payment_speed`, `fast_payment_limit`, or `partner_owned_disbursement` is required. 1-day payment speed is only applicable to partners that opt in. 1-day is not allowed when AutoPilot is enabled. ### Related guides - [Payroll Processing Speeds](doc:2-day-vs-4-day) scope: `company_payment_configs:write` - [Get a people batch](https://docs.gusto.com/embedded-payroll/reference/get-v1-people_batches-people_batch_uuid.md): Returns the status and results of a people batch. Poll this endpoint to check the batch processing status and retrieve results. scope: `people_batches:read` - [Create a people batch](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-people_batches.md): Creates a batch for bulk employee creation. The batch is processed asynchronously. Use the returned batch UUID to poll for status and results. scope: `people_batches:write` - [Delete a signatory](https://docs.gusto.com/embedded-payroll/reference/delete-v1-companies-company_uuid-signatories-signatory_uuid.md): Deletes a company signatory. ## Related guides - [Signatory Events](doc:signatory-events) scope: `signatories:manage` - [Get the signatories for a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_uuid-signatories.md): Returns the signatories for a company. A company has at most one signatory. ## Related guides - [Signatory Events](doc:signatory-events) scope: `signatories:read` - [Invite a signatory](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_uuid-signatories-invite.md): Creates a signatory with minimal information. This signatory can be invited to provide more information through the [Update a signatory](ref:put-v1-companies-company_uuid-signatories-signatory_uuid) endpoint. This will start the identity verification process and allow the signatory to be verified to sign documents. ## Related guides - [Signatory Events](doc:signatory-events) scope: `signatories:manage` - [Create a signatory](https://docs.gusto.com/embedded-payroll/reference/post-v1-company-signatories.md): Creates a company signatory with complete information. The company must not already have a signatory. A signatory can legally sign forms once the identity verification process is successful. The signatory should be an officer, owner, general partner or LLC member manager, plan administrator, fiduciary, or an authorized representative who is designated to sign agreements on the company's behalf. An officer is the president, vice president, treasurer, chief accounting officer, etc. There can only be a single primary signatory in a company. ### Webhooks - `signatory.created`: Fires when a signatory is successfully created. ### Related guides - [Signatory Events](doc:signatory-events) scope: `signatories:manage` - [Update a signatory](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_uuid-signatories-signatory_uuid.md): Updates a signatory that has been either invited or created. If the signatory has been created with minimal information through the [Invite a signatory](ref:post-v1-companies-company_uuid-signatories-invite) endpoint, then the first update must contain all attributes specified in the request body in order to start the identity verification process. ## Related guides - [Signatory Events](doc:signatory-events) scope: `signatories:write` - [Get tax requirements for a state](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_uuid-tax_requirements-state.md): Retrieves the detailed tax requirements for a specific state. The response includes requirement sets grouped by category (e.g., registrations, tax rates, deposit schedules), each containing individual requirements with their current values, labels, and metadata describing the expected input format. Use this to build dynamic UIs for tax setup or to read the current tax configuration for a state. scope: `company_tax_requirements:read` - [Get all tax requirements for a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_uuid-tax_requirements.md): Retrieves all states for which a company has tax requirements, along with a boolean indicating whether tax setup is complete for each state. Use this to determine which states still need tax setup during company onboarding. scope: `company_tax_requirements:read` - [Update tax requirements for a state](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_uuid-tax_requirements-state.md): Updates the tax requirement answers for a specific state. Submit answers to the requirement questions returned by [GET /v1/companies/{company_uuid}/tax_requirements/{state}](ref:get-v1-companies-company_uuid-tax_requirements-state). ### Prerequisites 1. Retrieve current requirements via [GET /v1/companies/{company_uuid}/tax_requirements/{state}](ref:get-v1-companies-company_uuid-tax_requirements-state) 2. Ensure that each requirement set that you're updating includes the correct `key`, `state`, and `effective_from` values from the GET response scope: `company_tax_requirements:write` - [Get all events](https://docs.gusto.com/embedded-payroll/reference/get-events.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `events:read` - [Create a flow](https://docs.gusto.com/embedded-payroll/reference/post-v1-company-flows.md): Generate a link to access a pre-built workflow in Gusto white-label UI. For security, all generated flows will expire within 1 hour of inactivity or 24 hours from creation time, whichever comes first. You can see a list of all possible flow types in our [Flow Types](https://docs.gusto.com/embedded-payroll/docs/flow-types) guide. You can also mix and match flow_types in the same category to create custom flows suitable for your needs. For instance, to create a custom onboarding flow that only includes `add_addresses`, `add_employees`, and `sign_all_forms` steps, simply stitch those flow_types together into a comma delimited string: ```json { "flow_type": "add_addresses,add_employees,sign_all_forms" } ``` Please be mindful of data dependencies in each step to achieve the best user experience. For more information and in-depth guides review the [Getting Started](https://docs.gusto.com/embedded-payroll/docs/flows-getting-started) guide for flows. scope: `flows:write` - [Get a generated document](https://docs.gusto.com/embedded-payroll/reference/get-v1-generated_documents-document_type-request_uuid.md): Get a document given the request_uuid. The response will include the generation request's status and urls to the document. A list of urls is returned as certain document types require several urls. scope: `generated_documents:read` - [Delete a company's holiday pay policy](https://docs.gusto.com/embedded-payroll/reference/delete-v1-companies-company_uuid-holiday_pay_policy.md): Delete a company's holiday pay policy scope: `holiday_pay_policies:write` - [Get a company's holiday pay policy](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_uuid-holiday_pay_policy.md): Get a company's holiday pay policy scope: `holiday_pay_policies:read` - [Create a holiday pay policy for a company](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_uuid-holiday_pay_policy.md): Create a holiday pay policy for a company scope: `holiday_pay_policies:write` - [Add employees to a company's holiday pay policy](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_uuid-holiday_pay_policy-add.md): Add employees to a company's holiday pay policy scope: `holiday_pay_policies:write` - [Remove employees from a company's holiday pay policy](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_uuid-holiday_pay_policy-remove.md): Remove employees from a company's holiday pay policy scope: `holiday_pay_policies:write` - [Update a company's holiday pay policy](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_uuid-holiday_pay_policy.md): Update a company's holiday pay policy scope: `holiday_pay_policies:write` - [Preview a company's paid holidays](https://docs.gusto.com/embedded-payroll/reference/get-companies-company_uuid-paid_holidays.md): Preview a company's paid holidays If a year is passed, paid holidays for that year will be returned. Otherwise, paid holidays for the next three years will be returned. scope: `holiday_pay_policies:read` - [Get all information requests for a company](https://docs.gusto.com/embedded-payroll/reference/get-information-requests.md): Fetch all information requests for a company. scope: `information_requests:read` - [Retrieve invoicing data for companies](https://docs.gusto.com/embedded-payroll/reference/get-invoices-invoice-period.md): Retrieve data for active companies used to calculate invoices for Gusto Embedded Payroll. A company is considered active for an invoice period if they are an active partner managed company, have run payroll or created contractor payments since becoming a partner managed company, and are not suspended at any point during the invoice period. This endpoint forces pagination, with 100 results returned at a time. You can learn more about our pagination here: [pagination guide](https://docs.gusto.com/embedded-payroll/docs/pagination) 📘 System Access Authentication This endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `invoices:read` - [Get notifications for company](https://docs.gusto.com/embedded-payroll/reference/get-company-notifications.md): Returns all notifications relevant for the given company. scope: `notifications:read` - [Get a notification's details](https://docs.gusto.com/embedded-payroll/reference/get-notifications-notification_uuid.md): Upon receiving a notification webhook event, use this endpoint to fetch the notification's details. The notification details include basic suggested content that can help you build notifications in your platform. Note: partners are responsible for the delivery and any custom state management of notifications in their application. Refer to our [partner notification guide](https://docs.gusto.com/embedded-payroll/docs/partner-notifications) for more details. If the notification UUID is not found, the response will be 404 Not Found. If the notification's supporting data is no longer valid, the response will be 422 Unprocessable Entity. scope: `notifications:read` - [Deactivate an earning type](https://docs.gusto.com/embedded-payroll/reference/delete-v1-companies-company_id-earning_types-earning_type_uuid.md): Deactivate an earning type. scope: `payrolls:write` - [Get all earning types for a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-earning_types.md): 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` - [Create a custom earning type](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-earning_types.md): 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` - [Update an earning type](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-earning_types-earning_type_uuid.md): Update an earning type. scope: `payrolls:write` - [Delete an external payroll](https://docs.gusto.com/embedded-payroll/reference/delete-v1-external-payroll.md): Delete an external payroll. scope: `external_payrolls:write` - [Get external payrolls for a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-company-external-payrolls.md): Get external payrolls for a company. scope: `external_payrolls:read` - [Get tax suggestions for an external payroll](https://docs.gusto.com/embedded-payroll/reference/get-v1-external-payroll-calculate-taxes.md): Get tax suggestions for an external payroll. Earnings and/or benefits data must be saved prior to the calculation in order to retrieve accurate tax calculation. scope: `external_payrolls:read` - [Get an external payroll](https://docs.gusto.com/embedded-payroll/reference/get-v1-external-payroll.md): Get an external payroll for a given company. scope: `external_payrolls:read` - [Get tax liabilities](https://docs.gusto.com/embedded-payroll/reference/get-v1-tax-liabilities.md): Get tax liabilities from aggregate external payrolls for a company. scope: `external_payrolls:read` - [Create an external payroll for a company](https://docs.gusto.com/embedded-payroll/reference/post-v1-external-payroll.md): Creates a new external payroll for a company. scope: `external_payrolls:write` - [Update an external payroll](https://docs.gusto.com/embedded-payroll/reference/put-v1-external-payroll.md): Update an external payroll with a list of external payroll items. scope: `external_payrolls:write` - [Finalize tax liabilities options and convert into processed payrolls](https://docs.gusto.com/embedded-payroll/reference/put-v1-tax-liabilities-finish.md): Finalizes tax liabilities for a company. All external payrolls edit action will be disabled. ### Asynchronous processing This endpoint triggers an asynchronous operation. The external payrolls will be processed in the background after finalization. scope: `external_payrolls:write` - [Update tax liabilities](https://docs.gusto.com/embedded-payroll/reference/put-v1-tax-liabilities.md): Update tax liabilities for a company. scope: `external_payrolls:write` - [Get pay periods for a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-pay_periods.md): Pay periods are the foundation of payroll. Compensation, time & attendance, taxes, and expense reports all rely on when they happened. To begin submitting information for a given payroll, we need to agree on the time period. By default, this endpoint returns pay periods starting from 6 months ago to the date today. Use the `start_date` and `end_date` parameters to change the scope of the response. End dates can be up to 3 months in the future and there is no limit on start dates. Starting in version 2023-04-01, the `eligible_employees` attribute was removed from the response. The eligible employees for a payroll are determined by the employee_compensations returned from the [PUT /v1/companies/{company_id}/payrolls/{payroll_id}/prepare](ref:put-v1-companies-company_id-payrolls-payroll_id-prepare) endpoint. scope: `payrolls:read` - [Get pay schedule assignments for a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-pay_schedules-assignments.md): 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 a pay schedule](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-pay_schedules-pay_schedule_id.md): 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` - [Preview pay schedule dates](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-pay_schedules-preview.md): Provides a preview of a pay schedule with the specified parameters for the next 18 months. Use this before creating or updating a pay schedule to show expected check dates, pay period boundaries, and payroll deadlines. ### Related guides - [Create a pay schedule](doc:create-a-pay-schedule) - [Manage Pay Schedules via API](doc:manage-pay-schedules-api) scope: `pay_schedules:write` - [Get the pay schedules for a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-pay_schedules.md): 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 termination pay periods for a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-unprocessed_termination_pay_periods.md): 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` - [Assign pay schedules for a company](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-pay_schedules-assign.md): This endpoint assigns employees to pay schedules based on the schedule type. For `by_employee` and `by_department` schedules, use the `partial_assignment` parameter to control the assignment scope. Set it to `true` for partial assignments (only some employees or departments at a time) and `false` for full assignments (all employees or departments at once). scope: `pay_schedules:write` - [Preview pay schedule assignments for a company](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-pay_schedules-assignment_preview.md): This endpoint returns the employee changes, including pay period and transition pay periods, for changing the pay schedule. scope: `pay_schedules:write` - [Create a new pay schedule](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-pay_schedules.md): If a company does not have any pay schedules, this endpoint will create a single pay schedule and assign it to all employees. This is a common use case during company onboarding. If a company has an existing active pay schedule and want to support multiple pay schedules, this endpoint will create a pay schedule that is not assigned to any employee. Be sure to **[check state laws](https://www.dol.gov/agencies/whd/state/payday)** to know what schedule is right for your customers. > If an onboarded company misses their first pay date, Gusto will automatically adjust the pay schedule to the next available pay date. ### Webhooks - `pay_schedule.created`: Fires when a pay schedule is successfully created. ### Related guides - [Create a pay schedule](doc:create-a-pay-schedule) - [Pay Schedules](doc:pay-schedule-info) - [Manage Pay Schedules via API](doc:manage-pay-schedules-api) scope: `pay_schedules:write` - [Update a pay schedule](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-pay_schedules-pay_schedule_id.md): Updates a pay schedule. The `version` parameter from the GET response is required for [optimistic concurrency](doc:api-fundamentals); a mismatch returns 409 Conflict. ### Effect on payrolls Updating a pay schedule will delete any unprocessed regular payrolls whose pay period end date is today or in the future. Already-processed payrolls are not affected. ### Pay schedules may be automatically adjusted If an onboarded company misses their first pay date, Gusto will automatically adjust the pay schedule to the next available pay date. ### Webhooks - `pay_schedule.updated`: Fires when a pay schedule is successfully updated. ### Related guides - [Create a pay schedule](doc:create-a-pay-schedule) - [Manage Pay Schedules via API](doc:manage-pay-schedules-api) scope: `pay_schedules:write` - [Get a payroll digest batch](https://docs.gusto.com/embedded-payroll/reference/get-v1-payroll_digests-payroll_digest_uuid.md): Returns the status and results of a payroll digest batch. Poll this endpoint until the batch `status` reaches a terminal value (`completed` or `failed`). Once terminal, the response includes the full `results` array (one entry per attempted company, each with its own per-company `status` — `success`, `partial_success`, or `failed`) and the `exclusions` array (one entry per company that could not be looked up or processed). Note that the top-level batch `status` (`pending` / `processing` / `completed` / `failed`) is distinct from the per-company `status` returned inside `results[]` and `exclusions[]`. A `completed` batch does not imply every company succeeded — inspect the arrays for per-company outcomes. Results are stored in Redis with a short TTL after completion. If the partner polls after results have expired, this endpoint returns 410 Gone — partners should re-submit a new batch to fetch fresh data. 📘 System Access Authentication This endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `payroll_digests:read` - [Create a payroll digest batch](https://docs.gusto.com/embedded-payroll/reference/post-v1-payroll_digests.md): Triggers an asynchronous computation of payroll digest data (statuses, blockers, pay periods, totals) across up to 25 companies that the partner is mapped to. The batch is processed asynchronously. Use the returned batch UUID to poll `GET /v1/payroll_digests/{payroll_digest_uuid}` for status and results. Idempotency is scoped per `(partner, idempotency_key)`. A duplicate POST with the same `idempotency_key` returns a 409 Conflict referencing the existing batch UUID — no duplicate computation occurs. 📘 System Access Authentication This endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `payroll_digests:write` - [Delete a payroll](https://docs.gusto.com/embedded-payroll/reference/delete-v1-companies-company_id-payrolls.md): This endpoint allows you to delete an **unprocessed** payroll. By default the payroll and associated data is deleted synchronously. To request an asynchronous delete, use the `async=true` query parameter. In both cases validation of ability to delete will be performed and an Unprocessable Entity error will be returned if the payroll is not able to be deleted. A successful synchronous delete will return `204/No Content`. When a payroll has been enqueued for asynchronous deletion, `202/Accepted` will be returned. scope: `payrolls:run` - [Get approved payroll reversals](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-payroll_reversals.md): Returns all approved Payroll Reversals for a Company. scope: `payrolls:read` - [Get partner disbursements for a payroll](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-payrolls-id-partner_disbursements.md): Get partner disbursements for a specific payroll. scope: `partner_disbursements:read` - [Get a single payroll](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-payrolls-payroll_id.md): 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 all payrolls for a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-payrolls.md): 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 all payroll blockers for a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-payroll-blockers-company_uuid.md): Returns a list of reasons that prevent the company from running payrolls. See the [Payroll Blockers guide](doc:payroll-blockers) for a complete list of reasons. The list is empty if there are no payroll blockers. scope: `payrolls:run` - [Get an employee's pay stubs](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_uuid-pay_stubs.md): Get an employee's pay stubs. Results are returned in reverse chronological order (newest first). scope: `pay_stubs:read` - [Get a single payroll receipt](https://docs.gusto.com/embedded-payroll/reference/get-v1-payment-receipts-payrolls-payroll_uuid.md): Returns a payroll receipt. Notes: * Hour and dollar amounts are returned as string representations of numeric decimals. * Dollar amounts are represented to the cent. * If no data has yet be inserted for a given field, it defaults to "0.00" (for fixed amounts). * Results are paginated. Maximum page size is 100 employee compensations per request. scope: `payrolls:read` - [Get an employee pay stub (pdf)](https://docs.gusto.com/embedded-payroll/reference/get-v1-payrolls-payroll_uuid-employees-employee_uuid-pay_stub.md): Get an employee's pay stub for the specified payroll. By default, an application/pdf response will be returned. No other content types are currently supported, but may be supported in the future. scope: `pay_stubs:read` - [Update partner disbursements for a payroll](https://docs.gusto.com/embedded-payroll/reference/patch-v1-companies-company_id-payrolls-id-partner_disbursements.md): Update partner disbursements for a specific payroll. scope: `partner_disbursements:write` - [Skip a payroll](https://docs.gusto.com/embedded-payroll/reference/post-companies-payroll-skip-company_uuid.md): Submits a $0 payroll for employees associated with the pay schedule to skip payroll. This submission is asynchronous and a successful request responds with a 202 HTTP status. Upon success, the payroll is transitioned to the `processed` state. If the company is blocked from running payroll due to issues like incomplete setup, missing information or other compliance issues, the response will be 422 Unprocessable Entity with a categorization of the blockers as described in the error responses. scope: `payrolls:run` - [Calculate gross up for a payroll](https://docs.gusto.com/embedded-payroll/reference/post-payrolls-gross-up-payroll_uuid.md): Calculates gross up earnings for an employee's payroll, given net earnings. This endpoint is only applicable to off-cycle unprocessed payrolls. The gross up amount must then be mapped to the corresponding fixed compensation earning type to get the correct payroll amount. For example, for bonus off-cycles, the gross up amount should be set with the Bonus earning type in the payroll `fixed_compensations` field. scope: `payrolls:run` - [Create an off-cycle payroll](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-payrolls.md): Creates a new, unprocessed, off-cycle payroll. ## `off_cycle_reason` By default: - External benefits and deductions will be included when the `off_cycle_reason` is set to `Correction`. - All benefits and deductions are blocked when the `off_cycle_reason` is set to `Bonus`. These elections can be overridden with the `skip_regular_deductions` boolean. scope: `payrolls:run` - [Generate printable payroll checks (pdf)](https://docs.gusto.com/embedded-payroll/reference/post-v1-payrolls-payroll_uuid-generated_documents-printable_payroll_checks.md): This endpoint initiates the generation of employee checks for the payroll specified by payroll_uuid. A generation status and corresponding request_uuid will be returned. Use the generated document GET endpoint with document_type: `printable_payroll_checks` and request_uuid to poll the check generation process and retrieve the generated check URL upon completion. scope: `generated_documents:write` - [Cancel a payroll](https://docs.gusto.com/embedded-payroll/reference/put-api-v1-companies-company_id-payrolls-payroll_id-cancel.md): Transitions a `processed` payroll back to the `unprocessed` state. A payroll can be canceled if it meets both criteria: - `processed` is `true` - Current time is earlier than 4pm PT on the `payroll_deadline` scope: `payrolls:run` - [Calculate a payroll](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-payrolls-payroll_id-calculate.md): Performs calculations for taxes, benefits, and deductions for an unprocessed payroll. The calculated payroll details provide a preview of the actual values that will be used when the payroll is run. This calculation is asynchronous and a successful request responds with a 202 HTTP status. To view the details of the calculated payroll, use the GET /v1/companies/{company_id}/payrolls/{payroll_id} endpoint with *include=taxes,benefits,deductions* params. If the company is blocked from running payroll due to issues like incomplete setup, missing information or other compliance issues, the response will be 422 Unprocessable Entity with a categorization of the blockers as described in the error responses. scope: `payrolls:run` - [Prepare a payroll for update](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-payrolls-payroll_id-prepare.md): Prepares an unprocessed payroll for update, including: adding or removing eligible employees from the payroll, and updating `check_date`, `payroll_deadline`, and `payroll_status_meta` dates and times. Use this endpoint before calling [PUT /v1/companies/{company_id}/payrolls/{payroll_id}](ref:put-v1-companies-company_id-payrolls). ### Notes * Nullifies `calculated_at` and `totals` if the payroll was previously calculated * Returns the `version` parameter required for [updating the payroll](ref:put-v1-companies-company_id-payrolls) * `employees:read` scope is required to include employee compensations data in the response. * Results are paginated, with a maximum page size of 100 employee compensations. scope: `payrolls:write employees:read` - [Submit payroll](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-payrolls-payroll_id-submit.md): Submits an unprocessed payroll to be calculated and run. This submission is asynchronous and a successful request responds with a 202 HTTP status. Upon success, transitions the payroll to the `processed` state. You should poll to ensure that payroll is processed successfully, as async errors only occur after async processing is complete. If the company is blocked from running payroll due to issues like incomplete setup, missing information or other compliance issues, the response will be 422 Unprocessable Entity with a categorization of the blockers as described in the error responses. scope: `payrolls:run` - [Update a payroll by ID](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-payrolls.md): 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` - [Get all recovery cases for a company](https://docs.gusto.com/embedded-payroll/reference/get-recovery-cases.md): Fetch all recovery cases for a company. scope: `recovery_cases:read` - [Initiate a redebit for a recovery case](https://docs.gusto.com/embedded-payroll/reference/redebit-recovery-case.md): After resolving the underlying bank error, initiate a redebit for an open recovery case. This submission is asynchronous and a successful request responds with a 202 HTTP status. It may take up to four business days for the ACH debit to process; in the meantime, the status of the recovery case will be in the `initiated_redebit` state. When funds are successfully redebited, the recovery case is transitioned to the `recovered` state. If the company has exceeded maximum redebit attempts, or if the recovery case is not in a redebitable state, the response will be 422 Unprocessable Entity. scope: `recovery_cases:write` - [Delete a recurring reimbursement](https://docs.gusto.com/embedded-payroll/reference/delete-v1-recurring_reimbursements.md): Delete (soft delete) a recurring reimbursement for an employee. scope: `reimbursements:write` - [Get recurring reimbursements for an employee](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-recurring_reimbursements.md): Get all active recurring reimbursements for an employee. scope: `reimbursements:read` - [Get a recurring reimbursement](https://docs.gusto.com/embedded-payroll/reference/get-v1-recurring_reimbursements.md): Get a specific recurring reimbursement. scope: `reimbursements:read` - [Create a recurring reimbursement](https://docs.gusto.com/embedded-payroll/reference/post-v1-employees-employee_id-recurring_reimbursements.md): Create a recurring reimbursement for an employee. scope: `reimbursements:write` - [Update a recurring reimbursement](https://docs.gusto.com/embedded-payroll/reference/put-v1-recurring_reimbursements.md): Update a recurring reimbursement. scope: `reimbursements:write` - [Create an employees annual FICA wage report](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-reports-employees_annual_fica_wage.md): Generates a report containing annual FICA (Federal Insurance Contributions Act) wage data for all employees in a company over a specified year range. This report provides detailed wage information subject to Social Security and Medicare taxes, useful for benefits integrations that need to verify employee earnings for compliance and benefit calculations. The report is generated asynchronously. After making this request, you will receive a `request_uuid` which can be used to poll the [Get a report](ref:get-v1-reports-request_uuid) endpoint to check the status and retrieve the report when complete. scope: `company_reports:write` - [Get a report template](https://docs.gusto.com/embedded-payroll/reference/get-companies-company_uuid-report-templates-report_type.md): Get a company's report template. The only supported report type is `payroll_journal`. The resulting columns and groupings from this endpoint can be used as a guidance to create the report using the POST create report endpoint. scope: `company_reports:write` - [Get a report](https://docs.gusto.com/embedded-payroll/reference/get-reports-request_uuid.md): 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` - [Create a custom report](https://docs.gusto.com/embedded-payroll/reference/post-companies-company_uuid-reports.md): Create a custom report for a company. This endpoint initiates creating a custom report with custom columns, groupings, and filters. The `request_uuid` in the response can then be used to poll for the status and report URL upon completion using the [report GET endpoint](https://docs.gusto.com/embedded-payroll/reference/get-reports-request_uuid). This URL is valid for 10 minutes. scope: `company_reports:write` - [Create a general ledger report](https://docs.gusto.com/embedded-payroll/reference/post-payrolls-payroll_uuid-reports-general_ledger.md): Create a general ledger report for a payroll. The report can be aggregated by different dimensions such as job or department. Use the `request_uuid` in the response with the [report GET endpoint](../reference/get-reports-request_uuid) to poll for the status and report URL upon completion. The retrieved report will be generated in a JSON format. scope: `company_reports:write` - [Get a salary estimate](https://docs.gusto.com/embedded-payroll/reference/get-v1-salary_estimates-id.md): 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` - [Search for BLS occupations](https://docs.gusto.com/embedded-payroll/reference/get-v1-salary_estimates-occupations.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `salary_estimates:read` - [Create a salary estimate for an employee](https://docs.gusto.com/embedded-payroll/reference/post-v1-employees-employee_id-salary_estimates.md): 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` - [Accept a salary estimate](https://docs.gusto.com/embedded-payroll/reference/post-v1-salary_estimates-uuid-accept.md): 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` - [Update a salary estimate](https://docs.gusto.com/embedded-payroll/reference/put-v1-salary_estimates-id.md): 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` - [Get all time off policies for a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_uuid-time_off_policies.md): Get all time off policies for a company scope: `time_off_policies:read` - [Get a time off policy](https://docs.gusto.com/embedded-payroll/reference/get-v1-time_off_policies-time_off_policy_uuid.md): Get a time off policy scope: `time_off_policies:read` - [Create a time off policy](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_uuid-time_off_policies.md): Create a time off policy scope: `time_off_policies:write` - [Add employees to a time off policy](https://docs.gusto.com/embedded-payroll/reference/put-v1-time_off_policies-time_off_policy_uuid-add_employees.md): 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` - [Update employee time off balances](https://docs.gusto.com/embedded-payroll/reference/put-v1-time_off_policies-time_off_policy_uuid-balance.md): Updates time off hours balances for employees for a time off policy. scope: `time_off_policies:write` - [Update a time off policy](https://docs.gusto.com/embedded-payroll/reference/put-v1-time_off_policies-time_off_policy_uuid.md): Update a time off policy scope: `time_off_policies:write` - [Calculate accruing time off hours](https://docs.gusto.com/embedded-payroll/reference/post-v1-payrolls-payroll_id-calculate_accruing_time_off_hours.md): 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` - [Deactivate a time off policy](https://docs.gusto.com/embedded-payroll/reference/put-v1-time_off_policies-time_off_policy_uuid-deactivate.md): Deactivate a time off policy scope: `time_off_policies:write` - [Remove employees from a time off policy](https://docs.gusto.com/embedded-payroll/reference/put-v1-time_off_policies-time_off_policy_uuid-remove_employees.md): Remove employees from a time off policy scope: `time_off_policies:write` - [Delete a time off request](https://docs.gusto.com/embedded-payroll/reference/delete-v1-time_off-requests-time_off_request_uuid.md): Delete a time off request scope: `time_off_requests:write` - [Get time off balances for a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_uuid-time_off-balances.md): Get time off balances for all employees in a company scope: `time_off_requests:read` - [List time off requests for a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_uuid-time_off-requests.md): Get all time off requests for a company. Supports filtering by status, employee, and date ranges. Possible statuses: - `pending` — awaiting approval - `approved` — approved by an admin but not yet processed in a payroll - `declined` — declined by an admin - `consumed` — processed in a completed payroll Allowed values for `status`: pending, approved, declined, consumed. scope: `time_off_requests:read` - [Get a time off request](https://docs.gusto.com/embedded-payroll/reference/get-v1-time_off-requests-time_off_request_uuid.md): Get a single time off request by UUID scope: `time_off_requests:read` - [Create an admin-approved time off request](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_uuid-time_off-admin_approved_requests.md): Create a pre-approved time off request on behalf of an employee (admin or system initiated). The request is always created with approved status. scope: `time_off_requests:manage` - [Preview a time off request](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_uuid-time_off-requests-preview.md): Preview a time off request to see balance impact before creating scope: `time_off_requests:read` - [Create a time off request](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_uuid-time_off-requests.md): Create a time off request for an employee scope: `time_off_requests:write` - [Approve a time off request](https://docs.gusto.com/embedded-payroll/reference/put-v1-time_off-requests-time_off_request_uuid-approve.md): Approve a pending time off request. Optionally override the dates and hours. Only requests with a `pending` status can be approved. Attempting to approve a request that has already been `declined` or `consumed` will fail with a 422 error. scope: `time_off_requests:manage` - [Decline a time off request](https://docs.gusto.com/embedded-payroll/reference/put-v1-time_off-requests-time_off_request_uuid-decline.md): Decline a pending or approved time off request. Requires an employer_note. scope: `time_off_requests:manage` - [Get info about the current access token](https://docs.gusto.com/embedded-payroll/reference/get-v1-token-info.md): 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 - [Create a System Access Token or Refresh an Access Token](https://docs.gusto.com/embedded-payroll/reference/oauth-access-token.md): Creates a system access token or refreshes an oauth access token - [What's new in v2026-06-15](https://docs.gusto.com/embedded-payroll/reference/whats-new-in-v2026-06-15.md) - [Delete an employee's home address](https://docs.gusto.com/embedded-payroll/reference/delete-v1-home_addresses-home_address_uuid.md): Used for deleting an employee's home address. Cannot delete the employee's active home address. scope: `employees:write` - [Delete an employee's work address](https://docs.gusto.com/embedded-payroll/reference/delete-v1-work_addresses-work_address_uuid.md): Used for deleting an employee's work address. Cannot delete the employee's active work address. scope: `employees:manage` - [Get an employee's home addresses](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-home_addresses.md): 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 an employee's work addresses](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-work_addresses.md): 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 an employee's home address](https://docs.gusto.com/embedded-payroll/reference/get-v1-home_addresses-home_address_uuid.md): 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 an employee work address](https://docs.gusto.com/embedded-payroll/reference/get-v1-work_addresses-work_address_uuid.md): The work address of an employee is used for payroll tax purposes. scope: `employees:read` - [Create an employee's home address](https://docs.gusto.com/embedded-payroll/reference/post-v1-employees-employee_id-home_addresses.md): 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` - [Create an employee work address](https://docs.gusto.com/embedded-payroll/reference/post-v1-employees-employee_id-work_addresses.md): The work address of an employee describes when an employee began working at an associated company location. scope: `employees:manage` - [Update an employee's home address](https://docs.gusto.com/embedded-payroll/reference/put-v1-home_addresses-home_address_uuid.md): 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` - [Update an employee work address](https://docs.gusto.com/embedded-payroll/reference/put-v1-work_addresses-work_address_uuid.md): The work address of an employee is used for payroll tax purposes. scope: `employees:manage` - [Delete an employee benefit](https://docs.gusto.com/embedded-payroll/reference/delete-v1-employee_benefits-employee_benefit_id.md): 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` - [Get year-to-date benefit amounts from a different company](https://docs.gusto.com/embedded-payroll/reference/get-employee-ytd-benefit-amounts-from-different-company.md): 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 an employee benefit](https://docs.gusto.com/embedded-payroll/reference/get-v1-employee_benefits-employee_benefit_id.md): 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 all benefits for an employee](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-employee_benefits.md): 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 all Section 603 high earner statuses for an employee](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_uuid-section603_high_earner_statuses-1.md): 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 a Section 603 high earner status for a specific year](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_uuid-section603_high_earner_statuses-effective_year-1.md): 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` - [Update a Section 603 high earner status](https://docs.gusto.com/embedded-payroll/reference/patch-v1-employees-employee_uuid-section603_high_earner_statuses-effective_year-1.md): 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` - [Create year-to-date benefit amounts from a different company](https://docs.gusto.com/embedded-payroll/reference/post-employee-ytd-benefit-amounts-from-different-company.md): 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` - [Create an employee benefit](https://docs.gusto.com/embedded-payroll/reference/post-v1-employees-employee_id-employee_benefits.md): 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` - [Create a Section 603 high earner status](https://docs.gusto.com/embedded-payroll/reference/post-v1-employees-employee_uuid-section603_high_earner_statuses-1.md): 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` - [Update an employee benefit](https://docs.gusto.com/embedded-payroll/reference/put-v1-employee_benefits-employee_benefit_id.md): 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` - [Delete an employee rehire](https://docs.gusto.com/embedded-payroll/reference/delete-v1-employees-employee_id-rehire.md): Delete an employee rehire. An employee rehire cannot be deleted if it's active (past effective date). scope: `employments:write` - [Delete an employee termination](https://docs.gusto.com/embedded-payroll/reference/delete-v1-employees-employee_id-terminations.md): Delete an employee termination. scope: `employments:write` - [Get employment history for an employee](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-employment_history.md): Retrieve the employment history for a given employee, which includes termination and rehire. scope: `employments:read` - [Get an employee rehire](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-rehire.md): Retrieve an employee's rehire, which contains information on when the employee returns to work. scope: `employments:read` - [Get terminations for an employee](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-terminations.md): 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 an employee termination](https://docs.gusto.com/embedded-payroll/reference/get-v1-terminations-employee_id.md): 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` - [Create an employee rehire](https://docs.gusto.com/embedded-payroll/reference/post-v1-employees-employee_id-rehire.md): Rehire is created whenever an employee is scheduled to return to the company. scope: `employments:write` - [Create an employee termination](https://docs.gusto.com/embedded-payroll/reference/post-v1-employees-employee_id-terminations.md): 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` - [Update an employee rehire](https://docs.gusto.com/embedded-payroll/reference/put-v1-employees-employee_id-rehire.md): Update an employee's rehire. scope: `employments:write` - [Update an employee termination](https://docs.gusto.com/embedded-payroll/reference/put-v1-terminations-employee_id.md): 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` - [Get the employee form pdf](https://docs.gusto.com/embedded-payroll/reference/get-v1-employee-form-pdf.md): Get the link to the employee form PDF scope: `employee_forms:read` - [Get an employee form](https://docs.gusto.com/embedded-payroll/reference/get-v1-employee-form.md): Get an employee form scope: `employee_forms:read` - [Get all employee forms](https://docs.gusto.com/embedded-payroll/reference/get-v1-employee-forms.md): Get a list of all employee's forms scope: `employee_forms:read` - [Generate a W2 form [DEMO]](https://docs.gusto.com/embedded-payroll/reference/post-v1-sandbox-generate_w2.md): > 🚧 Demo action > > This action is only available in the Demo environment Generates a W2 document for testing purposes. scope: `employees:write` - [Sign an employee form](https://docs.gusto.com/embedded-payroll/reference/put-v1-employee-form-sign.md): Sign an employee form. The optional preparer attributes are only valid for I-9 form. When a preparer is used, the first name, last name, street address, city, state, and zip for that preparer are all required. scope: `employee_forms:sign` - [Delete an employee bank account](https://docs.gusto.com/embedded-payroll/reference/delete-v1-employees-employee_id-bank_accounts-bank_account_id.md): Deletes an employee bank account. To update an employee's bank account details, delete the bank account first and create a new one. scope: `employee_payment_methods:write` - [List employee bank accounts](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-bank_accounts.md): Returns all employee bank accounts. scope: `employee_payment_methods:read` - [Get payment method for an employee](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-payment_method.md): Returns the payment method for an employee (e.g. Check or Direct Deposit with split configuration). scope: `employee_payment_methods:read` - [Create an employee bank account](https://docs.gusto.com/embedded-payroll/reference/post-v1-employees-employee_id-bank_accounts.md): Creates an employee bank account. An employee can have multiple bank accounts. Note that creating an employee bank account will also update the employee's payment method. scope: `employee_payment_methods:write` - [Update an employee bank account](https://docs.gusto.com/embedded-payroll/reference/put-v1-employees-employee_id-bank_accounts.md): Updates an employee bank account. scope: `employee_payment_methods:write` - [Update payment method for an employee](https://docs.gusto.com/embedded-payroll/reference/put-v1-employees-employee_id-payment_method.md): Updates the payment method for an employee. Can set to Check or Direct Deposit with split configuration. scope: `employee_payment_methods:write` - [Get federal taxes for an employee](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-federal_taxes.md): Returns federal tax information for an employee. The response structure varies based on the w4_data_type (pre_2020_w4 or rev_2020_w4). scope: `employee_federal_taxes:read` - [Get an employee's state taxes](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-state_taxes.md): Get attributes relevant for an employee's state taxes. The data required to correctly calculate an employee's state taxes varies by both home and work location. This API returns information about each question that must be answered grouped by state. Mostly commonly, an employee lives and works in the same state and will only have questions for a single state. The response contains metadata about each question, the type of answer expected, and the current answer stored in Gusto for that question. Answers are represented by an array. Today, this array can only be empty or contain exactly one element, but is designed to allow for forward compatibility with effective-dated fields. The `valid_from` and `valid_up_to` fields are optional and currently ignored. ## About filing new hire reports Payroll Admins are responsible for filing a new hire report for each Employee. The `file_new_hire_report` question will only be listed if: - the `employee.onboarding_status` is one of the following: - `admin_onboarding_incomplete` - `self_onboarding_awaiting_admin_review` - that employee's work state requires filing a new hire report scope: `employee_state_taxes:read` - [Update federal taxes for an employee](https://docs.gusto.com/embedded-payroll/reference/put-v1-employees-employee_id-federal_taxes.md): Updates federal tax (W4) information for an employee. Only rev_2020_w4 format is accepted for updates. scope: `employee_federal_taxes:write` - [Update an employee's state taxes](https://docs.gusto.com/embedded-payroll/reference/put-v1-employees-employee_id-state_taxes.md): Update attributes relevant for an employee's state taxes. As described for the GET endpoint, the answers must be supplied in the effective-dated format, but currently only a single answer will be accepted. The `valid_from` and `valid_up_to` fields are optional and currently ignored. scope: `employee_state_taxes:write` - [Delete an onboarding employee](https://docs.gusto.com/embedded-payroll/reference/delete-v1-employee.md): 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` - [Get employee payment details for a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-employees-payment_details.md): Fetches payment details for employees in a given company. Results are paginated. Use the `employee_uuid` query parameter to filter for a single employee. Use the `payroll_uuid` query parameter to filter for employees on a specific payroll. Providing both `employee_uuid` and `payroll_uuid` will result in a 422 error. An empty array is returned if the company has no employees or if no employees match the filter criteria. The `encrypted_account_number` in the `splits` array is only visible if the `employee_payment_methods:read:account_number` scope is present. scope: `employee_payment_methods:read` - [Get employees of a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-employees.md): 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 an employee's custom fields](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-custom_fields.md): Returns a list of the employee's custom fields. scope: `employees:read` - [Get the employee's onboarding status](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-onboarding_status.md): # Description Retrieves an employee's onboarding status. The data returned helps inform the required onboarding steps and respective completion status. ## onboarding_status ### Admin-facilitated onboarding | onboarding_status | Description | |:------------------|------------:| | `admin_onboarding_incomplete` | Admin needs to complete the full employee-onboarding. | | `onboarding_completed` | Employee has been fully onboarded and verified. | ### Employee self-onboarding | onboarding_status | Description | |:------------------|------------:| | `admin_onboarding_incomplete` | Admin needs to enter basic information about the employee. | | `self_onboarding_pending_invite` | Admin has the intention to invite the employee to self-onboard (e.g., marking a checkbox), but the system has not yet sent the invitation. | | `self_onboarding_invited` | Employee has been sent an invitation to self-onboard. | | `self_onboarding_invited_started` | Employee has started the self-onboarding process. | | `self_onboarding_invited_overdue` | Employee's start date has passed, and employee has still not completed self-onboarding. | | `self_onboarding_completed_by_employee` | Employee has completed entering in their information. The status should be updated via API to "self_onboarding_awaiting_admin_review" from here, once the Admin has started reviewing. | | `self_onboarding_awaiting_admin_review` | Admin has started to verify the employee's information. | | `onboarding_completed` | Employee has been fully onboarded and verified. | ## onboarding_steps | onboarding_steps | Requirement(s) to be completed | |:-----------------|-------------------------------:| | `personal_details` | Add employee's first name, last name, email, date of birth, social security number | | `compensation_details` | Associate employee to a job & compensation. | | `add_work_address` | Add employee work address. | | `add_home_address` | Add employee home address. | | `federal_tax_setup` | Set up federal tax withholdings. | | `state_tax_setup` | Set up state tax withholdings. | | `direct_deposit_setup` | (optional) Set up employee's direct deposit. | | `employee_form_signing` | Employee forms (e.g., W4, direct deposit authorization) are generated & signed. | | `file_new_hire_report` | File a new hire report for this employee. | | `admin_review` | Admin reviews & confirms employee details (only required for Employee self-onboarding) | scope: `employees:read` - [Get an employee](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees.md): 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 employee time off activities](https://docs.gusto.com/embedded-payroll/reference/get-version-employees-time_off_activities.md): Get employee time off activities. scope: `employee_time_off_activities:read` - [Create an employee](https://docs.gusto.com/embedded-payroll/reference/post-v1-employees.md): Create an employee. scope: `employees:manage` - [Create a historical employee](https://docs.gusto.com/embedded-payroll/reference/post-v1-historical_employees.md): Create a historical employee, an employee that was previously dismissed from the company in the current year. scope: `employees:manage` - [Update employee onboarding documents config](https://docs.gusto.com/embedded-payroll/reference/put-v1-employees-employee_id-onboarding_documents_config.md): Indicate whether to include the Form I-9 for an employee during the onboarding process. If included, the employee will be prompted to complete Form I-9 as part of their onboarding. ## Related guides - [Employee onboarding](doc:employee-onboarding) scope: `employees:manage` - [Update the employee's onboarding status](https://docs.gusto.com/embedded-payroll/reference/put-v1-employees-employee_id-onboarding_status.md): Updates an employee's onboarding status. Below is a list of valid onboarding status changes depending on the intended action to be performed on behalf of the employee. | Action | current onboarding_status | new onboarding_status | |:------------------|:------------:|----------:| | Mark an employee as self-onboarding | `admin_onboarding_incomplete` | `self_onboarding_pending_invite` | | Invite an employee to self-onboard | `admin_onboarding_incomplete` or `self_onboarding_pending_invite` | `self_onboarding_invited` | | Cancel an employee's self-onboarding | `self_onboarding_invited` or `self_onboarding_pending_invite` | `admin_onboarding_incomplete` | | Review an employee's self-onboarded info | `self_onboarding_completed_by_employee` | `self_onboarding_awaiting_admin_review` | | Finish an employee's onboarding | `admin_onboarding_incomplete` or `self_onboarding_awaiting_admin_review` | `onboarding_completed` | scope: `employees:manage` - [Update an employee.](https://docs.gusto.com/embedded-payroll/reference/put-v1-employees.md): Update an employee. scope: `employees:write` - [Update a historical employee](https://docs.gusto.com/embedded-payroll/reference/put-v1-historical_employees.md): Update a historical employee, an employee that was previously dismissed from the company in the current year. scope: `employees:manage employees:write` - [Get garnishments for an employee](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-garnishments.md): 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 child support garnishment data](https://docs.gusto.com/embedded-payroll/reference/get-v1-garnishments-child_support.md): Agency data and requirements to be used for creating child support garnishments scope: `garnishments:read` - [Get a garnishment](https://docs.gusto.com/embedded-payroll/reference/get-v1-garnishments-garnishment_id.md): 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` - [Create a garnishment](https://docs.gusto.com/embedded-payroll/reference/post-v1-employees-employee_id-garnishments.md): 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` - [Update a garnishment](https://docs.gusto.com/embedded-payroll/reference/put-v1-garnishments-garnishment_id.md): 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` - [Delete an employee's I-9 verification document](https://docs.gusto.com/embedded-payroll/reference/delete-v1-employees-employee_id-i9_authorization-documents-document_id.md): An employee's I-9 verification documents are the documents an employee has provided the employer to verify their identity and authorization to work in the United States. This endpoint deletes a specific verification document. ### Related guides - [I-9 employment verification](doc:i-9-employment-verification) scope: `i9_authorizations:manage` - [Get an employee's I-9 verification document options](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-i9_authorization-document_options.md): An employee's I-9 verification documents are the documents an employee has provided the employer to verify their identity and authorization to work in the United States. This endpoint returns the possible document options based on the employee's authorization status. These options can then be used to create the I-9 verification documents. ### Related guides - [I-9 employment verification](doc:i-9-employment-verification) scope: `i9_authorizations:read` - [Get an employee's I-9 verification documents](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-i9_authorization-documents.md): An employee's I-9 verification documents are the documents an employee has provided the employer to verify their identity and authorization to work in the United States. ### Related guides - [I-9 employment verification](doc:i-9-employment-verification) scope: `i9_authorizations:read` - [Get an employee's I-9 authorization](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-i9_authorization.md): An employee's I-9 authorization stores information about an employee's authorization status and I-9 signatures, information required to fill out the Form I-9 for employment eligibility verification. **NOTE:** The `form_uuid` in responses from this endpoint can be used to retrieve the PDF version of the I-9. See the "get employee form PDF" request for more details. ### Related guides - [I-9 employment verification](doc:i-9-employment-verification) scope: `i9_authorizations:read` - [Create an employee's I-9 authorization verification documents](https://docs.gusto.com/embedded-payroll/reference/put-v1-employees-employee_id-i9_authorization-documents.md): An employee's I-9 verification documents are the documents an employee has provided the employer to verify their identity and authorization to work in the United States. Use the [document options endpoint](ref:get-v1-employees-employee_id-i9_authorization-document_options) to get the possible document types and titles, which can vary depending on the employee's authorization status. > 🚧 Every request must contain the complete list of documents for the Employee. > > Every request to this endpoint removes any previous verification document records for the employee. ### Related guides - [I-9 employment verification](doc:i-9-employment-verification) scope: `i9_authorizations:manage` - [Employer sign an employee's Form I-9](https://docs.gusto.com/embedded-payroll/reference/put-v1-employees-employee_id-i9_authorization-employer_sign.md): Sign an employee's Form I-9 as an employer. Once the form is signed, the employee's I-9 authorization is considered complete and cannot be modified. ### Prerequisites Before calling this endpoint: 1. The employee must have a completed [I-9 authorization](ref:put-v1-employees-employee_id-i9_authorization) 2. The employee must have signed the Form I-9 3. [I-9 verification documents](ref:put-v1-employees-employee_id-i9_authorization-documents) must be submitted ### Related guides - [I-9 employment verification](doc:i-9-employment-verification) scope: `i9_authorizations:manage` - [Create or update an employee's I-9 authorization](https://docs.gusto.com/embedded-payroll/reference/put-v1-employees-employee_id-i9_authorization.md): An employee's I-9 authorization stores information about an employee's authorization status, as well as signatures and other information required to complete the Form I-9 for employment eligibility verification. If the version is supplied and the employee I-9 authorization exists, this endpoint acts as an update. Otherwise, it will create an employee I-9 authorization. Validations on this endpoint are conditional: * `document_type` may be required, depending on `authorization_status`. * Valid formats for `document_number` vary, depending on `document_type`. * `country` is only allowed with `document_type: 'foreign_passport'`. * `expiration_date` is only allowed with `authorization_status: 'alien'`. > ℹ️ Unneeded information is automatically removed during updates. > > If an update causes some formerly-required fields to be unneeded, the now-unneeded data will be removed automatically. > > **Example:** Updating `authorization_status` from `alien` to `citizen` will cause any data in `document_type`, `document_number`, `country`, and `expiration_date` to be removed, since these fields are unused for `authorization_status:'citizen'`. Detailed instructions for completing Form I-9 can be found at https://www.uscis.gov/sites/default/files/document/forms/i-9instr.pdf ### Related guides - [I-9 employment verification](doc:i-9-employment-verification) scope: `i9_authorizations:write` - [Delete a compensation](https://docs.gusto.com/embedded-payroll/reference/delete-v1-compensations-compensation_id.md): 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 an individual job](https://docs.gusto.com/embedded-payroll/reference/delete-v1-jobs-job_id.md): Deletes a specific job that an employee holds. scope: `jobs:write` - [Get a compensation](https://docs.gusto.com/embedded-payroll/reference/get-v1-compensations-compensation_id.md): 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 jobs for an employee](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-jobs.md): Get all of the jobs that an employee holds. Note: Compensation data (pay rate, payment unit, and related fields) represents sensitive employee pay information. When retrieving employee job data, these fields (`rate`, `payment_unit`, `current_compensation_uuid`, `compensations`) are only returned when the `compensations:read` scope is included. This allows you to access employee and job metadata without exposing pay rates. Compensation data in the response requires the `compensations:read` scope. scope: `jobs:read` - [Get compensations for a job](https://docs.gusto.com/embedded-payroll/reference/get-v1-jobs-job_id-compensations.md): 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 a job](https://docs.gusto.com/embedded-payroll/reference/get-v1-jobs-job_id.md): Get a job. Note: Compensation data (pay rate, payment unit, and related fields) represents sensitive employee pay information. When retrieving employee job data, these fields (`rate`, `payment_unit`, `current_compensation_uuid`, `compensations`) are only returned when the `compensations:read` scope is included. This allows you to access employee and job metadata without exposing pay rates. Compensation data in the response requires the `compensations:read` scope. scope: `jobs:read` - [Create a compensation](https://docs.gusto.com/embedded-payroll/reference/post-v1-compensations-compensation_id.md): Compensations contain information on how much is paid out for a job. Jobs may have many compensations, but only one that is active. The current compensation is the one with the most recent `effective_date`. ### Prerequisites Before calling this endpoint: 1. A [job](ref:post-v1-jobs-job_id) must exist for the employee ### Webhooks - `employee_job_compensation.created`: Fires when a compensation is successfully created scope: `compensations:write` - [Create a job](https://docs.gusto.com/embedded-payroll/reference/post-v1-employees-employee_id-jobs.md): Create a job. scope: `jobs:write` - [Update a compensation](https://docs.gusto.com/embedded-payroll/reference/put-v1-compensations-compensation_id.md): 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` - [Update a job](https://docs.gusto.com/embedded-payroll/reference/put-v1-jobs-job_id.md): Update a job. scope: `jobs:write` - [Delete a webhook subscription](https://docs.gusto.com/embedded-payroll/reference/delete-v1-webhook-subscription-uuid.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `webhook_subscriptions:write` - [Get a webhook subscription](https://docs.gusto.com/embedded-payroll/reference/get-v1-webhook-subscription-uuid.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `webhook_subscriptions:read` - [Request a verification token for a webhook subscription](https://docs.gusto.com/embedded-payroll/reference/get-v1-webhook-subscription-verification-token-uuid.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `webhook_subscriptions:read` - [List webhook subscriptions](https://docs.gusto.com/embedded-payroll/reference/get-v1-webhook-subscriptions.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `webhook_subscriptions:read` - [Get the webhooks health status](https://docs.gusto.com/embedded-payroll/reference/get-v1-webhooks-health_check.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `webhook_subscriptions:read` - [Create a webhook subscription](https://docs.gusto.com/embedded-payroll/reference/post-v1-webhook-subscription.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `webhook_subscriptions:write` - [Verify a webhook subscription](https://docs.gusto.com/embedded-payroll/reference/put-v1-verify-webhook-subscription-uuid.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `webhook_subscriptions:write` - [Update a webhook subscription](https://docs.gusto.com/embedded-payroll/reference/put-v1-webhook-subscription-uuid.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `webhook_subscriptions:write` - [Get all Wire In Requests for a company](https://docs.gusto.com/embedded-payroll/reference/get-companies-company_uuid-wire_in_request_uuid.md): Fetches all Wire In Requests for a company. scope: `payrolls:read` - [Get a single Wire In Request](https://docs.gusto.com/embedded-payroll/reference/get-wire_in_requests-wire_in_request_uuid.md): Fetch a Wire In Request. scope: `payrolls:read` - [Submit a wire in request](https://docs.gusto.com/embedded-payroll/reference/put-wire_in_requests-wire_in_request_uuid.md): Submit a wire in request for a payment scope: `payrolls:run` ## Pages - [API Policy](https://docs.gusto.com/embedded-payroll/api-policy.md) - [API Status](https://docs.gusto.com/embedded-payroll/api-status.md) - [Security at Gusto](https://docs.gusto.com/embedded-payroll/security-at-gusto.md) ## Changelog - [v2024-04-01 Sunset](https://docs.gusto.com/embedded-payroll/changelog/v2024-04-01-sunset.md) - [v2026-02-01 Deprecation](https://docs.gusto.com/embedded-payroll/changelog/v2026-02-01-deprecation.md) - [v2026-06-15](https://docs.gusto.com/embedded-payroll/changelog/v2026-06-15.md) - [Added payroll.deleted webhook](https://docs.gusto.com/embedded-payroll/changelog/added-payrolldeleted-webhook.md) - [Added Payroll Digests API for multi-company payroll monitoring](https://docs.gusto.com/embedded-payroll/changelog/added-payroll-digests-api-for-multi-company-payroll-monitoring.md) # App Integrations Documentation ## Guides - [Getting Setup](https://docs.gusto.com/app-integrations/docs/getting-setup.md) - [API Versioning](https://docs.gusto.com/app-integrations/docs/api-versioning.md) - [Version Upgrade Guide](https://docs.gusto.com/app-integrations/docs/version-upgrade-guide.md) - [Authentication](https://docs.gusto.com/app-integrations/docs/authentication.md) - [OAuth2](https://docs.gusto.com/app-integrations/docs/oauth2.md) - [Strict Access](https://docs.gusto.com/app-integrations/docs/strict-access.md) - [System Access Tokens](https://docs.gusto.com/app-integrations/docs/system-access-tokens.md) - [Error Categories](https://docs.gusto.com/app-integrations/docs/error-categories.md) - [App Integrations vs. Gusto Embedded](https://docs.gusto.com/app-integrations/docs/app-integrations-vs-embedded-payroll.md) - [Introduction](https://docs.gusto.com/app-integrations/docs/introduction.md) - [Security Review](https://docs.gusto.com/app-integrations/docs/security-review.md) - [Pagination](https://docs.gusto.com/app-integrations/docs/pagination.md) - [Rate Limits](https://docs.gusto.com/app-integrations/docs/rate-limits.md) - [Scopes](https://docs.gusto.com/app-integrations/docs/scopes.md) - [Bank Account Events](https://docs.gusto.com/app-integrations/docs/bank-account-events.md) - [Best Practices](https://docs.gusto.com/app-integrations/docs/best-practices.md) - [Company Benefit Events](https://docs.gusto.com/app-integrations/docs/company-benefit-events.md) - [Company Events](https://docs.gusto.com/app-integrations/docs/company-events.md) - [Contractor Events](https://docs.gusto.com/app-integrations/docs/contractor-events.md) - [Contractor Payment Events](https://docs.gusto.com/app-integrations/docs/contractor-payment-events.md) - [Employee Benefit Events](https://docs.gusto.com/app-integrations/docs/employee-benefit-events.md) - [Employee Events](https://docs.gusto.com/app-integrations/docs/employee-events.md) - [Employee Home Address Events](https://docs.gusto.com/app-integrations/docs/employee-home-address-events.md) - [Employee Job Compensation Events](https://docs.gusto.com/app-integrations/docs/employee-job-compensation-events.md) - [Employee Work Address Events](https://docs.gusto.com/app-integrations/docs/employee-work-address-events.md) - [External Payroll Events](https://docs.gusto.com/app-integrations/docs/external-payroll-events.md) - [Fast Ach Config Events](https://docs.gusto.com/app-integrations/docs/fast-ach-config-events.md) - [Form Events](https://docs.gusto.com/app-integrations/docs/form-events.md) - [Webhooks](https://docs.gusto.com/app-integrations/docs/webhooks.md): Efficiently integrate Gusto's real-time event data into your application - [Location Events](https://docs.gusto.com/app-integrations/docs/location-events.md) - [Pay Schedule Events](https://docs.gusto.com/app-integrations/docs/pay-schedule-events.md) - [Payroll Events](https://docs.gusto.com/app-integrations/docs/payroll-events.md) - [Signatory Events](https://docs.gusto.com/app-integrations/docs/signatory-events.md) - [Webhook Events](https://docs.gusto.com/app-integrations/docs/webhook-events.md) - [Contact Gusto](https://docs.gusto.com/app-integrations/docs/contact-gusto-1.md) - [Gusto Experience Principles](https://docs.gusto.com/app-integrations/docs/gusto-experience-principles.md) - [Jobs and Compensations](https://docs.gusto.com/app-integrations/docs/jobs-and-compensations.md) - [Syncing Employees](https://docs.gusto.com/app-integrations/docs/syncing-employees.md) - [Syncing Time Tracking Data](https://docs.gusto.com/app-integrations/docs/syncing-time-tracking-data.md) - [Payrolls](https://docs.gusto.com/app-integrations/docs/updating-payrolls.md) ## API Reference - [Get a single contractor payment](https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-contractor_payment-contractor-payment.md): Returns a single contractor payment. scope: `payrolls:read` - [Get contractor payments for a company](https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-contractor_payments.md): 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` - [List contractor payment details](https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-contractors-payment_details.md): Get payment details for contractors in a company. This endpoint returns a list of all contractors associated with the specified company, including their payment methods and bank account details if they are paid via direct deposit. For contractors paid by direct deposit, the response includes their bank account information with sensitive data masked for security. The payment details also include information about how their payments are split if they have multiple bank accounts configured. For contractors paid by check, only the basic payment method information is returned. ### Response Details - For direct deposit contractors: - Bank account details (masked) - Payment splits configuration - Routing numbers - Account types - For check payments: - Basic payment method designation ### Common Use Cases - Fetching contractor payment information for payroll processing - Verifying contractor payment methods - Reviewing payment split configurations `encrypted_account_number` is available only with the additional scope `contractor_payment_methods:read:account_numbers`. scope: `contractor_payment_methods:read` - [Get contractors of a company](https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_uuid-contractors.md): Get all contractors, active and inactive, individual and business, for a company. scope: `contractors:read` - [Get a contractor](https://docs.gusto.com/app-integrations/reference/get-v1-contractors-contractor_uuid.md): Get a contractor. scope: `contractors:read` - [Create a contractor](https://docs.gusto.com/app-integrations/reference/post-v1-companies-company_uuid-contractors.md): Create an individual or business contractor. scope: `contractors:manage` - [Update a contractor](https://docs.gusto.com/app-integrations/reference/put-v1-contractors-contractor_uuid.md): 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` - [Get all the admins at a company](https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-admins.md): Returns a list of all the admins at a company scope: `company_admin:read` - [Get the custom fields of a company](https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-custom_fields.md): 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 a company](https://docs.gusto.com/app-integrations/reference/get-v1-companies.md): 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` - [Create a company](https://docs.gusto.com/app-integrations/reference/post-v1-provision.md): ### 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](https://docs.gusto.com/embedded-payroll/docs/system-access). 📘 System Access Authentication This endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `accounts:write` - [Update a company](https://docs.gusto.com/app-integrations/reference/put-v1-companies.md): Update a company. scope: `companies:write` - [Delete a company benefit](https://docs.gusto.com/app-integrations/reference/delete-v1-company_benefits-company_benefit_id.md): 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` - [Get a supported benefit](https://docs.gusto.com/app-integrations/reference/get-v1-benefits-benefit_id.md): 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 benefit fields requirements by benefit type](https://docs.gusto.com/app-integrations/reference/get-v1-benefits-benefits_id-requirements.md): Returns the field requirements for a given benefit type. scope: `benefits:read` - [Get company benefit summary by company benefit id.](https://docs.gusto.com/app-integrations/reference/get-v1-benefits-company_benefit_id-summary.md): 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 all supported benefits](https://docs.gusto.com/app-integrations/reference/get-v1-benefits.md): 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 benefits for a company](https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-company_benefits.md): 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 contribution exclusions for a company benefit](https://docs.gusto.com/app-integrations/reference/get-v1-company_benefits-company_benefit_id-contribution_exclusions.md): 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 all employee benefits for a company benefit](https://docs.gusto.com/app-integrations/reference/get-v1-company_benefits-company_benefit_id-employee_benefits.md): 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 a company benefit](https://docs.gusto.com/app-integrations/reference/get-v1-company_benefits-company_benefit_id.md): 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` - [Create a company benefit](https://docs.gusto.com/app-integrations/reference/post-v1-companies-company_id-company_benefits.md): 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` - [Update contribution exclusions for a company benefit](https://docs.gusto.com/app-integrations/reference/put-v1-company_benefits-company_benefit_id-contribution_exclusions.md): 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` - [Bulk update employee benefits for a company benefit](https://docs.gusto.com/app-integrations/reference/put-v1-company_benefits-company_benefit_id-employee_benefits.md): 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` - [Update a company benefit](https://docs.gusto.com/app-integrations/reference/put-v1-company_benefits-company_benefit_id.md): 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` - [Delete a department](https://docs.gusto.com/app-integrations/reference/delete-department.md): Delete a department. You cannot delete a department until all employees and contractors have been removed. scope: `departments:write` - [Get all departments of a company](https://docs.gusto.com/app-integrations/reference/get-companies-departments.md): Get all of the departments for a given company with the employees and contractors assigned to that department. scope: `departments:read` - [Get a department](https://docs.gusto.com/app-integrations/reference/get-department.md): Get a department given the UUID scope: `departments:read` - [Create a department](https://docs.gusto.com/app-integrations/reference/post-departments.md): Create a department scope: `departments:write` - [Add people to a department](https://docs.gusto.com/app-integrations/reference/put-add-people-to-department.md): Add employees and contractors to a department scope: `departments:write` - [Update a department](https://docs.gusto.com/app-integrations/reference/put-departments.md): Update a department scope: `departments:write` - [Remove people from a department](https://docs.gusto.com/app-integrations/reference/put-remove-people-from-department.md): Remove employees and contractors from a department scope: `departments:write` - [Deactivate an earning type](https://docs.gusto.com/app-integrations/reference/delete-v1-companies-company_id-earning_types-earning_type_uuid.md): Deactivate an earning type. scope: `payrolls:write` - [Get all earning types for a company](https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-earning_types.md): 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` - [Create a custom earning type](https://docs.gusto.com/app-integrations/reference/post-v1-companies-company_id-earning_types.md): 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` - [Update an earning type](https://docs.gusto.com/app-integrations/reference/put-v1-companies-company_id-earning_types-earning_type_uuid.md): Update an earning type. scope: `payrolls:write` - [Get all company locations](https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-locations.md): Retrieves all company locations (addresses) associated with a company: mailing addresses, filing addresses, or work locations. A single address may serve multiple, or all, purposes. Since all company locations are subsets of locations, use the Locations endpoints to [get](ref:get-v1-locations-location_id) or [update](ref:put-v1-locations-location_id) an individual record. scope: `companies:read` - [Get a location](https://docs.gusto.com/app-integrations/reference/get-v1-locations-location_id.md): Get a location. scope: `companies:read` - [Get minimum wages for a location](https://docs.gusto.com/app-integrations/reference/get-v1-locations-location_uuid-minimum_wages.md): Get minimum wages for a location scope: `companies:read` - [Create a company location](https://docs.gusto.com/app-integrations/reference/post-v1-companies-company_id-locations.md): Create a company location, which represents any address associated with a company: mailing addresses, filing addresses, or work locations. A single address may serve multiple, or all, purposes. Since all company locations are subsets of locations, use the Locations endpoints to [get](ref:get-v1-locations-location_id) or [update](ref:put-v1-locations-location_id) an individual record. scope: `companies:write` - [Update a location](https://docs.gusto.com/app-integrations/reference/put-v1-locations-location_id.md): Update a location. scope: `companies:write` - [Get pay periods for a company](https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-pay_periods.md): Pay periods are the foundation of payroll. Compensation, time & attendance, taxes, and expense reports all rely on when they happened. To begin submitting information for a given payroll, we need to agree on the time period. By default, this endpoint returns pay periods starting from 6 months ago to the date today. Use the `start_date` and `end_date` parameters to change the scope of the response. End dates can be up to 3 months in the future and there is no limit on start dates. Starting in version 2023-04-01, the `eligible_employees` attribute was removed from the response. The eligible employees for a payroll are determined by the employee_compensations returned from the [PUT /v1/companies/{company_id}/payrolls/{payroll_id}/prepare](ref:put-v1-companies-company_id-payrolls-payroll_id-prepare) endpoint. scope: `payrolls:read` - [Get pay schedule assignments for a company](https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-pay_schedules-assignments.md): 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 a pay schedule](https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-pay_schedules-pay_schedule_id.md): 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 the pay schedules for a company](https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-pay_schedules.md): 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 termination pay periods for a company](https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-unprocessed_termination_pay_periods.md): 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 a single payroll](https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-payrolls-payroll_id.md): 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 all payrolls for a company](https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-payrolls.md): 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` - [Prepare a payroll for update](https://docs.gusto.com/app-integrations/reference/put-v1-companies-company_id-payrolls-payroll_id-prepare.md): Prepares an unprocessed payroll for update, including: adding or removing eligible employees from the payroll, and updating `check_date`, `payroll_deadline`, and `payroll_status_meta` dates and times. Use this endpoint before calling [PUT /v1/companies/{company_id}/payrolls/{payroll_id}](ref:put-v1-companies-company_id-payrolls). ### Notes * Nullifies `calculated_at` and `totals` if the payroll was previously calculated * Returns the `version` parameter required for [updating the payroll](ref:put-v1-companies-company_id-payrolls) * `employees:read` scope is required to include employee compensations data in the response. * Results are paginated, with a maximum page size of 100 employee compensations. scope: `payrolls:write employees:read` - [Update a payroll by ID](https://docs.gusto.com/app-integrations/reference/put-v1-companies-company_id-payrolls.md): 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` - [Get time off requests for a company](https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-time_off_requests.md): 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` - [Delete a time sheet](https://docs.gusto.com/app-integrations/reference/delete-time_tracking-time_sheets-time_sheet_uuid.md): 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` - [Get all time sheets for a company](https://docs.gusto.com/app-integrations/reference/get-companies-company_uuid-time_tracking-time_sheets.md): 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 a payroll sync](https://docs.gusto.com/app-integrations/reference/get-time_tracking-payroll_syncs-payroll_sync_uuid.md): 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 a time sheet](https://docs.gusto.com/app-integrations/reference/get-time_tracking-time_sheets-time_sheet_uuid.md): 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` - [Create a payroll sync](https://docs.gusto.com/app-integrations/reference/post-companies-company_uuid-time_tracking-payroll_syncs.md): 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](ref:post-v1-webhook-subscription)) to `PayrollSync` webhook events scope: `payroll_syncs:write` - [Create a time sheet](https://docs.gusto.com/app-integrations/reference/post-companies-company_uuid-time_tracking-time_sheets.md): 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` - [Update a time sheet](https://docs.gusto.com/app-integrations/reference/put-time_tracking-time_sheets-time_sheet_uuid.md): 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` - [Get an employee termination](https://docs.gusto.com/app-integrations/reference/get-v1-terminations-employee_id.md): 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 info about the current access token](https://docs.gusto.com/app-integrations/reference/get-v1-token-info.md): 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 - [Create a System Access Token or Refresh an Access Token](https://docs.gusto.com/app-integrations/reference/oauth-access-token.md): Creates a system access token or refreshes an oauth access token - [Disconnect an app integration](https://docs.gusto.com/app-integrations/reference/post-v1-disconnect-app-integration.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `companies:disconnect_app_integration` - [Revoke access token](https://docs.gusto.com/app-integrations/reference/revoke-access-token.md): Revokes the given access token. After revoking, this token can no longer be used to make requests nor can it be refreshed. - [Get notifications for company](https://docs.gusto.com/app-integrations/reference/get-company-notifications.md): Returns all notifications relevant for the given company. scope: `notifications:read` - [Get all time off policies for a company](https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_uuid-time_off_policies.md): Get all time off policies for a company scope: `time_off_policies:read` - [Get a time off policy](https://docs.gusto.com/app-integrations/reference/get-v1-time_off_policies-time_off_policy_uuid.md): Get a time off policy scope: `time_off_policies:read` - [Calculate accruing time off hours](https://docs.gusto.com/app-integrations/reference/post-v1-payrolls-payroll_id-calculate_accruing_time_off_hours.md): 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` - [Add employees to a time off policy](https://docs.gusto.com/app-integrations/reference/put-v1-time_off_policies-time_off_policy_uuid-add_employees.md): 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` - [Get a report](https://docs.gusto.com/app-integrations/reference/get-reports-request_uuid.md): 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` - [Create a general ledger report](https://docs.gusto.com/app-integrations/reference/post-payrolls-payroll_uuid-reports-general_ledger.md): Create a general ledger report for a payroll. The report can be aggregated by different dimensions such as job or department. Use the `request_uuid` in the response with the [report GET endpoint](../reference/get-reports-request_uuid) to poll for the status and report URL upon completion. The retrieved report will be generated in a JSON format. scope: `company_reports:write` - [Create an employees annual FICA wage report](https://docs.gusto.com/app-integrations/reference/post-v1-companies-company_id-reports-employees_annual_fica_wage.md): Generates a report containing annual FICA (Federal Insurance Contributions Act) wage data for all employees in a company over a specified year range. This report provides detailed wage information subject to Social Security and Medicare taxes, useful for benefits integrations that need to verify employee earnings for compliance and benefit calculations. The report is generated asynchronously. After making this request, you will receive a `request_uuid` which can be used to poll the [Get a report](ref:get-v1-reports-request_uuid) endpoint to check the status and retrieve the report when complete. scope: `company_reports:write` - [Delete an employee's home address](https://docs.gusto.com/app-integrations/reference/delete-v1-home_addresses-home_address_uuid.md): Used for deleting an employee's home address. Cannot delete the employee's active home address. scope: `employees:write` - [Delete an employee's work address](https://docs.gusto.com/app-integrations/reference/delete-v1-work_addresses-work_address_uuid.md): Used for deleting an employee's work address. Cannot delete the employee's active work address. scope: `employees:manage` - [Get an employee's home addresses](https://docs.gusto.com/app-integrations/reference/get-v1-employees-employee_id-home_addresses.md): 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 an employee's work addresses](https://docs.gusto.com/app-integrations/reference/get-v1-employees-employee_id-work_addresses.md): 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 an employee's home address](https://docs.gusto.com/app-integrations/reference/get-v1-home_addresses-home_address_uuid.md): 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 an employee work address](https://docs.gusto.com/app-integrations/reference/get-v1-work_addresses-work_address_uuid.md): The work address of an employee is used for payroll tax purposes. scope: `employees:read` - [Create an employee's home address](https://docs.gusto.com/app-integrations/reference/post-v1-employees-employee_id-home_addresses.md): 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` - [Create an employee work address](https://docs.gusto.com/app-integrations/reference/post-v1-employees-employee_id-work_addresses.md): The work address of an employee describes when an employee began working at an associated company location. scope: `employees:manage` - [Update an employee's home address](https://docs.gusto.com/app-integrations/reference/put-v1-home_addresses-home_address_uuid.md): 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` - [Update an employee work address](https://docs.gusto.com/app-integrations/reference/put-v1-work_addresses-work_address_uuid.md): The work address of an employee is used for payroll tax purposes. scope: `employees:manage` - [Delete an employee benefit](https://docs.gusto.com/app-integrations/reference/delete-v1-employee_benefits-employee_benefit_id.md): 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` - [Get year-to-date benefit amounts from a different company](https://docs.gusto.com/app-integrations/reference/get-employee-ytd-benefit-amounts-from-different-company.md): 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 an employee benefit](https://docs.gusto.com/app-integrations/reference/get-v1-employee_benefits-employee_benefit_id.md): 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 all benefits for an employee](https://docs.gusto.com/app-integrations/reference/get-v1-employees-employee_id-employee_benefits.md): 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 a Section 603 high earner status for a specific year](https://docs.gusto.com/app-integrations/reference/get-v1-employees-employee_uuid-section603_high_earner_statuses-effective_year.md): 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 all Section 603 high earner statuses for an employee](https://docs.gusto.com/app-integrations/reference/get-v1-employees-employee_uuid-section603_high_earner_statuses.md): 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` - [Update a Section 603 high earner status](https://docs.gusto.com/app-integrations/reference/patch-v1-employees-employee_uuid-section603_high_earner_statuses-effective_year.md): 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` - [Create year-to-date benefit amounts from a different company](https://docs.gusto.com/app-integrations/reference/post-employee-ytd-benefit-amounts-from-different-company.md): 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` - [Create an employee benefit](https://docs.gusto.com/app-integrations/reference/post-v1-employees-employee_id-employee_benefits.md): 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` - [Create a Section 603 high earner status](https://docs.gusto.com/app-integrations/reference/post-v1-employees-employee_uuid-section603_high_earner_statuses.md): 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` - [Update an employee benefit](https://docs.gusto.com/app-integrations/reference/put-v1-employee_benefits-employee_benefit_id.md): 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` - [Delete an employee rehire](https://docs.gusto.com/app-integrations/reference/delete-v1-employees-employee_id-rehire.md): Delete an employee rehire. An employee rehire cannot be deleted if it's active (past effective date). scope: `employments:write` - [Delete an employee termination](https://docs.gusto.com/app-integrations/reference/delete-v1-employees-employee_id-terminations.md): Delete an employee termination. scope: `employments:write` - [Get employment history for an employee](https://docs.gusto.com/app-integrations/reference/get-v1-employees-employee_id-employment_history.md): Retrieve the employment history for a given employee, which includes termination and rehire. scope: `employments:read` - [Get an employee rehire](https://docs.gusto.com/app-integrations/reference/get-v1-employees-employee_id-rehire.md): Retrieve an employee's rehire, which contains information on when the employee returns to work. scope: `employments:read` - [Get terminations for an employee](https://docs.gusto.com/app-integrations/reference/get-v1-employees-employee_id-terminations.md): 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` - [Create an employee rehire](https://docs.gusto.com/app-integrations/reference/post-v1-employees-employee_id-rehire.md): Rehire is created whenever an employee is scheduled to return to the company. scope: `employments:write` - [Create an employee termination](https://docs.gusto.com/app-integrations/reference/post-v1-employees-employee_id-terminations.md): 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` - [Update an employee rehire](https://docs.gusto.com/app-integrations/reference/put-v1-employees-employee_id-rehire.md): Update an employee's rehire. scope: `employments:write` - [Update an employee termination](https://docs.gusto.com/app-integrations/reference/put-v1-terminations-employee_id.md): 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` - [Delete an onboarding employee](https://docs.gusto.com/app-integrations/reference/delete-v1-employee.md): 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` - [Get employees of a company](https://docs.gusto.com/app-integrations/reference/get-v1-companies-company_id-employees.md): 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 an employee's custom fields](https://docs.gusto.com/app-integrations/reference/get-v1-employees-employee_id-custom_fields.md): Returns a list of the employee's custom fields. scope: `employees:read` - [Get an employee](https://docs.gusto.com/app-integrations/reference/get-v1-employees.md): 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 employee time off activities](https://docs.gusto.com/app-integrations/reference/get-version-employees-time_off_activities.md): Get employee time off activities. scope: `employee_time_off_activities:read` - [Create an employee](https://docs.gusto.com/app-integrations/reference/post-v1-employees.md): Create an employee. scope: `employees:manage` - [Update an employee.](https://docs.gusto.com/app-integrations/reference/put-v1-employees.md): Update an employee. scope: `employees:write` - [Get garnishments for an employee](https://docs.gusto.com/app-integrations/reference/get-v1-employees-employee_id-garnishments.md): 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 child support garnishment data](https://docs.gusto.com/app-integrations/reference/get-v1-garnishments-child_support.md): Agency data and requirements to be used for creating child support garnishments scope: `garnishments:read` - [Get a garnishment](https://docs.gusto.com/app-integrations/reference/get-v1-garnishments-garnishment_id.md): 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` - [Create a garnishment](https://docs.gusto.com/app-integrations/reference/post-v1-employees-employee_id-garnishments.md): 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` - [Update a garnishment](https://docs.gusto.com/app-integrations/reference/put-v1-garnishments-garnishment_id.md): 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` - [Delete a compensation](https://docs.gusto.com/app-integrations/reference/delete-v1-compensations-compensation_id.md): 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` - [Get a compensation](https://docs.gusto.com/app-integrations/reference/get-v1-compensations-compensation_id.md): 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 compensations for a job](https://docs.gusto.com/app-integrations/reference/get-v1-jobs-job_id-compensations.md): 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` - [Create a compensation](https://docs.gusto.com/app-integrations/reference/post-v1-compensations-compensation_id.md): Compensations contain information on how much is paid out for a job. Jobs may have many compensations, but only one that is active. The current compensation is the one with the most recent `effective_date`. ### Prerequisites Before calling this endpoint: 1. A [job](ref:post-v1-jobs-job_id) must exist for the employee ### Webhooks - `employee_job_compensation.created`: Fires when a compensation is successfully created scope: `compensations:write` - [Update a compensation](https://docs.gusto.com/app-integrations/reference/put-v1-compensations-compensation_id.md): 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` - [Delete a recurring reimbursement](https://docs.gusto.com/app-integrations/reference/delete-v1-recurring_reimbursements.md): Delete (soft delete) a recurring reimbursement for an employee. scope: `reimbursements:write` - [Get recurring reimbursements for an employee](https://docs.gusto.com/app-integrations/reference/get-v1-employees-employee_id-recurring_reimbursements.md): Get all active recurring reimbursements for an employee. scope: `reimbursements:read` - [Get a recurring reimbursement](https://docs.gusto.com/app-integrations/reference/get-v1-recurring_reimbursements.md): Get a specific recurring reimbursement. scope: `reimbursements:read` - [Create a recurring reimbursement](https://docs.gusto.com/app-integrations/reference/post-v1-employees-employee_id-recurring_reimbursements.md): Create a recurring reimbursement for an employee. scope: `reimbursements:write` - [Update a recurring reimbursement](https://docs.gusto.com/app-integrations/reference/put-v1-recurring_reimbursements.md): Update a recurring reimbursement. scope: `reimbursements:write` - [Get a salary estimate](https://docs.gusto.com/app-integrations/reference/get-v1-salary_estimates-id.md): 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` - [Search for BLS occupations](https://docs.gusto.com/app-integrations/reference/get-v1-salary_estimates-occupations.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `salary_estimates:read` - [Create a salary estimate for an employee](https://docs.gusto.com/app-integrations/reference/post-v1-employees-employee_id-salary_estimates.md): 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` - [Accept a salary estimate](https://docs.gusto.com/app-integrations/reference/post-v1-salary_estimates-uuid-accept.md): 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` - [Update a salary estimate](https://docs.gusto.com/app-integrations/reference/put-v1-salary_estimates-id.md): 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` - [Get all events](https://docs.gusto.com/app-integrations/reference/get-events.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `events:read` - [Delete a webhook subscription](https://docs.gusto.com/app-integrations/reference/delete-v1-webhook-subscription-uuid.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `webhook_subscriptions:write` - [Get a webhook subscription](https://docs.gusto.com/app-integrations/reference/get-v1-webhook-subscription-uuid.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `webhook_subscriptions:read` - [Request a verification token for a webhook subscription](https://docs.gusto.com/app-integrations/reference/get-v1-webhook-subscription-verification-token-uuid.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `webhook_subscriptions:read` - [List webhook subscriptions](https://docs.gusto.com/app-integrations/reference/get-v1-webhook-subscriptions.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `webhook_subscriptions:read` - [Get the webhooks health status](https://docs.gusto.com/app-integrations/reference/get-v1-webhooks-health_check.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `webhook_subscriptions:read` - [Create a webhook subscription](https://docs.gusto.com/app-integrations/reference/post-v1-webhook-subscription.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `webhook_subscriptions:write` - [Verify a webhook subscription](https://docs.gusto.com/app-integrations/reference/put-v1-verify-webhook-subscription-uuid.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `webhook_subscriptions:write` - [Update a webhook subscription](https://docs.gusto.com/app-integrations/reference/put-v1-webhook-subscription-uuid.md): 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](https://docs.gusto.com/embedded-payroll/docs/system-access) scope: `webhook_subscriptions:write` ## Changelog - [v2024-04-01 Sunset](https://docs.gusto.com/app-integrations/changelog/v2024-04-01-sunset.md) - [v2026-02-01 Deprecation](https://docs.gusto.com/app-integrations/changelog/v2026-02-01-deprecation.md) - [v2026-06-15](https://docs.gusto.com/app-integrations/changelog/v2026-06-15.md) - [May, 2026](https://docs.gusto.com/app-integrations/changelog/may-2026.md) - [April, 2026](https://docs.gusto.com/app-integrations/changelog/april-2026.md)