# Embedded Payroll Documentation > Documentation for Embedded Payroll ## Guides: Getting started - [Introduction](https://docs.gusto.com/embedded-payroll/docs/introduction.md) - [Platform overview](https://docs.gusto.com/embedded-payroll/docs/platform-overview.md) - [Quickstart](https://docs.gusto.com/embedded-payroll/docs/quickstart.md): Get started with Gusto Embedded in under 5 minutes - [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. - [Payroll fundamentals](https://docs.gusto.com/embedded-payroll/docs/payroll-fundamentals.md) ## Guides: Developer tools - [Authentication and authorization](https://docs.gusto.com/embedded-payroll/docs/authentication-and-authorization.md) - [Postman](https://docs.gusto.com/embedded-payroll/docs/postman.md): Learn how to set up and maintain your Postman environment - [API versioning](https://docs.gusto.com/embedded-payroll/docs/api-versioning.md): Understanding Gusto date-based versioning - [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 - [Version upgrade guide](https://docs.gusto.com/embedded-payroll/docs/version-upgrade-guide.md) - [API fundamentals](https://docs.gusto.com/embedded-payroll/docs/api-fundamentals.md): Learn about the Gusto API, including pagination, rate limits, and scopes - [Errors](https://docs.gusto.com/embedded-payroll/docs/errors.md) - [Error Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories.md) - [Webhooks](https://docs.gusto.com/embedded-payroll/docs/webhooks.md) - [Best Practices](https://docs.gusto.com/embedded-payroll/docs/best-practices.md) - [Webhook Events](https://docs.gusto.com/embedded-payroll/docs/webhook-events.md) - [Bank Account Events](https://docs.gusto.com/embedded-payroll/docs/bank-account-events.md) - [Company Events](https://docs.gusto.com/embedded-payroll/docs/company-events.md) - [Company Benefit Events](https://docs.gusto.com/embedded-payroll/docs/company-benefit-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) - [Employee Events](https://docs.gusto.com/embedded-payroll/docs/employee-events.md) - [Employee Home Address Events](https://docs.gusto.com/embedded-payroll/docs/home-address-events.md) - [Employee Work Address Events](https://docs.gusto.com/embedded-payroll/docs/work-address-events.md) - [Employee Benefit Events](https://docs.gusto.com/embedded-payroll/docs/employee-benefit-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) - [Document Events](https://docs.gusto.com/embedded-payroll/docs/document-events.md) - [Generated Document Events](https://docs.gusto.com/embedded-payroll/docs/generated-document-events.md) - [Location Events](https://docs.gusto.com/embedded-payroll/docs/location-events.md) - [Member Portal Invitation Events](https://docs.gusto.com/embedded-payroll/docs/member-portal-invitation-events.md) - [Notification Events](https://docs.gusto.com/embedded-payroll/docs/notification-events.md) - [Payroll Events](https://docs.gusto.com/embedded-payroll/docs/payroll-events.md) - [Pay Schedule Events](https://docs.gusto.com/embedded-payroll/docs/pay-schedule-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) - [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 - [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. ## Guides: Build options - [Introduction](https://docs.gusto.com/embedded-payroll/docs/build-options-introduction.md): Learn about the available options for building with Gusto Embedded Payroll - [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 - [Gusto Flows (pre-built UI)](https://docs.gusto.com/embedded-payroll/docs/gusto-flows-pre-built-ui.md) - [Flows quickstart](https://docs.gusto.com/embedded-payroll/docs/flows-quickstart.md) - [Customize flows](https://docs.gusto.com/embedded-payroll/docs/customize-flows.md) - [Flow types](https://docs.gusto.com/embedded-payroll/docs/flow-types.md) - [Try it now](https://docs.gusto.com/embedded-payroll/docs/try-it-now.md) - [Flow events](https://docs.gusto.com/embedded-payroll/docs/flow-events.md) ## Guides: Companies - [Introduction](https://docs.gusto.com/embedded-payroll/docs/companies-intro.md): Integrate company and employee-related data, and streamline operations - [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 - [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 - [Manage company bank accounts](https://docs.gusto.com/embedded-payroll/docs/manage-company-bank-accounts.md) - [Create company benefits](https://docs.gusto.com/embedded-payroll/docs/create-company-benefits.md) - [Company forms](https://docs.gusto.com/embedded-payroll/docs/company-form.md) - [Manage company attachments](https://docs.gusto.com/embedded-payroll/docs/manage-company-attachments.md) - [Create a department](https://docs.gusto.com/embedded-payroll/docs/create-a-department.md) - [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 ## Guides: People management - [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 - [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) - [Employee self-onboarding](https://docs.gusto.com/embedded-payroll/docs/employee-self-management.md): Enable employees to self-onboard into a company - [Adjust for minimum wage](https://docs.gusto.com/embedded-payroll/docs/adjust-for-minimum-wage.md) - [Configure employee tax information](https://docs.gusto.com/embedded-payroll/docs/configure-employee-tax-information.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) - [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 - [Terminate a W2 Employee](https://docs.gusto.com/embedded-payroll/docs/terminate-a-w2-employee.md) - [Manage recurring reimbursements](https://docs.gusto.com/embedded-payroll/docs/manage-recurring-reimbursements.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 - [Manage employee benefits](https://docs.gusto.com/embedded-payroll/docs/manage-employee-benefits.md): Create and view the benefits assigned to an employee - [Benefit effective dating](https://docs.gusto.com/embedded-payroll/docs/benefit-effective-dating.md) - [People Batch API](https://docs.gusto.com/embedded-payroll/docs/people-batch-api.md): Create batches of employees in a single request - [Create a people batch](https://docs.gusto.com/embedded-payroll/docs/create-people-batch.md) - [Person data](https://docs.gusto.com/embedded-payroll/docs/people-data.md) - [Home address](https://docs.gusto.com/embedded-payroll/docs/home-address.md) - [Work address](https://docs.gusto.com/embedded-payroll/docs/work-address.md) - [Job](https://docs.gusto.com/embedded-payroll/docs/job.md) - [Compensation](https://docs.gusto.com/embedded-payroll/docs/compensation.md) - [Bank accounts and direct deposit splits](https://docs.gusto.com/embedded-payroll/docs/bank-accounts-and-direct-deposit-splits.md) - [Department information](https://docs.gusto.com/embedded-payroll/docs/department-information.md) - [ Get the status of a people batch](https://docs.gusto.com/embedded-payroll/docs/get-people-batch-status.md) - [People batch webhooks](https://docs.gusto.com/embedded-payroll/docs/webhook.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 - [Pay contractors](https://docs.gusto.com/embedded-payroll/docs/process-contractor-payments.md): Set up payments to 1099 workers - [Contractor Payment Receipts](https://docs.gusto.com/embedded-payroll/docs/contractor-payment-receipts.md) - [Contractor payment group submission blockers](https://docs.gusto.com/embedded-payroll/docs/contractor-payment-group-submission-blockers.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 forms](https://docs.gusto.com/embedded-payroll/docs/contractor-forms-guide.md) - [Contractor documents](https://docs.gusto.com/embedded-payroll/docs/contractor-documents-guide.md) - [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 - [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 - [Accrual methods](https://docs.gusto.com/embedded-payroll/docs/accrual-methods.md) - [Time off management flow](https://docs.gusto.com/embedded-payroll/docs/time-off-management-flow.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 ## Guides: Payrolls - [Payroll Processing Speeds](https://docs.gusto.com/embedded-payroll/docs/2-day-vs-4-day.md) - [Recovery Cases](https://docs.gusto.com/embedded-payroll/docs/recovery-cases-1.md) - [Complete a Regular Payroll](https://docs.gusto.com/embedded-payroll/docs/complete-a-regular-payroll.md) - [Payroll Statuses](https://docs.gusto.com/embedded-payroll/docs/payroll-statuses.md) - [Payroll Receipts](https://docs.gusto.com/embedded-payroll/docs/payroll-receipts.md) - [Payroll Blockers](https://docs.gusto.com/embedded-payroll/docs/payroll-blockers.md) - [Payroll Submission Blockers & Unblock Options](https://docs.gusto.com/embedded-payroll/docs/payroll-submission-blockers-unblock-options.md) - [Payroll Processing Request](https://docs.gusto.com/embedded-payroll/docs/payroll-processing-request.md) - [Payroll by Workweek](https://docs.gusto.com/embedded-payroll/docs/payroll-by-workweek.md) - [Parallelize Payroll Updates](https://docs.gusto.com/embedded-payroll/docs/parallelize-payroll-updates.md): Cut update time on large-roster payrolls by splitting the work across concurrent requests. - [Pay Schedules](https://docs.gusto.com/embedded-payroll/docs/pay-schedule-info.md) - [Create a pay schedule](https://docs.gusto.com/embedded-payroll/docs/create-a-pay-schedule.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 - [Batch Payroll Cancellation API](https://docs.gusto.com/embedded-payroll/docs/bulk-payroll-cancellations.md): Cancel multiple payrolls for companies ## Guides: Reports - [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) ## Guides: ACH TRANSACTIONS - [ACH Codes and Transaction Types](https://docs.gusto.com/embedded-payroll/docs/ach-codes-and-transaction-types.md) ## Guides: Product Partnerships - [Health Insurance (SimplyInsured)](https://docs.gusto.com/embedded-payroll/docs/health-insurance-simplyinsured.md) - [Workers' Compensation (NEXT)](https://docs.gusto.com/embedded-payroll/docs/workers-compensation-next.md) - [401(k) (Guideline)](https://docs.gusto.com/embedded-payroll/docs/401k-guideline.md) - [Accounting integrations (Xero and QuickBooks Online)](https://docs.gusto.com/embedded-payroll/docs/testing-accounting-integrations-xero-and-qbo.md) ## API Reference: Versions - [What's new in v2026-06-15](https://docs.gusto.com/embedded-payroll/reference/whats-new-in-v2026-06-15.md) ## API Reference: Token - Introspection - [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 - [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… ## API Reference: Flows (Pre-built UI) - Flows - [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… ## API Reference: Companies - People Batches - [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` - [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` - Companies - [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… - [Disassociate a partner managed company](https://docs.gusto.com/embedded-payroll/reference/put-v1-partner-managed-companies-company-uuid-disassociate.md): Disassociate a company from your embedded payroll product, reversing an earlier association or migration. You can only disassociate a company that is currently associated with your application. 📘… - [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… - [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… - [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… - [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` - [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 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… - [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… - [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)… - [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` - [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 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:… - [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… - [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 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… - [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… - Bank Accounts - [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… - [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` - [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… - [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… - [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` - Locations - [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.… - [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… - [Get a location](https://docs.gusto.com/embedded-payroll/reference/get-v1-locations-location_id.md): Get a location. scope: `companies:read` - [Update a location](https://docs.gusto.com/embedded-payroll/reference/put-v1-locations-location_id.md): Update a location. scope: `companies:write` - [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` - Payment Configs - [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.… - [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… - Company Forms - [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` - [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 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` - [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` - Company Benefits - [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… - [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… - [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… - [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… - [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… - [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… - [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,… - [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 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… - [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… - [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 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` - [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` - Federal Tax Details - [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… - Industry Selection - [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… - Tax Requirements - [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… - [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… - [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… - Tax Payments - [Get all tax payments for a company](https://docs.gusto.com/embedded-payroll/reference/get-tax-payments.md): Fetches all tax payments Gusto has made (or scheduled) to tax agencies on behalf of a company. scope: `tax_payments:read` - [Get a tax payment for a company](https://docs.gusto.com/embedded-payroll/reference/get-tax-payment.md): Fetches a single tax payment by UUID, including the payroll tax liabilities that make up the payment. scope: `tax_payments:read` - Reverse Wire Transactions - [Get all reverse wire transactions for a company](https://docs.gusto.com/embedded-payroll/reference/get-reverse-wire-transactions.md): Returns a paginated list of reverse wire (drawdown) transactions for a company. Reverse wires are debit transactions initiated by Gusto to pull funds from a partner's bank account to cover payroll or… - Company Attachment - [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 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 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,… - Signatories - [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… - [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)… - [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… - [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` - Departments - [Create a department](https://docs.gusto.com/embedded-payroll/reference/post-departments.md): Create a department 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` - [Update a department](https://docs.gusto.com/embedded-payroll/reference/put-departments.md): Update a department scope: `departments:write` - [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` - [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` - [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` ## API Reference: W2 Employees - Employee Tax Setup - [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` - [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` - [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… - [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… - Employee Payment Method - [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:… - [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` - [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` - [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` - [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` - [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` - Employee Employments - [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… - [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… - [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… - [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` - [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… - [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` - [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` - [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` - [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` - [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` - Employee Addresses - [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… - [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… - [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… - [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… - [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` - [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` - [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` - [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` - [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'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` - Jobs and Compensations - [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,… - [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`,… - [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 job](https://docs.gusto.com/embedded-payroll/reference/put-v1-jobs-job_id.md): Update a job. scope: `jobs: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 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… - [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… - [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… - [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… - [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… - I-9 Verification - [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.… - [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… - [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… - [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… - [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… - [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… - [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:… - Employee Forms - [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` - [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` - [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 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` - [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… - Employees - [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.… - [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` - [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… - [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 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`,… - [Update an employee.](https://docs.gusto.com/embedded-payroll/reference/put-v1-employees.md): Update an employee. scope: `employees: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… - [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` - [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… - [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… - [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… - [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` - Employee Benefits - [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… - [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… - [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… - [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… - [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… - [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… - [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… - [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… - [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… - [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… - [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… - Garnishments - [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… - [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… - [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… - [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… - [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` ## API Reference: 1099 Contractors - Contractor Payment Groups - [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` - [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` - [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… - [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` - [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` - [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… - [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` - Contractor Payment Method - [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:… - [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` - [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` - Contractor Documents - [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` - [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 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` - [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` - Contractor Payments - [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… - [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… - [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` - [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:… - [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` - [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` - [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` - [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… - [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:… - [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` - Contractor Forms - [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` - [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 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` - [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` - Contractors - [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` - [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](https://docs.gusto.com/embedded-payroll/reference/get-v1-contractors-contractor_uuid.md): Get a contractor. scope: `contractors:read` - [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… - [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 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 |… - [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… - [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` - [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. > >… - [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… - [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… - [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… - [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… ## API Reference: Payrolls - Payroll Cancellations - [Create a payroll cancellation batch](https://docs.gusto.com/embedded-payroll/reference/post-v1-payroll_batches.md): Cancels up to 100 payrolls across one or more companies the partner is mapped to, asynchronously. The batch is processed asynchronously. Use the returned batch UUID to poll `GET… - [Get a payroll cancellation batch](https://docs.gusto.com/embedded-payroll/reference/get-v1-payroll_batches-payroll_batch_uuid.md): Returns the status and per-payroll results of a payroll cancellation batch. Poll this endpoint until the batch `status` reaches a terminal value (`completed` or `failed`). Once terminal, the… - Payroll Digests - [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.… - [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… - Pay Schedules - [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… - [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:… - [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… - [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:… - [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… - [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… - [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… - [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` - [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` - [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.… - Earning Types - [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` - [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… - [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` - [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` - External Payrolls - [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` - [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 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` - [Delete an external payroll](https://docs.gusto.com/embedded-payroll/reference/delete-v1-external-payroll.md): Delete an external payroll. 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` - [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 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` - [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` - [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… - Payrolls - [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… - [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,… - [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 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… - [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… - [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… - [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 eligible employees to off-cycle payrolls that support multiple employees (`Bonus`, `Correction`, and `Adhoc`), and updating `check_date`,… - [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… - [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](https://docs.gusto.com/embedded-payroll/docs/payroll-blockers) for a complete list of… - [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… - [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… - [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.… - [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… - [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… - [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.… - [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` - [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 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` - [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` ## API Reference: Events - Events - [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… ## API Reference: Webhooks - Webhooks - [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… - [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… - [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… - [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… - [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… - [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… - [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… - [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… ## API Reference: NOTIFICATIONS - Notifications - [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… - [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` ## API Reference: Time Off Policies - Time Off Policies - [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` - [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` - [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` - [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` - [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` - [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… - [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` - [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:… - [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` ## API Reference: Holiday Pay Policies - Holiday Pay Policies - [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` - [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` - [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` - [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` - [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:… ## API Reference: Time Off Requests - Time Off Requests - [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` - [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… - [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` - [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` - [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` - [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` - [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`… - [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` ## API Reference: Generated Documents - Generated Documents - [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.… ## API Reference: Reports - Reports - [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… - [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… - [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… - [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… - [Create a bulk report batch](https://docs.gusto.com/embedded-payroll/reference/post-v1-bulk_reports.md): Triggers asynchronous generation of up to 25 reports across companies the partner is mapped to. Each `batch` item is a `custom_report` (same parameters as [create a custom… - [Get a bulk report batch](https://docs.gusto.com/embedded-payroll/reference/get-v1-bulk_reports-request_uuid.md): Get a bulk report batch's status and results given the `request_uuid`. While in progress, only batch metadata is returned; once complete, it also includes a signed `report_url` (a zip of all… - [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… ## API Reference: Invoices - Invoices - [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 and have… ## API Reference: Recovery cases - Recovery Cases - [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… ## API Reference: ACH Transactions - ACH Transactions - [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` ## API Reference: Wire in Requests - Wire In Requests - [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` - [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` ## API Reference: Information Requests - Information Requests - [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` ## API Reference: Reimbursements - Reimbursements - [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` - [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` - [Get a recurring reimbursement](https://docs.gusto.com/embedded-payroll/reference/get-v1-recurring_reimbursements.md): Get a specific recurring reimbursement. scope: `reimbursements:read` - [Update a recurring reimbursement](https://docs.gusto.com/embedded-payroll/reference/put-v1-recurring_reimbursements.md): Update a recurring reimbursement. scope: `reimbursements: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` ## API Reference: Salary estimates - Salary Estimates - [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… - [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` - [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… - [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.… - [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… ## API Reference: Member portal - Member Portal Invitations - [Create an employee member portal invitation](https://docs.gusto.com/embedded-payroll/reference/post-v1-employees-employee_id-member_portal_invitations.md): Generates a member portal invitation for the specified employee. If the employee already has an invitation that is not `complete`, calling this endpoint resends it with a new token, and the link from… - [Get an employee member portal invitation](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-member_portal_invitations.md): Returns the current status of an employee's member portal invitation (`pending`, `sent`, `verified`, `complete`, or `cancelled`) along with an `expired` flag indicating whether the invitation can… - [Cancel an employee member portal invitation](https://docs.gusto.com/embedded-payroll/reference/delete-v1-employees-employee_id-member_portal_invitations.md): Cancels the member portal invitation for the specified employee. Note: this endpoint does not cancel the employee's self-onboarding flow. If you want the company admin to take full control of… - [Create a contractor member portal invitation](https://docs.gusto.com/embedded-payroll/reference/post-v1-contractors-contractor_uuid-member_portal_invitations.md): Generates a member portal invitation for the specified contractor. If the contractor already has an invitation that is not `complete`, calling this endpoint resends it with a new token, and the link… - [Get a contractor member portal invitation](https://docs.gusto.com/embedded-payroll/reference/get-v1-contractors-contractor_uuid-member_portal_invitations.md): Returns the current status of a contractor's member portal invitation (`pending`, `sent`, `verified`, `complete`, or `cancelled`) along with an `expired` flag indicating whether the invitation can… - [Cancel a contractor member portal invitation](https://docs.gusto.com/embedded-payroll/reference/delete-v1-contractors-contractor_uuid-member_portal_invitations.md): Cancels the member portal invitation for the specified contractor. Note: this endpoint does not cancel the contractor's self-onboarding flow. If you want the company admin to take full control of… ## Pages - [API Policy](https://docs.gusto.com/embedded-payroll/page/api-policy.md) - [API Status](https://docs.gusto.com/embedded-payroll/page/api-status.md) - [Security at Gusto](https://docs.gusto.com/embedded-payroll/page/security-at-gusto.md) ## Changelog - [Added support for parallel payroll updates on large rosters](https://docs.gusto.com/embedded-payroll/changelog/added-support-for-parallel-payroll-updates-on-large-rosters.md) - [Added Payroll by Workweek support for earning types, pay schedules, and payrolls](https://docs.gusto.com/embedded-payroll/changelog/added-payroll-by-workweek-support-for-earning-types-pay-schedules-and-payrolls.md) - [11-02-26 Partner notification changes](https://docs.gusto.com/embedded-payroll/changelog/11-02-26-partner-notification-changes.md) - [Added validation for webhook subscription URLs](https://docs.gusto.com/embedded-payroll/changelog/return-422-for-invalid-or-inaccessible-webhook-subscription-urls.md) - [10-01-26 Partner notification changes](https://docs.gusto.com/embedded-payroll/changelog/10-01-26-partner-notification-changes.md) - [Added contractor lifecycle webhooks for future-dated transitions](https://docs.gusto.com/embedded-payroll/changelog/added-contractor-lifecycle-webhooks-for-future-dated-transitions.md) - [Filter tax payments by payroll](https://docs.gusto.com/embedded-payroll/changelog/filter-tax-payments-by-payroll.md) - [09-01-26 Partner notification changes](https://docs.gusto.com/embedded-payroll/changelog/09-01-26-partner-notification-changes.md) - [Added Tax Payments endpoints](https://docs.gusto.com/embedded-payroll/changelog/added-tax-payments-endpoints.md) - [Added work_email read and write for contractors](https://docs.gusto.com/embedded-payroll/changelog/added-work_email-read-and-write-for-contractors.md)