diff --git a/docs/build-methods/build-methods.md b/docs/build-methods/build-methods.md
new file mode 100644
index 000000000..bb03f020d
--- /dev/null
+++ b/docs/build-methods/build-methods.md
@@ -0,0 +1,40 @@
+---
+title: Build methods
+description: Three ways to build with the Gusto Embedded React SDK — workflows, sub-components, and hooks — and how to pick the right one for each surface.
+order: 0
+---
+
+# Build methods
+
+The SDK exposes the same payroll surfaces at three levels of integration depth. Each one trades control for effort: workflows do the most for you, hooks give you the most say.
+
+| Method | What you write | What the SDK handles | Customizable |
+| ------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------- |
+| [Workflows](./workflows.md) | A single component drop-in, plus IDs and an event handler | Step routing, data fetching, validation, submission, error handling, layout | Theming, copy, the surface's public props |
+| [Sub-components](./sub-components.md) | One component per step, wired together by your own routing | Data fetching, validation, submission, error handling, the step's own layout | The above, plus step order and which steps to include |
+| [Hooks](./hooks.md) | Your own layout, your own copy, your own field arrangement | Data fetching, validation, submission, error handling | Everything visual |
+
+## When to pick which
+
+**Pick a workflow when…**
+
+- You want a complete surface live as quickly as possible.
+- The default order of steps and the default copy work for the experience you're building.
+- You don't need to insert your own screens into the middle of the flow.
+
+**Pick sub-components when…**
+
+- You want to reorder, remove, or insert your own steps in between the SDK's steps.
+- You only need part of a surface — for example, an "Edit profile" page that reuses the Profile step without the rest of onboarding.
+- You're building a multi-step experience whose shape doesn't match any of the shipped workflows but whose individual steps do.
+
+**Pick hooks when…**
+
+- The default layout of a sub-component doesn't fit the design you need.
+- You want to control labels, helper text, field grouping, or where the submit button lives.
+- You're embedding fields into a form shell that's already part of your app (a side panel, a wizard with its own chrome, a multi-column layout).
+- You need to do something between validation and submission — e.g. show a confirmation step or capture additional data.
+
+## You can mix and match
+
+These methods aren't mutually exclusive across a single app — or even a single surface. A common pattern is to start with the workflow drop-in to get something shipping, then swap one or two steps out for sub-components or hooks as the design evolves. The data model and event shapes are consistent across all three layers, so moving down a level doesn't require rewriting how the rest of the app integrates.
diff --git a/docs/build-methods/hooks.md b/docs/build-methods/hooks.md
new file mode 100644
index 000000000..b817ef492
--- /dev/null
+++ b/docs/build-methods/hooks.md
@@ -0,0 +1,53 @@
+---
+title: Hooks
+description: Headless React hooks that handle data fetching, validation, submission, and error handling — you own the layout, copy, and ordering around them.
+order: 2
+---
+
+# Hooks
+
+Hooks are the headless layer of the SDK. They handle data fetching, validation, submission, and error handling, and hand back exactly what's needed to render a step — but no layout, no chrome, no fixed copy. You decide how the markup is arranged and what the labels say.
+
+Hooks are the deepest level of control the SDK exposes. Reach for them when [sub-components](./sub-components.md) don't give you enough say over layout or copy, when you need to slot fields into an existing form shell, or when you're building a screen that doesn't map cleanly onto a single sub-component.
+
+> Hooks are an experimental feature. APIs may change between minor versions during 0.x.x releases.
+
+## Two kinds of hooks
+
+- **Form hooks** return pre-bound Field components, form actions, and metadata. You arrange the fields, label them, and decide when to call submit. Validation, submission, and error handling are wired up for you.
+- **Data hooks** return fetched, decorated data plus the actions valid for it. You render it however you like.
+
+Both follow the same loading/error conventions: a discriminated `isLoading` union plus a shared `errorHandling` contract that surfaces server validation back into the form.
+
+## Example
+
+A form hook returns pre-bound Field components and a `handleSubmit` action — drop them into whatever layout you want:
+
+```jsx
+import { GustoProvider, useEmployeeDetailsForm } from '@gusto/embedded-react-sdk'
+
+function App({ companyId }) {
+ return (
+
+
+
+ )
+}
+
+function EmployeeDetails({ companyId }) {
+ const form = useEmployeeDetailsForm({ companyId })
+
+ if (form.isLoading) return null
+
+ return (
+
+ )
+}
+```
+
+See the [hooks reference](../hooks/hooks.md) for the full list of available form and data hooks, along with the return shape, props, and events for each.
diff --git a/docs/build-methods/sub-components.md b/docs/build-methods/sub-components.md
new file mode 100644
index 000000000..badfdae88
--- /dev/null
+++ b/docs/build-methods/sub-components.md
@@ -0,0 +1,42 @@
+---
+title: Sub-components
+description: The individual steps that make up each workflow — render them standalone or compose them into a custom multi-step experience.
+order: 1
+---
+
+# Sub-components
+
+Each workflow is assembled from a set of sub-components — Profile, Compensation, Federal Taxes, Documents, and so on. Every sub-component is also exported on its own, so you can render any single step in isolation or compose them into a multi-step experience of your own design.
+
+Sub-components sit between [workflows](./workflows.md) and [hooks](./hooks.md): more control than a workflow, less work than a fully headless hook integration. Reach for them when the built-in workflow's order or set of steps doesn't match what you want to render, or when you only need part of a surface (for example, an in-app "Edit profile" page that reuses the Profile step without the rest of onboarding).
+
+## What a sub-component gives you
+
+- A standalone React component for one logical step
+- The same data fetching, validation, and submission as the workflow uses
+- Step-level events on `onEvent` (entity created, entity updated, "done" with that step)
+- No assumption about what step comes next — that's yours to wire up
+
+## Example
+
+Render the Profile step in isolation:
+
+```jsx
+import { Employee } from '@gusto/embedded-react-sdk'
+
+function EditProfilePage({ companyId, employeeId }) {
+ return (
+ {
+ // Handle EMPLOYEE_PROFILE_DONE here to advance,
+ // close a modal, or refresh upstream state.
+ }}
+ />
+ )
+}
+```
+
+Each surface page lists every sub-component it exposes, the props each accepts, and the events each emits. For guidance on composing several sub-components into a custom multi-step flow, see the [composition guide](../integration-guide/composition.md).
diff --git a/docs/build-methods/workflows.md b/docs/build-methods/workflows.md
new file mode 100644
index 000000000..e2f335961
--- /dev/null
+++ b/docs/build-methods/workflows.md
@@ -0,0 +1,39 @@
+---
+title: Workflows
+description: Drop-in React components that render a complete multi-step Gusto Embedded experience end to end — routing, data fetching, validation, and error handling included.
+order: 0
+---
+
+# Workflows
+
+A workflow is a single React component that renders a complete multi-step experience end to end. It manages routing between steps, data fetching, validation, submission, and error handling internally. Supply IDs and an event handler — the workflow handles the rest.
+
+Workflows are the fastest way to ship a complete surface. The tradeoff is composition: the order and presence of steps is fixed, so reach for [sub-components](./sub-components.md) when you need to reorder, insert, or replace steps, and [hooks](./hooks.md) when you need to own the layout entirely.
+
+## What a workflow includes
+
+- A single component that mounts the full flow
+- Built-in step routing, including back/next behavior and conditional steps
+- Data fetching for every step from the Gusto API
+- Validation and submission for every step
+- A unified `onEvent` callback that fires at meaningful checkpoints (step completed, entity created, flow finished)
+
+## Example
+
+```jsx
+import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
+
+function EmployeeOnboardingPage({ companyId }) {
+ return (
+ {
+ // React to flow events — e.g. record analytics or
+ // navigate elsewhere when onboarding completes.
+ }}
+ />
+ )
+}
+```
+
+Each surface in the SDK ships a workflow. See the [Surfaces section](../surfaces/surfaces.mdx) for the full list, with the props and events each one accepts.
diff --git a/docs/customize/customize.mdx b/docs/customize/customize.mdx
new file mode 100644
index 000000000..c867649c5
--- /dev/null
+++ b/docs/customize/customize.mdx
@@ -0,0 +1,27 @@
+---
+title: Customize
+description: Tailor the SDK's visual appearance to your product — start with theming, then reach for the component adapter when you need to swap in your own primitives.
+order: 5
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The SDK ships with sensible visual defaults, but every surface — colors, typography, shadows, and the primitive components themselves — is customizable. Start with **theming** for the broadest set of changes, and reach for the **component adapter** when you need to replace SDK primitives with components from your own design system.
+
+
diff --git a/docs/deciding-to-build-with-the-sdk/component-types.md b/docs/deciding-to-build-with-the-sdk/component-types.md
deleted file mode 100644
index 5e38f95c6..000000000
--- a/docs/deciding-to-build-with-the-sdk/component-types.md
+++ /dev/null
@@ -1,39 +0,0 @@
----
-title: Component Types
-description: How the SDK organizes UI into hooks (headless), sub-components (granular building blocks), and workflows (end-to-end, off-the-shelf flows) — with tradeoffs around control and build speed.
-order: 1
----
-
-## SDK component types
-
-The SDK offers three levels of abstraction. They can be mixed and matched across workflows in your application — use whichever fits each part of your build.
-
-| Type | What it gives you | Best for |
-| ------------------ | ------------------------------------------------------------- | ------------------------------------------------ |
-| **Hooks** | Headless utilities — you own all UI, SDK handles data and API | Design-system-first teams; deepest customization |
-| **Sub-components** | Individual form and UI components with SDK logic built in | Custom layouts and sequencing; mid-level control |
-| **Workflows** | Full multi-step experiences as a single component | Fastest path to a working feature |
-
-### Hooks
-
-Hooks are headless — they handle data fetching, form state, validation, and API submission while you supply all markup and styling. If your team has a mature design system and wants the SDK to stay out of your UI, hooks are the right choice.
-
-See the [Hooks documentation](../hooks/hooks.md) for available hooks and usage examples.
-
-### Sub-components
-
-Sub-components are individual components for a single step or interaction (for example, `CompanyOnboarding.FederalTaxes`). They give you control over layout and sequencing while handling the business logic of each step. Using sub-components instead of a full workflow means:
-
-- You can re-order or omit steps
-- You can insert your own content between SDK steps
-- You can apply [Component Adapters](../component-adapter/component-adapter.md) to bring your own UI components while keeping the SDK's business logic
-
-See the [Workflows Overview](../workflows-overview/workflows-overview.md) for the sub-components available in each domain.
-
-### Workflows
-
-Workflows are single components that encapsulate an entire multi-step user experience. They are the fastest path to a production-ready feature and support the same theming and event handling as individual sub-components.
-
-See the [Workflows Overview](../workflows-overview/workflows-overview.md) for all available workflows.
-
-> Not sure which type is right for you? Starting with a workflow and dropping down to sub-components or hooks for areas that need more control is a common pattern.
diff --git a/docs/deciding-to-build-with-the-sdk/deciding-to-build-with-the-sdk.md b/docs/deciding-to-build-with-the-sdk/deciding-to-build-with-the-sdk.md
deleted file mode 100644
index 8e1dc3de7..000000000
--- a/docs/deciding-to-build-with-the-sdk/deciding-to-build-with-the-sdk.md
+++ /dev/null
@@ -1,29 +0,0 @@
----
-title: Deciding to build with the SDK
-description: Considerations for choosing the React SDK over Flows or a custom API build — React stack fit, abstraction over endpoints, theming, coverage, and customization depth.
-order: 1
----
-
-## Is the GEP React SDK right for me?
-
-If your application uses React — or can introduce React ([see how](https://react.dev/learn/add-react-to-an-existing-project)) — the SDK is the recommended build path for any [payroll workflow it covers](../workflows-overview/workflows-overview.md). You can mix and match approaches across workflows, choosing the right level of abstraction for each part of your application.
-
-**Use the SDK if:**
-
-- Your app is built with React, or you can add React to it
-- You want pre-built, customizable UI — via [workflows](../workflows-overview/workflows-overview.md) or their sub-components — or to own your UI entirely while the SDK handles data fetching, validation, and API calls (via [hooks](../hooks/hooks.md))
-- You want to pre-fill forms with data your application already has
-- You need to match your design system via theming or custom components
-
-**Consider a different approach if:**
-
-- The workflow or hook you need doesn't have SDK coverage yet — check the [Workflows Overview](../workflows-overview/workflows-overview.md) and [Hooks](../hooks/hooks.md) for what's available, and reach out to your Gusto Embedded contact to ask about coverage on your roadmap
-- Your customization requirements go beyond what hooks and component adapters can support — in that case a raw API build may be the right path, though we'd still recommend using SDK components where possible to reduce build scope
-
-## Next steps
-
-[**Getting Started →**](../getting-started/getting-started.md) Install the SDK and render your first component.
-
-[**Workflows Overview →**](../workflows-overview/workflows-overview.md) See what's available end-to-end.
-
-[**Hooks →**](../hooks/hooks.md) Explore the headless API surface.
diff --git a/docs/hooks/hooks.md b/docs/hooks/hooks.md
index 13412a301..a291227a8 100644
--- a/docs/hooks/hooks.md
+++ b/docs/hooks/hooks.md
@@ -10,30 +10,30 @@ Hooks let you own the layout while the SDK manages data fetching, validation, su
## Available Form Hooks
-| Hook | Description | Reference |
-| -------------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| `useEmployeeDetailsForm` | Create or update employee profile fields (name, email, SSN, date of birth, self-onboarding) | [useEmployeeDetailsForm](./useEmployeeDetailsForm.md) |
-| `useJobForm` | Create or update an employee's job (title, hire date, S-Corp 2% shareholder, WA workers' comp) | [useJobForm](./useJobForm.md) |
-| `useCompensationForm` | Create or update a compensation row on a job (FLSA status, pay rate, payment unit, effective date) | [useCompensationForm](./useCompensationForm.md) |
-| `useWorkAddressForm` | Create or update an employee's work address (company location select, effective date) | [useWorkAddressForm](./useWorkAddressForm.md) |
-| `useFederalTaxesForm` | Update an employee's federal tax (W-4) withholding information | [useFederalTaxesForm](./useFederalTaxesForm.md) |
-| `useEmployeeStateTaxesForm` | Update an employee's state tax withholding answers (dynamic, per-state question groups) | [useEmployeeStateTaxesForm](./useEmployeeStateTaxesForm.md) |
-| `usePayScheduleForm` | Create or update a company pay schedule (frequency, pay dates, pay period calendar preview) | [usePayScheduleForm](./usePayScheduleForm.md) |
-| `useSignCompanyForm` | Sign a company form (PDF viewer, typed signature, confirmation checkbox) | [useSignCompanyForm](./useSignCompanyForm.md) |
-| `useSignEmployeeForm` | Sign an employee form (signature, confirmation, I-9 preparer/translator sections) | [useSignEmployeeForm](./useSignEmployeeForm.md) |
-| `useBankForm` | Create a bank account for an employee (nickname, routing/account number, account type) | [useBankForm](./useBankForm.md) |
-| `usePaymentMethodForm` | Switch an employee's payment method between Direct Deposit and Check | [usePaymentMethodForm](./usePaymentMethodForm.md) |
-| `useSplitPaymentsForm` | Split a paycheck across multiple bank accounts (Percentage or Fixed amount, with reordering) | [useSplitPaymentsForm](./useSplitPaymentsForm.md) |
-| `useDeductionForm` | Create or update a non-child-support deduction (court-ordered garnishment or post-tax custom) | [useDeductionForm](./useDeductionForm.md) |
-| `useChildSupportGarnishmentForm` | Create or update a child-support garnishment (agency-keyed required attributes, county selection) | [useChildSupportGarnishmentForm](./useChildSupportGarnishmentForm.md) |
+| Hook | Description |
+| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| [useEmployeeDetailsForm](./useEmployeeDetailsForm.md) | Create or update employee profile fields (name, email, SSN, date of birth, self-onboarding) |
+| [useJobForm](./useJobForm.md) | Create or update an employee's job (title, hire date, S-Corp 2% shareholder, WA workers' comp) |
+| [useCompensationForm](./useCompensationForm.md) | Create or update a compensation row on a job (FLSA status, pay rate, payment unit, effective date) |
+| [useWorkAddressForm](./useWorkAddressForm.md) | Create or update an employee's work address (company location select, effective date) |
+| [useFederalTaxesForm](./useFederalTaxesForm.md) | Update an employee's federal tax (W-4) withholding information |
+| [useEmployeeStateTaxesForm](./useEmployeeStateTaxesForm.md) | Update an employee's state tax withholding answers (dynamic, per-state question groups) |
+| [usePayScheduleForm](./usePayScheduleForm.md) | Create or update a company pay schedule (frequency, pay dates, pay period calendar preview) |
+| [useSignCompanyForm](./useSignCompanyForm.md) | Sign a company form (PDF viewer, typed signature, confirmation checkbox) |
+| [useSignEmployeeForm](./useSignEmployeeForm.md) | Sign an employee form (signature, confirmation, I-9 preparer/translator sections) |
+| [useBankForm](./useBankForm.md) | Create a bank account for an employee (nickname, routing/account number, account type) |
+| [usePaymentMethodForm](./usePaymentMethodForm.md) | Switch an employee's payment method between Direct Deposit and Check |
+| [useSplitPaymentsForm](./useSplitPaymentsForm.md) | Split a paycheck across multiple bank accounts (Percentage or Fixed amount, with reordering) |
+| [useDeductionForm](./useDeductionForm.md) | Create or update a non-child-support deduction (court-ordered garnishment or post-tax custom) |
+| [useChildSupportGarnishmentForm](./useChildSupportGarnishmentForm.md) | Create or update a child-support garnishment (agency-keyed required attributes, county selection) |
## Available Data Hooks
Data hooks fetch and decorate server data and expose the actions valid for it, leaving presentation to you. They follow the same `isLoading` discriminated union and `errorHandling` contract as the rest of the SDK hooks, returning domain `data`, `status`, and `actions`.
-| Hook | Description | Reference |
-| ----------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------- |
-| `useEmployeeList` | Paginated list of a company's employees, each decorated with its allowed actions and primary job | [useEmployeeList](./useEmployeeList.md) |
+| Hook | Description |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| [useEmployeeList](./useEmployeeList.md) | Paginated list of a company's employees, each decorated with its allowed actions and primary job |
---
diff --git a/docs/integration-guide/composition.md b/docs/integration-guide/composition.md
index ad6d26e2d..bf231400e 100644
--- a/docs/integration-guide/composition.md
+++ b/docs/integration-guide/composition.md
@@ -56,6 +56,6 @@ function MyApp({ employeeId, startDate }) {
-Each step of the employee onboarding flow can be imported like this in isolation and used directly as needed. (For a comprehensive list of employee onboarding components available [see the Employee Onboarding documentation here](../workflows-overview/employee-onboarding/employee-onboarding.md)).
+Each step of the employee onboarding flow can be imported like this in isolation and used directly as needed. (For a comprehensive list of employee onboarding components available [see the Employee Onboarding documentation here](../surfaces/employee-onboarding/sub-components.md)).
Because each step is available for direct use in isolation, it is also possible to rearrange steps, compose them with your own content, or [integrate them with your routing infrastructure as outlined here](./routing.md). For example, we could place this compensation form inside of an existing page inline with our own components, or we could use this as a step in a different flow entirely.
diff --git a/docs/surfaces/companies.mdx b/docs/surfaces/companies.mdx
new file mode 100644
index 000000000..889d2c672
--- /dev/null
+++ b/docs/surfaces/companies.mdx
@@ -0,0 +1,27 @@
+---
+title: Companies
+description: SDK surface for onboarding a new company to Gusto Embedded Payroll and handling outstanding information requests.
+order: 1
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The Companies surface covers everything required to onboard a new company to Gusto Embedded Payroll and to manage ongoing company-level interactions like outstanding information requests.
+
+
diff --git a/docs/surfaces/company-onboarding/company-onboarding.mdx b/docs/surfaces/company-onboarding/company-onboarding.mdx
new file mode 100644
index 000000000..d3c51c5e0
--- /dev/null
+++ b/docs/surfaces/company-onboarding/company-onboarding.mdx
@@ -0,0 +1,110 @@
+---
+title: Onboard a company
+description: Onboard a company to Gusto Embedded Payroll — industry, signatory, locations, federal and state taxes, pay schedule, bank account, and document signing.
+order: 1
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+Company Onboarding walks a company through everything required before they can run payroll: industry, signatory assignment, locations, federal and state taxes, pay schedule, bank account, and document signing. The same building blocks can be composed end-to-end as a full workflow or rendered individually as standalone sub-components.
+
+
+
+## Sub-components
+
+
diff --git a/docs/workflows-overview/company-onboarding.md b/docs/surfaces/company-onboarding/sub-components.md
similarity index 91%
rename from docs/workflows-overview/company-onboarding.md
rename to docs/surfaces/company-onboarding/sub-components.md
index ab5a70bdf..7942a6bae 100644
--- a/docs/workflows-overview/company-onboarding.md
+++ b/docs/surfaces/company-onboarding/sub-components.md
@@ -1,65 +1,23 @@
---
-title: Company Onboarding
-description: Workflow for onboarding a company to Gusto Embedded Payroll — industry, signatory, locations, federal taxes, bank account, and document signing subcomponents.
-order: 1
+title: Sub-components
+description: Standalone sub-components for company onboarding — render in isolation or compose into a custom workflow.
+order: 2
---
-The Company Onboarding workflow provides components for managing company-related onboarding tasks. These components can be used individually or composed into a complete workflow.
+# Company Onboarding sub-components
-## Implementation
+Company onboarding components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../../integration-guide/composition.md).
-```jsx title="App.tsx"
-import { CompanyOnboarding } from '@gusto/embedded-react-sdk'
-
-function MyApp() {
- return (
- {}}
- />
- )
-}
-```
-
-### Props
-
-| Name | Type | Description |
-| ------------------ | ------ | --------------------------------------------------------------- |
-| companyId Required | string | The associated company identifier. |
-| defaultValues | object | Default values for individual flow step components |
-| onEvent Required | | See events table for each subcomponent to see available events. |
-
-## Using Company Subcomponents
-
-Company onboarding components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../integration-guide/composition.md).
-
-### Available Subcomponents
-
-- [CompanyOnboarding.AssignSignatory](#companyonboardingassignsignatory)
-- [CompanyOnboarding.CreateSignatory](#companyonboardingcreatesignatory)
-- [CompanyOnboarding.InviteSignatory](#companyonboardinginvitesignatory)
-- [CompanyOnboarding.Industry](#companyonboardingindustry)
-- [CompanyOnboarding.DocumentSigner](#companyonboardingdocumentsigner)
-- [CompanyOnboarding.DocumentList](#companyonboardingdocumentlist)
-- [CompanyOnboarding.SignatureForm](#companyonboardingsignatureform)
-- [CompanyOnboarding.FederalTaxes](#companyonboardingfederaltaxes)
-- [CompanyOnboarding.PaySchedule](#companyonboardingpayschedule)
-- [CompanyOnboarding.Locations](#companyonboardinglocations)
-- [CompanyOnboarding.LocationForm](#companyonboardinglocationform)
-- [CompanyOnboarding.BankAccount](#companyonboardingbankaccount)
-- [CompanyOnboarding.StateTaxes](#companyonboardingstatetaxes)
-- [CompanyOnboarding.StateTaxesForm](#companyonboardingstatetaxesform)
-- [CompanyOnboarding.StateTaxesList](#companyonboardingstatetaxeslist)
-- [CompanyOnboarding.OnboardingOverview](#companyonboardingonboardingoverview)
+---
-### CompanyOnboarding.AssignSignatory
+## Assign a signatory
A component allowing users to choose between creating a new signatory with full details or inviting someone else to become the signatory.
For more granular control, you can use `CompanyOnboarding.CreateSignatory` or `CompanyOnboarding.InviteSignatory` directly.
```jsx title="MyComponent.tsx"
-import { CompanyOnboarding } from '@gusto/embedded-react-sdk'
+import { Company } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -90,12 +48,14 @@ function MyComponent() {
| COMPANY_SIGNATORY_UPDATED | Fired when an existing signatory is updated (create mode) | [Response from the update signatory API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_uuid-signatories-signatory_uuid) |
| COMPANY_SIGNATORY_INVITED | Fired when a signatory invitation is sent (invite mode) | [Response from the invite signatory API request](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_uuid-signatories-invite) |
-### CompanyOnboarding.CreateSignatory
+---
+
+## Create a signatory
A standalone form for creating a new signatory with full personal details including name, contact information, SSN, and home address. Use this component when you want to provide only the create signatory flow without the invite option.
```jsx title="MyComponent.tsx"
-import { CompanyOnboarding } from '@gusto/embedded-react-sdk'
+import { Company } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -124,12 +84,14 @@ function MyComponent() {
| COMPANY_SIGNATORY_UPDATED | Fired when an existing signatory is updated successfully | [Response from the update signatory API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_uuid-signatories-signatory_uuid) |
| COMPANY_CREATE_SIGNATORY_DONE | Fired when the create signatory process is complete | None |
-### CompanyOnboarding.InviteSignatory
+---
+
+## Invite a signatory
A standalone form for inviting someone else to become the company signatory. The invited person will receive an email to complete their signatory information. Use this component when you want to provide only the invite signatory flow without the create option.
```jsx title="MyComponent.tsx"
-import { CompanyOnboarding } from '@gusto/embedded-react-sdk'
+import { Company } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -156,12 +118,14 @@ function MyComponent() {
| COMPANY_SIGNATORY_INVITED | Fired when a signatory is successfully invited to the company | [Response from the invite signatory API request](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_uuid-signatories-invite) |
| COMPANY_INVITE_SIGNATORY_DONE | Fired when the invite signatory process is complete | None |
-### CompanyOnboarding.Industry
+---
+
+## Industry
A component for selecting and saving the company's industry classification (NAICS code). The selector presents a searchable list of industry options for the company.
```jsx title="MyComponent.tsx"
-import { CompanyOnboarding } from '@gusto/embedded-react-sdk'
+import { Company } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -186,12 +150,14 @@ function MyComponent() {
| ------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| COMPANY_INDUSTRY_SELECTED | Fired when an industry is selected and saved | `industry` field from the [Update industry selection API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_uuid-industry_selection) |
-### CompanyOnboarding.DocumentSigner
+---
+
+## Documents
Provides an interface for company representatives to read and sign required company documents. The component handles document listing, signatory management, and document signing workflow.
```jsx title="MyComponent.tsx"
-import { CompanyOnboarding } from '@gusto/embedded-react-sdk'
+import { Company } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -227,12 +193,14 @@ function MyComponent() {
| COMPANY_SIGNATORY_UPDATED | Fired when an existing signatory is updated successfully | [Response from the update signatory API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_uuid-signatories-signatory_uuid) |
| COMPANY_SIGNATORY_INVITED | Fired when a signatory is successfully invited to the company | [Response from the invite signatory API request](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_uuid-signatories-invite) |
-### CompanyOnboarding.DocumentList
+---
+
+## Documents list
A standalone component that displays the list of company documents to be signed and lets the user manage signatories. This is the lower-level building block used internally by `CompanyOnboarding.DocumentSigner` for its list view. Use this component directly when you need full control over navigation between the document list and the signature form.
```jsx title="MyComponent.tsx"
-import { CompanyOnboarding } from '@gusto/embedded-react-sdk'
+import { Company } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -260,12 +228,14 @@ function MyComponent() {
| COMPANY_FORM_EDIT_SIGNATORY | Fired when user requests to change the document signatory | Current signatory entity |
| COMPANY_FORMS_DONE | Fired when user completes the document signing process | None |
-### CompanyOnboarding.SignatureForm
+---
+
+## Sign a document
A standalone form for signing an individual company document. This is the lower-level building block used internally by `CompanyOnboarding.DocumentSigner` for its signing view. Use this component directly when you need full control over navigation between the document list and the signature form (e.g. you are routing the user yourself after they select a form from `CompanyOnboarding.DocumentList`).
```jsx title="MyComponent.tsx"
-import { CompanyOnboarding } from '@gusto/embedded-react-sdk'
+import { Company } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -294,12 +264,14 @@ function MyComponent() {
| COMPANY_SIGN_FORM_DONE | Fired when the form signing process is complete | None |
| COMPANY_SIGN_FORM_BACK | Fired when the user navigates back from the signature form | None |
-### CompanyOnboarding.FederalTaxes
+---
+
+## Federal taxes
A component for adding company federal tax information including EIN, tax payer type, filing form, and legal name.
```jsx title="MyComponent.tsx"
-import { CompanyOnboarding } from '@gusto/embedded-react-sdk'
+import { Company } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -326,12 +298,14 @@ function MyComponent() {
| COMPANY_FEDERAL_TAXES_UPDATED | Fired when federal tax details are successfully updated | [Response from the update federal tax details API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-federal_tax_details) |
| COMPANY_FEDERAL_TAXES_DONE | Fired when the federal tax update process is complete | None |
-### CompanyOnboarding.PaySchedule
+---
+
+## Pay schedule
A component for managing company pay schedules, including creating, editing, and viewing pay schedules with preview functionality.
```jsx title="MyComponent.tsx"
-import { CompanyOnboarding } from '@gusto/embedded-react-sdk'
+import { Company } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -358,12 +332,14 @@ function MyComponent() {
| PAY_SCHEDULE_CREATED | Fired when a new pay schedule is successfully created | [Response from the create pay schedule API request](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-pay_schedules) |
| PAY_SCHEDULE_UPDATED | Fired when an existing pay schedule is successfully updated | [Response from the update pay schedule API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-pay_schedules-pay_schedule_id) |
-### CompanyOnboarding.Locations
+---
+
+## Locations
An orchestrated component for managing company addresses, including mailing and filing address. Internally uses a state machine to switch between a list view and a create/edit form. For more granular control, you can use `CompanyOnboarding.LocationForm` directly.
```jsx title="MyComponent.tsx"
-import { CompanyOnboarding } from '@gusto/embedded-react-sdk'
+import { Company } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -393,14 +369,16 @@ function MyComponent() {
| COMPANY_LOCATION_UPDATED | Fired when locations has been successfully edited | [Response from the update a location API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-locations-location_id) |
| COMPANY_LOCATION_DONE | Fired when user chooses to proceed to a next step | None |
-### CompanyOnboarding.LocationForm
+---
+
+## Location form
A standalone form component for creating a new company location or editing an existing one. This is the lower-level building block used internally by `CompanyOnboarding.Locations` for its create/edit views. Use this component directly when you need full control over navigation between the list and form views.
Pass a `locationId` to edit an existing location; omit it to create a new location.
```jsx title="MyComponent.tsx"
-import { CompanyOnboarding } from '@gusto/embedded-react-sdk'
+import { Company } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -429,12 +407,14 @@ function MyComponent() {
| COMPANY_LOCATION_UPDATED | Fired when a location has been successfully edited | [Response from the update a location API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-locations-location_id) |
| CANCEL | Fired when the user cancels editing | None |
-### CompanyOnboarding.BankAccount
+---
+
+## Bank account
A component for managing company bank account
```jsx title="MyComponent.tsx"
-import { CompanyOnboarding } from '@gusto/embedded-react-sdk'
+import { Company } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -464,12 +444,14 @@ function MyComponent() {
| COMPANY_BANK_ACCOUNT_VERIFIED | Fired when bank account has been successfully verifyed | [Response from the verify a company bank account API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-bank-accounts-verify) |
| COMPANY_BANK_ACCOUNT_DONE | Fired when user chooses to proceed to a next step | None |
-### CompanyOnboarding.StateTaxes
+---
+
+## State taxes
An orchestrated component for managing company state taxes setup. Internally uses a state machine to switch between a list view and an edit form. For more granular control, you can use `CompanyOnboarding.StateTaxesList` or `CompanyOnboarding.StateTaxesForm` directly.
```jsx title="MyComponent.tsx"
-import { CompanyOnboarding } from '@gusto/embedded-react-sdk'
+import { Company } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -496,12 +478,14 @@ function MyComponent() {
| COMPANY_STATE_TAX_UPDATED | Fired when a state tax setup has been successfully submitted | [Response from the create a company update state tax requirements API](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_uuid-tax_requirements-state) |
| COMPANY_STATE_TAX_DONE | Fired when user chooses to proceed to a next step | None |
-### CompanyOnboarding.StateTaxesForm
+---
+
+## State taxes form
A standalone form component for editing state tax requirements for a specific state. This is the lower-level building block used internally by `CompanyOnboarding.StateTaxes` for its edit view. Use this component directly when you need full control over navigation between the list and form views.
```jsx title="MyComponent.tsx"
-import { CompanyOnboarding } from '@gusto/embedded-react-sdk'
+import { Company } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -529,12 +513,14 @@ function MyComponent() {
| COMPANY_STATE_TAX_UPDATED | Fired when a state tax setup has been successfully submitted | [Response from the create a company update state tax requirements API](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_uuid-tax_requirements-state) |
| CANCEL | Fired when the user cancels editing | None |
-### CompanyOnboarding.StateTaxesList
+---
+
+## State taxes list
A standalone component that displays the list of state tax requirements for a company. This is the lower-level building block used internally by `CompanyOnboarding.StateTaxes` for its list view. Use this component directly when you need full control over navigation between the list and form views.
```jsx title="MyComponent.tsx"
-import { CompanyOnboarding } from '@gusto/embedded-react-sdk'
+import { Company } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -560,12 +546,14 @@ function MyComponent() {
| COMPANY_STATE_TAX_EDIT | Fired when a user chooses to edit requirements for a specific state | `{ state: string }` |
| COMPANY_STATE_TAX_DONE | Fired when user chooses to proceed to a next step | None |
-### CompanyOnboarding.OnboardingOverview
+---
+
+## Onboarding overview
Displays the company's overall onboarding status. Shows completed steps and remaining requirements, providing a high-level summary of where the company is in the onboarding process. Used as the landing/summary screen of the onboarding flow.
```jsx title="MyComponent.tsx"
-import { CompanyOnboarding } from '@gusto/embedded-react-sdk'
+import { Company } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
diff --git a/docs/surfaces/company-onboarding/workflow.md b/docs/surfaces/company-onboarding/workflow.md
new file mode 100644
index 000000000..a57f6bac1
--- /dev/null
+++ b/docs/surfaces/company-onboarding/workflow.md
@@ -0,0 +1,34 @@
+---
+title: Workflow
+description: Drop-in CompanyOnboarding.OnboardingFlow component that renders the entire company onboarding experience.
+order: 1
+---
+
+# Company Onboarding workflow
+
+The Company Onboarding workflow renders the entire onboarding experience as a single component. Drop it into your app and it walks the user through every required step.
+
+---
+
+## Implementation
+
+```jsx title="App.tsx"
+import { CompanyOnboarding } from '@gusto/embedded-react-sdk'
+
+function MyApp() {
+ return (
+ {}}
+ />
+ )
+}
+```
+
+#### Props
+
+| Name | Type | Description |
+| ------------------ | ------ | --------------------------------------------------------------- |
+| companyId Required | string | The associated company identifier. |
+| defaultValues | object | Default values for individual flow step components |
+| onEvent Required | | See events table for each subcomponent to see available events. |
diff --git a/docs/surfaces/contractor-onboarding/contractor-onboarding.mdx b/docs/surfaces/contractor-onboarding/contractor-onboarding.mdx
new file mode 100644
index 000000000..d6e4d2441
--- /dev/null
+++ b/docs/surfaces/contractor-onboarding/contractor-onboarding.mdx
@@ -0,0 +1,62 @@
+---
+title: Contractor onboarding
+description: Workflow for onboarding a contractor — profile, address, payment method, new hire reporting, and submission.
+order: 1
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The Contractor Onboarding workflow collects everything required to set a contractor up for payment: profile, address, payment method, new hire reporting, and final submission. The same building blocks can be composed end-to-end as a full workflow or rendered individually as standalone sub-components.
+
+
+
+## Sub-components
+
+
diff --git a/docs/workflows-overview/contractor-onboarding.md b/docs/surfaces/contractor-onboarding/sub-components.md
similarity index 81%
rename from docs/workflows-overview/contractor-onboarding.md
rename to docs/surfaces/contractor-onboarding/sub-components.md
index c2d997a14..05d358e68 100644
--- a/docs/workflows-overview/contractor-onboarding.md
+++ b/docs/surfaces/contractor-onboarding/sub-components.md
@@ -1,55 +1,23 @@
---
-title: Contractor Onboarding
-description: Workflow for onboarding a contractor — profile, address, payment, and document signing — composable as a full flow or individual subcomponents.
+title: Sub-components
+description: Standalone sub-components for contractor onboarding — render in isolation or compose into a custom workflow.
order: 2
---
-The Contractor Onboarding workflow provides components for managing contractor-related onboarding tasks. These components can be used individually or composed into a complete workflow.
+# Contractor Onboarding sub-components
-## Implementation
+Contractor onboarding components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../../integration-guide/composition.md).
-```jsx
-import { ContractorOnboarding } from '@gusto/embedded-react-sdk'
-
-function MyApp() {
- return (
- {}}
- />
- )
-}
-```
-
-### Props
-
-| Name | Type | Description |
-| ------------------ | ------ | ----------------------------------------------------------------------------------------------------- |
-| companyId Required | string | The associated company identifier. |
-| defaultValues | object | Default values containing `profile` and/or `address` sub-objects for individual flow step components. |
-| onEvent Required | | See events table for each subcomponent to see available events. |
-
-Events from subcomponents bubble up through the `onEvent` handler.
-
-## Using Contractor Subcomponents
+> Legacy imports via `Contractor.*` (e.g. `ContractorOnboarding.OnboardingFlow`) continue to work.
-Contractor onboarding components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../integration-guide/composition.md).
-
-### Available Subcomponents
-
-- [ContractorOnboarding.ContractorList](#contractoronboardingcontractorlist)
-- [ContractorOnboarding.ContractorProfile](#contractoronboardingcontractorprofile)
-- [ContractorOnboarding.Address](#contractoronboardingaddress)
-- [ContractorOnboarding.PaymentMethod](#contractoronboardingpaymentmethod)
-- [ContractorOnboarding.NewHireReport](#contractoronboardingnewhirereport)
-- [ContractorOnboarding.ContractorSubmit](#contractoronboardingcontractorsubmit)
+---
-### ContractorOnboarding.ContractorList
+## Contractors list
Displays a list of contractors for a company, allowing users to add new contractors, edit existing ones, delete contractors, and continue the onboarding process.
```jsx
-import { ContractorOnboarding } from '@gusto/embedded-react-sdk'
+import { Contractor } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -78,12 +46,14 @@ function MyComponent() {
| CONTRACTOR_DELETED | Fired when a contractor is deleted | { contractorId: string } |
| CONTRACTOR_ONBOARDING_CONTINUE | Fired when user chooses to continue onboarding | None |
-### ContractorOnboarding.ContractorProfile
+---
+
+## Profile
A comprehensive form for creating and editing contractor profiles. Supports both individual and business contractor types, with different field sets for each. Includes options for wage type, self-onboarding invitations, and start date.
```jsx
-import { ContractorOnboarding } from '@gusto/embedded-react-sdk'
+import { Contractor } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -112,12 +82,14 @@ function MyComponent() {
| CONTRACTOR_UPDATED | Fired when an existing contractor is updated | [Response from the update contractor API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-contractors-contractor_uuid) |
| CONTRACTOR_PROFILE_DONE | Fired when the contractor profile step is complete | { contractorId: string, selfOnboarding: boolean } |
-### ContractorOnboarding.Address
+---
+
+## Address
A form for collecting and updating a contractor's mailing address.
```jsx
-import { ContractorOnboarding } from '@gusto/embedded-react-sdk'
+import { Contractor } from '@gusto/embedded-react-sdk'
function MyComponent() {
return {}} />
@@ -139,12 +111,14 @@ function MyComponent() {
| CONTRACTOR_ADDRESS_UPDATED | Fired when the contractor address is updated | [Response from the create or update a contractor's address API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-contractors-contractor_uuid-address) |
| CONTRACTOR_ADDRESS_DONE | Fired when the address step is complete | None |
-### ContractorOnboarding.PaymentMethod
+---
+
+## Payment method
Manages the contractor's payment method, including adding a bank account for direct deposit or selecting check as the payment method.
```jsx
-import { ContractorOnboarding } from '@gusto/embedded-react-sdk'
+import { Contractor } from '@gusto/embedded-react-sdk'
function MyComponent() {
return {}} />
@@ -166,12 +140,14 @@ function MyComponent() {
| CONTRACTOR_PAYMENT_METHOD_UPDATED | Fired when the payment method is updated | [Response from the update a contractor's payment method API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-contractors-contractor_id-payment_method) |
| CONTRACTOR_PAYMENT_METHOD_DONE | Fired when the payment method step is complete | None |
-### ContractorOnboarding.NewHireReport
+---
+
+## New hire report
Handles new hire reporting requirements for the contractor. Behavior varies based on whether the contractor is going through admin onboarding or self-onboarding.
```jsx
-import { ContractorOnboarding } from '@gusto/embedded-react-sdk'
+import { Contractor } from '@gusto/embedded-react-sdk'
function MyComponent() {
return {}} />
@@ -193,12 +169,14 @@ function MyComponent() {
| CONTRACTOR_NEW_HIRE_REPORT_UPDATED | Fired when the new hire report is updated | [Response from the update contractor API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-contractors-contractor_uuid) |
| CONTRACTOR_NEW_HIRE_REPORT_DONE | Fired when the new hire report step is complete | None |
-### ContractorOnboarding.ContractorSubmit
+---
+
+## Submit contractor
Finalizes the contractor onboarding process. Updates the onboarding status and, in the self-onboarding flow, can trigger an invitation to the contractor.
```jsx
-import { ContractorOnboarding } from '@gusto/embedded-react-sdk'
+import { Contractor } from '@gusto/embedded-react-sdk'
function MyComponent() {
return {}} />
diff --git a/docs/surfaces/contractor-onboarding/workflow.md b/docs/surfaces/contractor-onboarding/workflow.md
new file mode 100644
index 000000000..c75d36c07
--- /dev/null
+++ b/docs/surfaces/contractor-onboarding/workflow.md
@@ -0,0 +1,36 @@
+---
+title: Workflow
+description: Drop-in ContractorOnboarding.OnboardingFlow component that renders the entire contractor onboarding experience.
+order: 1
+---
+
+# Contractor Onboarding workflow
+
+The Contractor Onboarding workflow renders the full onboarding experience as a single component. Drop it into your app and it walks the user through every step required to bring a contractor onto the company.
+
+---
+
+## Implementation
+
+```jsx
+import { ContractorOnboarding } from '@gusto/embedded-react-sdk'
+
+function MyApp() {
+ return (
+ {}}
+ />
+ )
+}
+```
+
+#### Props
+
+| Name | Type | Description |
+| ------------------ | ------ | ----------------------------------------------------------------------------------------------------- |
+| companyId Required | string | The associated company identifier. |
+| defaultValues | object | Default values containing `profile` and/or `address` sub-objects for individual flow step components. |
+| onEvent Required | | See events table for each subcomponent to see available events. |
+
+Events from subcomponents bubble up through the `onEvent` handler.
diff --git a/docs/surfaces/contractor-payments/contractor-payments.mdx b/docs/surfaces/contractor-payments/contractor-payments.mdx
new file mode 100644
index 000000000..5618bf6df
--- /dev/null
+++ b/docs/surfaces/contractor-payments/contractor-payments.mdx
@@ -0,0 +1,59 @@
+---
+title: Contractor payments
+description: Workflow for creating, managing, and viewing contractor payment groups.
+order: 2
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The Contractor Payments workflow lets a company create, manage, and view contractor payment groups. The full experience can be dropped in as a single component, or assembled from individual sub-components — payment list, payment creation, history, summary, and individual payment statements.
+
+
+
+## Sub-components
+
+
diff --git a/docs/workflows-overview/contractor-payments.md b/docs/surfaces/contractor-payments/sub-components.md
similarity index 61%
rename from docs/workflows-overview/contractor-payments.md
rename to docs/surfaces/contractor-payments/sub-components.md
index 016947e2e..304f9a093 100644
--- a/docs/workflows-overview/contractor-payments.md
+++ b/docs/surfaces/contractor-payments/sub-components.md
@@ -1,53 +1,21 @@
---
-title: Contractor Payments
-description: Workflow for creating, managing, and viewing contractor payment groups via ContractorManagement.PaymentFlow, with subcomponents for list, create, history, and summary.
-order: 3
+title: Sub-components
+description: Standalone sub-components for contractor payments — render in isolation or compose into a custom workflow.
+order: 2
---
-The Contractor Payments workflow provides components for creating, managing, and viewing contractor payment groups. These components can be used individually or composed into a complete payment workflow through the `ContractorManagement.PaymentFlow` component.
+# Contractor Payments sub-components
-## Implementation
+Contractor payment components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../../integration-guide/composition.md).
-```jsx
-import { ContractorManagement } from '@gusto/embedded-react-sdk'
-
-function MyApp() {
- return (
- {}}
- />
- )
-}
-```
-
-### Props
-
-| Name | Type | Description |
-| ------------------ | ------ | --------------------------------------------------------------- |
-| companyId Required | string | The associated company identifier. |
-| onEvent Required | | See events table for each subcomponent to see available events. |
-
-Events from subcomponents bubble up through the `onEvent` handler.
-
-## Using Contractor Payment Subcomponents
-
-Contractor payment components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../integration-guide/composition.md).
-
-### Available Subcomponents
-
-- ContractorManagement.PaymentsList
-- ContractorManagement.CreatePayment
-- ContractorManagement.PaymentHistory
-- ContractorManagement.PaymentSummary
-- ContractorManagement.PaymentStatement
+---
-### ContractorManagement.PaymentsList
+## Payments list
Displays a list of contractor payment groups for a company, allowing users to view payment history, create new payments, and filter by date range. Includes alerts for pending information requests and wire transfer requirements.
```jsx
-import { ContractorManagement } from '@gusto/embedded-react-sdk'
+import { Contractor } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -75,12 +43,14 @@ function MyComponent() {
| CONTRACTOR_PAYMENT_VIEW | Fired when user selects a payment group to view | { paymentId: string } |
| CONTRACTOR_PAYMENT_RFI_RESPOND | Fired when user clicks to respond to an RFI alert | None |
-### ContractorManagement.CreatePayment
+---
+
+## Create payment
A comprehensive form for creating contractor payment groups. Allows selecting payment date, editing individual contractor payments with hours, wages, bonuses, and reimbursements. Supports preview before submission and handles submission blockers like Fast ACH thresholds.
```jsx
-import { ContractorManagement } from '@gusto/embedded-react-sdk'
+import { Contractor } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -111,20 +81,22 @@ function MyComponent() {
#### Features
-- **Payment Date Selection**: Choose the payment date with automatic validation
-- **Contractor Payment Editing**: Edit hours (for hourly contractors), wages (for fixed contractors), bonuses, and reimbursements
-- **Payment Method Selection**: Choose between Direct Deposit, Check, or Historical Payment per contractor
-- **Real-time Totals**: View totals for wages, bonuses, reimbursements, and overall total
-- **Preview Mode**: Review payment details, debit information, and submission deadlines before finalizing
-- **Submission Blockers**: Handle Fast ACH thresholds with options to wire funds or switch to 4-day direct deposit
-- **Wire Transfer Support**: Integrated wire transfer instructions when required
+- **Payment date selection**: Choose the payment date with automatic validation
+- **Contractor payment editing**: Edit hours (for hourly contractors), wages (for fixed contractors), bonuses, and reimbursements
+- **Payment method selection**: Choose between Direct Deposit, Check, or Historical Payment per contractor
+- **Real-time totals**: View totals for wages, bonuses, reimbursements, and overall total
+- **Preview mode**: Review payment details, debit information, and submission deadlines before finalizing
+- **Submission blockers**: Handle Fast ACH thresholds with options to wire funds or switch to 4-day direct deposit
+- **Wire transfer support**: Integrated wire transfer instructions when required
-### ContractorManagement.PaymentHistory
+---
+
+## Payment history
Displays detailed information about a specific contractor payment group, including all individual contractor payments. Allows viewing individual payment details and canceling payments when permitted.
```jsx
-import { ContractorManagement } from '@gusto/embedded-react-sdk'
+import { Contractor } from '@gusto/embedded-react-sdk'
function MyComponent() {
return {}} />
@@ -147,17 +119,19 @@ function MyComponent() {
#### Features
-- **Payment Group Overview**: View debit date and overall payment group information
-- **Detailed Payment Table**: Shows contractor name, wage type, payment method, hours, wages, bonuses, reimbursements, and totals
-- **Payment Actions**: View individual payment details or cancel payments when allowed
-- **Cancellation Support**: Cancel individual payments within a payment group when permitted
+- **Payment group overview**: View debit date and overall payment group information
+- **Detailed payment table**: Shows contractor name, wage type, payment method, hours, wages, bonuses, reimbursements, and totals
+- **Payment actions**: View individual payment details or cancel payments when allowed
+- **Cancellation support**: Cancel individual payments within a payment group when permitted
+
+---
-### ContractorManagement.PaymentSummary
+## Payment summary
Displays a summary of a created payment group, including payment details, contractor information, and wire transfer requirements if applicable. Used as a confirmation screen after payment creation.
```jsx
-import { ContractorManagement } from '@gusto/embedded-react-sdk'
+import { Contractor } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -186,17 +160,19 @@ function MyComponent() {
#### Features
-- **Success Confirmation**: Displays confirmation message with number of payments scheduled
-- **Payment Summary**: Shows payment totals, debit information, and payment dates
-- **Wire Transfer Details**: If wire transfer is required, displays wire instructions with confirmation workflow
-- **Bank Account Information**: Shows the debit bank account details
+- **Success confirmation**: Displays confirmation message with number of payments scheduled
+- **Payment summary**: Shows payment totals, debit information, and payment dates
+- **Wire transfer details**: If wire transfer is required, displays wire instructions with confirmation workflow
+- **Bank account information**: Shows the debit bank account details
+
+---
-### ContractorManagement.PaymentStatement
+## Payment statement
Displays an individual contractor payment statement with detailed payment information and breakdown.
```jsx
-import { ContractorManagement } from '@gusto/embedded-react-sdk'
+import { Contractor } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -211,48 +187,3 @@ function MyComponent() {
| ------------------------ | ------ | --------------------------------------------- |
| **paymentId** (Required) | string | The individual contractor payment identifier. |
| **onEvent** (Required) | | See events table for available events. |
-
-## Payment Workflow
-
-The contractor payments workflow follows these typical steps:
-
-1. **View Payment List**: Start with `PaymentsList` to see existing payment groups and create new payments
-2. **Create Payment**: Use `CreatePayment` to build a payment group:
- - Select payment date
- - Edit individual contractor payments (hours, wages, bonuses, reimbursements)
- - Preview payment details
- - Handle submission blockers (Fast ACH, wire transfers)
- - Submit payment group
-3. **View Summary**: After creation, `PaymentSummary` shows confirmation and wire transfer instructions if needed
-4. **View History**: Use `PaymentHistory` to see details of a payment group and manage individual payments
-5. **View Statement**: Use `PaymentStatement` to see detailed information for an individual contractor payment
-
-## Important Notes
-
-### Payment Timing
-
-- Direct deposit payments submitted before 4pm PT on a business day take 2 business days to complete
-- Fast ACH (2-day) payments have threshold limits; exceeding the threshold requires wire transfer or switching to 4-day processing
-
-### Payment Requirements
-
-- Only active contractors with completed onboarding can receive payments
-- At least one contractor payment must be included in a payment group
-- Bank account must be set up for the company to process payments
-
-### Submission Blockers
-
-Payment submission may be blocked by:
-
-- **Fast ACH Threshold Exceeded**: Payment amount exceeds the fast ACH limit
- - Options: Wire transfer (fastest) or switch to 4-day direct deposit
-- **Needs Earned Access for Fast ACH**: Company hasn't earned access to faster payments yet
- - Must use standard 4-day processing
-
-### Wire Transfers
-
-When wire transfer is required:
-
-- Instructions are provided in the payment flow
-- Must be completed by specified deadline to ensure timely payment
-- Confirmation workflow tracks wire transfer submission
diff --git a/docs/surfaces/contractor-payments/workflow.md b/docs/surfaces/contractor-payments/workflow.md
new file mode 100644
index 000000000..d93d8a7b6
--- /dev/null
+++ b/docs/surfaces/contractor-payments/workflow.md
@@ -0,0 +1,81 @@
+---
+title: Workflow
+description: Drop-in Contractor.PaymentFlow component that renders the entire contractor payments experience.
+order: 1
+---
+
+# Contractor Payments workflow
+
+The Contractor Payments workflow renders the full payments experience — view, create, preview, submit, and review payment groups — as a single component. Drop it into your app and the user walks through every step required to pay contractors.
+
+---
+
+## Implementation
+
+```jsx
+import { Contractor } from '@gusto/embedded-react-sdk'
+
+function MyApp() {
+ return (
+ {}} />
+ )
+}
+```
+
+#### Props
+
+| Name | Type | Description |
+| ------------------ | ------ | --------------------------------------------------------------- |
+| companyId Required | string | The associated company identifier. |
+| onEvent Required | | See events table for each subcomponent to see available events. |
+
+Events from subcomponents bubble up through the `onEvent` handler.
+
+---
+
+## Payment workflow
+
+The contractor payments workflow follows these typical steps:
+
+1. **View payment list**: Start with `PaymentsList` to see existing payment groups and create new payments.
+2. **Create payment**: Use `CreatePayment` to build a payment group:
+ - Select payment date
+ - Edit individual contractor payments (hours, wages, bonuses, reimbursements)
+ - Preview payment details
+ - Handle submission blockers (Fast ACH, wire transfers)
+ - Submit payment group
+3. **View summary**: After creation, `PaymentSummary` shows confirmation and wire transfer instructions if needed.
+4. **View history**: Use `PaymentHistory` to see details of a payment group and manage individual payments.
+5. **View statement**: Use `PaymentStatement` to see detailed information for an individual contractor payment.
+
+---
+
+## Important notes
+
+### Payment timing
+
+- Direct deposit payments submitted before 4pm PT on a business day take 2 business days to complete.
+- Fast ACH (2-day) payments have threshold limits; exceeding the threshold requires wire transfer or switching to 4-day processing.
+
+### Payment requirements
+
+- Only active contractors with completed onboarding can receive payments.
+- At least one contractor payment must be included in a payment group.
+- A bank account must be set up for the company to process payments.
+
+### Submission blockers
+
+Payment submission may be blocked by:
+
+- **Fast ACH threshold exceeded**: Payment amount exceeds the fast ACH limit
+ - Options: Wire transfer (fastest) or switch to 4-day direct deposit
+- **Needs earned access for Fast ACH**: Company hasn't earned access to faster payments yet
+ - Must use standard 4-day processing
+
+### Wire transfers
+
+When wire transfer is required:
+
+- Instructions are provided in the payment flow.
+- Must be completed by specified deadline to ensure timely payment.
+- Confirmation workflow tracks wire transfer submission.
diff --git a/docs/surfaces/contractors.mdx b/docs/surfaces/contractors.mdx
new file mode 100644
index 000000000..cb822f55e
--- /dev/null
+++ b/docs/surfaces/contractors.mdx
@@ -0,0 +1,27 @@
+---
+title: Contractors
+description: SDK surface for onboarding contractors and paying them on or off cycle.
+order: 3
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The Contractors surface covers everything required to bring a contractor onto a company and to pay them once they're active. The two flows can be used independently or composed together as part of a broader contractor management experience.
+
+
diff --git a/docs/surfaces/dismissal-payroll/dismissal-payroll.mdx b/docs/surfaces/dismissal-payroll/dismissal-payroll.mdx
new file mode 100644
index 000000000..c1ca005ce
--- /dev/null
+++ b/docs/surfaces/dismissal-payroll/dismissal-payroll.mdx
@@ -0,0 +1,21 @@
+---
+title: Dismissal payroll
+description: Guided workflow for running a terminated employee's final payroll — surfaces unprocessed termination pay periods and transitions into the standard payroll flow.
+order: 3
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The Dismissal Payroll workflow provides a guided experience for running a terminated employee's final payroll. It presents unprocessed termination pay periods for the employee, creates an off-cycle payroll for the selected period, and then transitions into the standard payroll execution flow. Like all off-cycle payroll types, the dismissal flow shares the same execution steps as regular payrolls — the only difference is how the payroll is created.
+
+
diff --git a/docs/surfaces/dismissal-payroll/sub-components.md b/docs/surfaces/dismissal-payroll/sub-components.md
new file mode 100644
index 000000000..b92def182
--- /dev/null
+++ b/docs/surfaces/dismissal-payroll/sub-components.md
@@ -0,0 +1,24 @@
+---
+title: Sub-components
+description: Dismissal payroll is delivered as a single orchestrated flow and reuses the standard payroll processing sub-components for execution.
+order: 2
+---
+
+# Dismissal Payroll sub-components
+
+The Dismissal Payroll workflow is delivered as a single orchestrated flow ([`Payroll.DismissalFlow`](./workflow)) and does not export its own standalone sub-components. After the dismissal payroll is created, the flow internally renders [`Payroll.PayrollExecutionFlow`](../run-payroll/sub-components#execution-flow) with `isDismissalPayroll` enabled to deliver the standard configuration → overview → submission → receipts experience.
+
+---
+
+## Building a custom dismissal experience
+
+If you want to build a custom dismissal-creation step in front of the standard execution UI:
+
+1. Create the off-cycle payroll yourself with `off_cycle_reason: "Dismissed employee"` via the [Create off-cycle payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-payrolls).
+2. Render [`Payroll.PayrollExecutionFlow`](../run-payroll/sub-components#execution-flow) directly with the resulting `payrollId` and `isDismissalPayroll={true}`.
+
+For the individual execution sub-components, see the [Payroll Processing sub-components](../run-payroll/sub-components):
+
+- [Configuration](../run-payroll/sub-components#configuration)
+- [Overview](../run-payroll/sub-components#overview)
+- [Receipts](../run-payroll/sub-components#receipts)
diff --git a/docs/workflows-overview/dismissal-payroll.md b/docs/surfaces/dismissal-payroll/workflow.md
similarity index 69%
rename from docs/workflows-overview/dismissal-payroll.md
rename to docs/surfaces/dismissal-payroll/workflow.md
index 06e8fc7e6..1f803633d 100644
--- a/docs/workflows-overview/dismissal-payroll.md
+++ b/docs/surfaces/dismissal-payroll/workflow.md
@@ -1,15 +1,19 @@
---
-title: Dismissal Payroll
-description: Guided workflow for running a terminated employee's final payroll — surfaces unprocessed termination pay periods and transitions into the standard payroll flow.
-order: 6
+title: Workflow
+description: Drop-in Payroll.DismissalFlow component that runs a terminated employee's final payroll.
+order: 1
---
-The Dismissal Payroll workflow provides a guided experience for running a terminated employee's final payroll. It presents unprocessed termination pay periods for the employee, creates an off-cycle payroll for the selected period, and then transitions into the standard [Payroll Processing](./run-payroll.md) flow for configuration, review, and submission. Like all off-cycle payroll types, the dismissal flow shares the same execution steps as regular payrolls — the only difference is how the payroll is created.
+# Dismissal Payroll workflow
-This workflow is typically launched from the [Employee Termination](./employee-termination.md) flow when the user selects the "Dismissal payroll" option for the employee's final paycheck.
+The Dismissal Payroll workflow renders the full final-paycheck experience for a terminated employee as a single component. It surfaces unprocessed termination pay periods, lets the user pick one, creates an off-cycle payroll for it, and then hands off to the standard payroll execution.
+
+This workflow is typically launched from the [Employee Termination](../employee-termination.md) flow when the user selects the "Dismissal payroll" option for the employee's final paycheck.
> **Important**: Make sure employees are paid on time by checking your [state's requirement guide](https://support.gusto.com/article/100895878100000/Final-paychecks). Some states require employees to receive their final wages within 24 hours (unless they consent otherwise), in which case running a dismissal payroll may be the only option.
+---
+
## Implementation
```jsx
@@ -26,7 +30,7 @@ function MyApp() {
}
```
-### Props
+#### Props
| Name | Type | Description |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
@@ -35,7 +39,7 @@ function MyApp() {
| onEvent Required | function | See events table for available events. |
| payrollId | string | Optional payroll identifier. When provided, the flow skips pay period selection and starts directly at payroll execution. |
-### Events
+#### Events
Events emitted during the pay period selection phase:
@@ -43,38 +47,32 @@ Events emitted during the pay period selection phase:
| ----------------------------- | -------------------------------------------------- | ----------------------- |
| DISMISSAL_PAY_PERIOD_SELECTED | Fired when user selects a pay period and continues | { payrollUuid: string } |
-Once the payroll is created, all standard [run payroll events](./run-payroll.md) are emitted during execution (e.g. `RUN_PAYROLL_CALCULATED`, `RUN_PAYROLL_SUBMITTED`, `RUN_PAYROLL_PROCESSED`).
-
-## Using Dismissal Subcomponents
-
-The dismissal payroll workflow is delivered as a single orchestrated flow (`Payroll.DismissalFlow`). After the dismissal payroll is created, the flow transitions into the standard payroll execution experience and uses the [Run Payroll subcomponents](./run-payroll.md#available-subcomponents) for configuration, overview, submission, and receipts.
-
-### Available Subcomponents
+Once the payroll is created, all standard [run payroll events](../run-payroll/workflow#events) are emitted during execution (e.g. `RUN_PAYROLL_CALCULATED`, `RUN_PAYROLL_SUBMITTED`, `RUN_PAYROLL_PROCESSED`).
-- `Payroll.DismissalFlow` (the entire dismissal flow — see [Implementation](#implementation) above)
-
-For the execution phase, the dismissal flow internally renders [`Payroll.PayrollExecutionFlow`](./run-payroll.md#payrollpayrollexecutionflow) with `isDismissalPayroll` enabled. If you want to build a custom dismissal-creation step in front of the standard execution UI, render `Payroll.PayrollExecutionFlow` directly with the payroll you created. See the [Run Payroll docs](./run-payroll.md) for individual execution subcomponents (`Payroll.PayrollConfiguration`, `Payroll.PayrollOverview`, `Payroll.PayrollReceipts`).
+---
-## Workflow Steps
+## Workflow steps
The flow adapts based on whether a `payrollId` is provided:
**Without `payrollId` (default)**:
-1. **Pay Period Selection**: Displays unprocessed termination pay periods for the employee. The user selects which period to run the final payroll for.
+1. **Pay period selection**: Displays unprocessed termination pay periods for the employee. The user selects which period to run the final payroll for.
2. **Execution**: The standard payroll execution flow takes over — configure employee compensation, review, submit, and view receipts.
**With `payrollId`**:
1. **Execution**: Skips pay period selection and goes directly to payroll execution for the specified payroll.
+---
+
## Integration with Employee Termination
-The dismissal payroll flow integrates with the [Employee Termination workflow](./employee-termination.md):
+The dismissal payroll flow integrates with the [Employee Termination workflow](../employee-termination.md):
-- When the user selects the "Dismissal payroll" option during termination, the `EMPLOYEE_TERMINATION_RUN_PAYROLL` event is emitted with `{ employeeId, companyId, payrollUuid, termination }`
-- Your application should handle this event by rendering `Payroll.DismissalFlow` with the appropriate `companyId` and `employeeId`
-- The dismissal flow fetches the employee's unprocessed termination pay periods and guides the user through the final payroll
+- When the user selects the "Dismissal payroll" option during termination, the `EMPLOYEE_TERMINATION_RUN_PAYROLL` event is emitted with `{ employeeId, companyId, payrollUuid, termination }`.
+- Your application should handle this event by rendering `Payroll.DismissalFlow` with the appropriate `companyId` and `employeeId`.
+- The dismissal flow fetches the employee's unprocessed termination pay periods and guides the user through the final payroll.
```jsx
import { useState } from 'react'
@@ -110,13 +108,23 @@ function TerminationPage({ companyId, employeeId }) {
}
```
-## Pay Period Selection
+---
+
+## Pay period selection
The pay period selection step fetches unprocessed termination pay periods for the employee and presents them as options. Each option shows the pay period date range. When only one pay period is available, it is automatically pre-selected.
Upon selection and submission, the component creates an off-cycle payroll with the `"Dismissed employee"` off-cycle reason using the selected pay period's start and end dates.
-## API Reference
+---
+
+## Skipping a dismissal payroll
+
+If someone accidentally selects dismissal payroll as the final paycheck option and doesn't want to run a dismissal payroll, they can use the [Skip a payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/post-companies-payroll-skip-company_uuid) to bypass the requirement.
+
+---
+
+## API reference
The dismissal payroll uses these API endpoints:
@@ -125,7 +133,3 @@ The dismissal payroll uses these API endpoints:
- **Calculate payroll**: `PUT /v1/companies/{company_id}/payrolls/{payroll_id}/calculate`
- **Submit payroll**: `PUT /v1/companies/{company_id}/payrolls/{payroll_id}/submit`
- **Cancel payroll**: `PUT /v1/companies/{company_id}/payrolls/{payroll_id}/cancel`
-
-### Skipping a Dismissal Payroll
-
-If someone accidentally selects dismissal payroll as the final paycheck option and doesn't want to run a dismissal payroll, they can use the [Skip a payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/post-companies-payroll-skip-company_uuid) to bypass the requirement.
diff --git a/docs/workflows-overview/employee-dashboard.md b/docs/surfaces/employee-dashboard.md
similarity index 100%
rename from docs/workflows-overview/employee-dashboard.md
rename to docs/surfaces/employee-dashboard.md
diff --git a/docs/workflows-overview/employee-management/employee-management.md b/docs/surfaces/employee-management/employee-management.md
similarity index 100%
rename from docs/workflows-overview/employee-management/employee-management.md
rename to docs/surfaces/employee-management/employee-management.md
diff --git a/docs/surfaces/employee-onboarding/employee-onboarding.mdx b/docs/surfaces/employee-onboarding/employee-onboarding.mdx
new file mode 100644
index 000000000..73cf4fa27
--- /dev/null
+++ b/docs/surfaces/employee-onboarding/employee-onboarding.mdx
@@ -0,0 +1,76 @@
+---
+title: Onboard an employee to payroll
+description: Admin-driven workflow for onboarding an employee to payroll — profile, compensation, taxes, payment method, and document signing, with optional I-9 step.
+order: 1
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The Employee Onboarding workflow provides a complete experience for an admin to onboard a new employee to a company. It collects every piece of information required for the employee to be added to payroll, and can be composed end-to-end as a full workflow or rendered piece by piece as standalone sub-components.
+
+
+
+## Sub-components
+
+
diff --git a/docs/workflows-overview/employee-onboarding/employee-onboarding.md b/docs/surfaces/employee-onboarding/sub-components.md
similarity index 86%
rename from docs/workflows-overview/employee-onboarding/employee-onboarding.md
rename to docs/surfaces/employee-onboarding/sub-components.md
index a7f04e1e5..aacd474d6 100644
--- a/docs/workflows-overview/employee-onboarding/employee-onboarding.md
+++ b/docs/surfaces/employee-onboarding/sub-components.md
@@ -1,57 +1,18 @@
---
-title: Employee Onboarding
-description: Complete workflow for onboarding an employee to payroll — profile, compensation, taxes, payment method, and document signing, with optional I-9 step.
-order: 0
+title: Sub-components
+description: Standalone sub-components for admin-driven employee onboarding — render in isolation or compose into a custom workflow.
+order: 2
---
-The Employee Onboarding workflow provides a complete experience for onboarding an employee to a company. It is used to collect all required information for an employee to be added to payroll.
-
-## Implementation
-
-```jsx
-import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
-
-function MyApp() {
- return (
- {}}
- />
- )
-}
-```
-
-### Props
-
-| Name | Type | Default | Description |
-| ----------------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| employeeId | string | | The associated employee identifier. |
-| companyId Required | string | | The associated company identifier. |
-| defaultValues | object | | Default values for individual flow step components |
-| onEvent Required | | | See events table for each subcomponent to see available events. |
-| isSelfOnboardingEnabled | boolean | true | When true, presents the self-onboarding toggle allowing the admin to opt the employee into self-onboarding. When false, the option to self-onboard is not available. |
-| withEmployeeI9 | boolean | false | When true, enables the Employee Documents step in the onboarding flow, allowing the admin to configure I-9 document requirements. |
-
-## Using Employee Subcomponents
+# Employee Onboarding sub-components
Employee onboarding components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../../integration-guide/composition.md).
-### Available Subcomponents
-
-- [EmployeeOnboarding.EmployeeList](#employeeonboardingemployeelist)
-- [EmployeeOnboarding.Profile](#employeeonboardingprofile)
-- [EmployeeOnboarding.Compensation](#employeeonboardingcompensation)
-- [EmployeeOnboarding.FederalTaxes](#employeeonboardingfederaltaxes--employeemanagementfederaltaxes)
-- [EmployeeOnboarding.StateTaxes / EmployeeManagement.StateTaxes](#employeeonboardingstatetaxes--employeemanagementstatetaxes)
-- [EmployeeOnboarding.PaymentMethod](#employeeonboardingpaymentmethod)
-- [EmployeeOnboarding.Deductions](#employeeonboardingdeductions)
-- [EmployeeOnboarding.EmployeeDocuments](#employeeonboardingemployeedocuments)
-- [EmployeeOnboarding.OnboardingSummary](#employeeonboardingonboardingsummary)
+---
-### EmployeeOnboarding.EmployeeList
+## Employees list
-Displays a list of employees containing their full name, and their current onboarding status. An onboarding status. This list also contains actions that allow for the editing or removal of an employee.
+Displays a list of employees containing their full name and their current onboarding status. The list also includes actions for editing or removing an employee.
```jsx
import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
@@ -82,7 +43,9 @@ function MyApp() {
| EMPLOYEE_ONBOARDING_STATUS_UPDATED | Fired after the "Review" or "Cancel self-onboarding" action updates the employee's onboarding status | The updated `EmployeeOnboardingStatus` record |
| EMPLOYEE_DELETED | Fired after selecting delete from the employee actions menu and the delete operation completes | `{ employeeId: string }` |
-### EmployeeOnboarding.Profile
+---
+
+## Profile
Used to collect basic information about the employee:
@@ -96,7 +59,7 @@ Used to collect basic information about the employee:
This component also provides the option to invite the employee to enter some of their details themself. If selected, they can be sent an invitation to complete the form.
```jsx
-import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
+import { Employee } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -134,7 +97,9 @@ function MyComponent() {
| EMPLOYEE_PROFILE_DONE | Fired after form submission and all api calls have finished and we are ready to advance to the next step | Called with an object aggregated with the responses above. This either includes all of the responses for creating new entities (if it is creating a new employee) or all the responses for updating entities (if it is updating an existing employee) |
| CANCEL | Fired when user clicks cancel button | None |
-### EmployeeOnboarding.Compensation
+---
+
+## Compensation
Collects details related to the role of the employee and their compensation:
@@ -146,7 +111,7 @@ Collects details related to the role of the employee and their compensation:
For hourly employees, the compensation component allows for the configuration of multiple roles.
```jsx
-import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
+import { Employee } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -178,12 +143,14 @@ function MyComponent() {
| EMPLOYEE_COMPENSATION_UPDATED | Fired after updating compensation details | Response from the Update a compensation endpoint |
| EMPLOYEE_COMPENSATION_DONE | Fired when compensation setup is complete and we are ready to advance to the next step | None |
-### EmployeeOnboarding.FederalTaxes / EmployeeManagement.FederalTaxes
+---
+
+## Federal taxes
Provides required form inputs for employee federal tax configuration. The component ships in two journey-scoped variants that share the same form rendering but differ in CTAs and emitted events; pick the variant that matches your screen instead of toggling a prop.
- **`EmployeeOnboarding.FederalTaxes`** renders a single **Continue** submit button and emits `EMPLOYEE_FEDERAL_TAXES_DONE` after a successful save so the parent onboarding flow can advance.
-- **`EmployeeManagement.FederalTaxes`** renders **Cancel** + **Save**. Cancel emits `CANCEL` so the parent can navigate away; Save submits the form, surfaces a dismissible success alert, and keeps the user on the screen.
+- **`EmployeeManagement.FederalTaxes`** (also exported as `EmployeeOnboarding.FederalTaxes` for backwards compatibility) renders **Cancel** + **Save**. Cancel emits `CANCEL` so the parent can navigate away; Save submits the form, surfaces a dismissible success alert, and keeps the user on the screen.
```jsx
// Onboarding journey
@@ -226,7 +193,9 @@ function ManagementEditScreen() {
| EMPLOYEE_FEDERAL_TAXES_DONE | Onboarding only | Fired after a successful save, signalling the parent flow can advance to the next step | None |
| CANCEL | Management only | Fired when the user clicks the Cancel button | None |
-### EmployeeOnboarding.StateTaxes / EmployeeManagement.StateTaxes
+---
+
+## State taxes
Provides required form inputs for employee state tax configuration. The component ships in two journey-scoped variants that share the same form rendering but differ in CTAs, emitted events, and visible questions; pick the variant that matches your screen instead of toggling a prop.
@@ -275,12 +244,14 @@ function ManagementEditScreen() {
| EMPLOYEE_STATE_TAXES_DONE | Onboarding only | Fired after a successful save, signalling the parent flow can advance to the next step | None |
| CANCEL | Management only | Fired when the user clicks the Cancel button | None |
-### EmployeeOnboarding.PaymentMethod
+---
+
+## Payment method
Used for configuring employee bank account(s). Bank accounts created with this component will be used to pay the employee when payroll is run. Payments can be split across multiple accounts.
```jsx
-import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
+import { Employee } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -309,12 +280,14 @@ function MyComponent() {
| EMPLOYEE_PAYMENT_METHOD_UPDATED | Fired when the employee updates the payment method by selecting the continue CTA or if they opt to split paychecks and save the split paycheck form | Response from the Update payment method endpoint |
| EMPLOYEE_PAYMENT_METHOD_DONE | Fired when the continue CTA is selected on the payment details step, all API calls are finished, and we are ready to advance to the next step | None |
-### EmployeeOnboarding.Deductions
+---
+
+## Deductions
Used for configuring additional withholdings from employee pay. Deductions can be set by percentage or fixed amount, and can be either recurring or one-time.
```jsx
-import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
+import { Employee } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -343,14 +316,16 @@ function MyComponent() {
| EMPLOYEE_DEDUCTION_DELETED | Fired after deleting a deduction | Response from the Update a garnishment endpoint with active:false |
| EMPLOYEE_DEDUCTION_DONE | Fired when deductions setup is complete and user is ready to navigate to the next step | None |
-### EmployeeOnboarding.EmployeeDocuments
+---
+
+## Documents
Used during admin onboarding to configure which documents are included in the employee's self-onboarding experience. When the employee has been invited to self-onboard, this step allows the admin to enable or disable the I-9 (Employment Eligibility Verification) form. When the employee is not self-onboarding, this step displays a read-only summary of the documents that will be part of the onboarding process.
This component is conditionally shown in the `EmployeeOnboardingFlow` when `withEmployeeI9` is set to `true`.
```jsx
-import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
+import { Employee } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
@@ -376,12 +351,14 @@ function MyComponent() {
| EMPLOYEE_ONBOARDING_DOCUMENTS_CONFIG_UPDATED | Fired after the admin toggles the I-9 inclusion checkbox and the configuration is successfully updated | Response from the [Update an employee's onboarding documents config](https://docs.gusto.com/embedded-payroll/reference/put-v1-employees-employee_id-onboarding_documents_config) endpoint |
| EMPLOYEE_DOCUMENTS_CONTINUE | Fired when the admin clicks continue and is ready to advance to the next step | None |
-### EmployeeOnboarding.OnboardingSummary
+---
+
+## Onboarding summary
Displays the current state of employee onboarding.
```jsx
-import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
+import { Employee } from '@gusto/embedded-react-sdk'
function MyComponent() {
return (
diff --git a/docs/surfaces/employee-onboarding/workflow.md b/docs/surfaces/employee-onboarding/workflow.md
new file mode 100644
index 000000000..2c8333c15
--- /dev/null
+++ b/docs/surfaces/employee-onboarding/workflow.md
@@ -0,0 +1,38 @@
+---
+title: Workflow
+description: Drop-in EmployeeOnboarding.OnboardingFlow component that renders the entire admin-driven employee onboarding experience.
+order: 1
+---
+
+# Employee Onboarding workflow
+
+The Employee Onboarding workflow renders the full admin-driven onboarding experience as a single component. Drop it into your app and it walks the admin through every step required to add an employee to payroll.
+
+---
+
+## Implementation
+
+```jsx
+import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
+
+function MyApp() {
+ return (
+ {}}
+ />
+ )
+}
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| ----------------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| employeeId | string | | The associated employee identifier. |
+| companyId Required | string | | The associated company identifier. |
+| defaultValues | object | | Default values for individual flow step components |
+| onEvent Required | | | See events table for each subcomponent to see available events. |
+| isSelfOnboardingEnabled | boolean | true | When true, presents the self-onboarding toggle allowing the admin to opt the employee into self-onboarding. When false, the option to self-onboard is not available. |
+| withEmployeeI9 | boolean | false | When true, enables the Employee Documents step in the onboarding flow, allowing the admin to configure I-9 document requirements. |
diff --git a/docs/surfaces/employee-self-onboarding/employee-self-onboarding.mdx b/docs/surfaces/employee-self-onboarding/employee-self-onboarding.mdx
new file mode 100644
index 000000000..ca2c51aaf
--- /dev/null
+++ b/docs/surfaces/employee-self-onboarding/employee-self-onboarding.mdx
@@ -0,0 +1,72 @@
+---
+title: Employee self-onboarding
+description: Employee-driven onboarding flow that hands the employee responsibility for submitting their own profile, tax, payment, and document-signing information.
+order: 2
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+When an admin opts an employee into self-onboarding, the employee completes their own onboarding steps — profile, tax, payment method, and document signing — rather than the admin entering everything on their behalf. The workflow can be composed end-to-end as a single component, or built from standalone sub-components when you need full control over the surrounding experience.
+
+
+
+## Sub-components
+
+
diff --git a/docs/workflows-overview/employee-onboarding/employee-self-onboarding.md b/docs/surfaces/employee-self-onboarding/sub-components.md
similarity index 65%
rename from docs/workflows-overview/employee-onboarding/employee-self-onboarding.md
rename to docs/surfaces/employee-self-onboarding/sub-components.md
index d066d1ce5..1c0ed45e4 100644
--- a/docs/workflows-overview/employee-onboarding/employee-self-onboarding.md
+++ b/docs/surfaces/employee-self-onboarding/sub-components.md
@@ -1,53 +1,18 @@
---
-title: Employee Self-Onboarding
-description: Employee-driven onboarding flow that hands the employee responsibility for submitting their own profile, tax, payment, and document-signing information.
-order: 0
+title: Sub-components
+description: Standalone sub-components for employee-driven self-onboarding — render in isolation or compose into a custom workflow.
+order: 2
---
-In the case an employer elects to allow the employee to self-onboard, they can be provided with the self-onboarding workflow. This workflow places the responsibility of submitting some required information on the employee.
+# Employee Self-Onboarding sub-components
-## Implementation
+Like the admin-driven employee onboarding, self-onboarding components can be used to compose your own workflow or be rendered in isolation. Many of these components are the same as the ones used for general employee onboarding; some fields are hidden or shown based on the current user type. For guidance on creating a custom workflow, see [docs on composition](../../integration-guide/composition.md).
-```jsx
-import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
-
-function MyApp() {
- return (
- {}}
- />
- )
-}
-```
-
-### Props
-
-| Name | Type | Default | Description |
-| ------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| employeeId Required | string | | The associated employee identifier. |
-| companyId Required | string | | The associated company identifier. |
-| onEvent Required | | | See events table for each subcomponent to see available events. |
-| withEmployeeI9 | boolean | false | When true, the Document Signer step checks if the employee has I-9 enabled and routes to the Employment Eligibility and I-9 signature form steps. |
+> Legacy imports via `Employee.*` (e.g. `EmployeeOnboarding.Landing`) continue to work.
-## Using Self-Onboarding Subcomponents
-
-Like Employee onboarding, self-onboarding components can be used to compose your own workflow, or be rendered in isolation. Many of these components are the same as the ones used for general employee onboarding, however some fields are hidden and shown based on the current user type. For guidance on creating a custom workflow, see [docs on composition](../../integration-guide/composition.md).
-
-### Available Subcomponents
-
-- [EmployeeOnboarding.Landing](#employeeonboardinglanding)
-- [EmployeeOnboarding.Profile](#employeeonboardingprofile)
-- [EmployeeOnboarding.FederalTaxes](#employeeonboardingfederaltaxes)
-- [EmployeeOnboarding.StateTaxes](#employeeonboardingstatetaxes)
-- [EmployeeOnboarding.PaymentMethod](#employeeonboardingpaymentmethod)
-- [EmployeeOnboarding.DocumentSigner](#employeeonboardingdocumentsigner)
-- [EmployeeOnboarding.EmploymentEligibility](#employeeonboardingemploymenteligibility)
-- [EmployeeOnboarding.OnboardingSummary](#employee-onboarding-summary)
+---
-### EmployeeOnboarding.Landing
+## Welcome screen
Displays guidance on what to expect from the workflow and what information the employee will be required to have on hand and provide.
@@ -79,11 +44,13 @@ function MyApp() {
| ------------------------------ | --------------------------------------------------------------------------------------------- | ---- |
| EMPLOYEE_SELF_ONBOARDING_START | Fired when the employee selects the get started CTA and is ready to navigate to the next step | None |
-### EmployeeOnboarding.Profile
+---
-_See component documentation in the Employee Onboarding section for a complete list of props and events since this component is used in both employee onboarding and employee self onboarding._
+## Profile
-When used in self onboarding, used to collect basic information about the employee:
+_See [Profile in Employee Onboarding sub-components](../employee-onboarding/sub-components#profile) for a complete list of props and events — this component is used in both employee onboarding and employee self-onboarding._
+
+When used in self-onboarding, this component collects basic information about the employee:
- First and last name
- Email address
@@ -91,7 +58,7 @@ When used in self onboarding, used to collect basic information about the employ
- Date of birth
- And home address
-For self onboarding, you need to be sure to set the `employeeId` property. The `isAdmin` property should be left out or set to false (which is the setting by default). The following example has the Profile component configured for self onboarding:
+For self-onboarding, set the `employeeId` property and leave `isAdmin` out (or set it to `false`, the default). The example below has the Profile component configured for self-onboarding:
```jsx
import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
@@ -107,9 +74,11 @@ function MyApp() {
}
```
-### EmployeeOnboarding.FederalTaxes
+---
+
+## Federal taxes
-_See component documentation in the Employee Onboarding section for a complete list of props and events since this component is used in both employee onboarding and employee self onboarding._
+_See [Federal taxes in Employee Onboarding sub-components](../employee-onboarding/sub-components#federal-taxes) for a complete list of props and events — this component is used in both employee onboarding and employee self-onboarding._
Provides required form inputs for employee federal tax configuration.
@@ -126,9 +95,11 @@ function MyComponent() {
}
```
-### EmployeeOnboarding.StateTaxes
+---
+
+## State taxes
-_See component documentation in the Employee Onboarding section for a complete list of props and events since this component is used in both employee onboarding and employee self onboarding._
+_See [State taxes in Employee Onboarding sub-components](../employee-onboarding/sub-components#state-taxes) for a complete list of props and events — this component is used in both employee onboarding and employee self-onboarding._
Provides required form inputs for employee state tax configuration.
@@ -145,9 +116,11 @@ function MyComponent() {
}
```
-### EmployeeOnboarding.PaymentMethod
+---
+
+## Payment method
-_See component documentation in the Employee Onboarding section for a complete list of props and events since this component is used in both employee onboarding and employee self onboarding._
+_See [Payment method in Employee Onboarding sub-components](../employee-onboarding/sub-components#payment-method) for a complete list of props and events — this component is used in both employee onboarding and employee self-onboarding._
Used for configuring employee bank account(s). Bank accounts created with this component will be used to pay the employee when payroll is run. Payments can be split across multiple accounts.
@@ -164,7 +137,9 @@ function MyComponent() {
}
```
-### EmployeeOnboarding.DocumentSigner
+---
+
+## Sign documents
Provides the employee with an interface to read and sign required employment documents. When `withEmployeeI9` is enabled and the employee has I-9 configured, the Document Signer will first route the employee through the Employment Eligibility step and then present the I-9 form for signature alongside other required documents.
@@ -199,7 +174,9 @@ function MyComponent() {
| EMPLOYEE_SIGN_FORM | Fired when the user submits the form to sign | Response from the [Sign an employee form](https://docs.gusto.com/embedded-payroll/reference/put-v1-employees-employee_id-forms-form_id-sign) endpoint |
| EMPLOYEE_FORMS_DONE | Fired when the user is done signing forms and is ready to advance to the next step in the flow | None |
-### EmployeeOnboarding.EmploymentEligibility
+---
+
+## Employment eligibility
A standalone form for collecting an employee's I-9 employment eligibility (Section 1) details, including authorization status (citizen, non-citizen national, permanent resident, alien) and supporting document information when applicable. This is the lower-level building block used internally by `EmployeeOnboarding.DocumentSigner` when `withEmployeeI9` is enabled. Use this component directly when you want to collect I-9 details outside of the document-signing flow or compose a custom routing experience.
@@ -229,13 +206,15 @@ function MyComponent() {
| ------------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| EMPLOYEE_EMPLOYMENT_ELIGIBILITY_DONE | Fired when the employee completes the employment eligibility form | Response from the [Create or update an employee's I-9 authorization](https://docs.gusto.com/embedded-payroll/reference/put-v1-employees-employee_id-i9_authorization) endpoint |
-### Employee Onboarding Summary
+---
+
+## Onboarding summary
-_See component documentation in the Employee Onboarding section for a complete list of props and events since this component is used in both employee onboarding and employee self onboarding._
+_See [Onboarding summary in Employee Onboarding sub-components](../employee-onboarding/sub-components#onboarding-summary) for a complete list of props and events — this component is used in both employee onboarding and employee self-onboarding._
Displays the current state of employee onboarding.
-The `isAdmin` property should be left out or set to false (which is the setting by default). The following example has the OnboardingSummary component configured for self onboarding:
+For self-onboarding, leave `isAdmin` out (or set it to `false`, the default). The example below has the OnboardingSummary component configured for self-onboarding:
```jsx
import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
diff --git a/docs/surfaces/employee-self-onboarding/workflow.md b/docs/surfaces/employee-self-onboarding/workflow.md
new file mode 100644
index 000000000..7aec01eef
--- /dev/null
+++ b/docs/surfaces/employee-self-onboarding/workflow.md
@@ -0,0 +1,37 @@
+---
+title: Workflow
+description: Drop-in EmployeeOnboarding.SelfOnboardingFlow component that renders the entire employee-driven self-onboarding experience.
+order: 1
+---
+
+# Employee Self-Onboarding workflow
+
+The Employee Self-Onboarding workflow renders the full employee-driven onboarding experience as a single component. Drop it into your app and the employee walks themselves through every required step.
+
+---
+
+## Implementation
+
+```jsx
+import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
+
+function MyApp() {
+ return (
+ {}}
+ />
+ )
+}
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| ------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| employeeId Required | string | | The associated employee identifier. |
+| companyId Required | string | | The associated company identifier. |
+| onEvent Required | | | See events table for each subcomponent to see available events. |
+| withEmployeeI9 | boolean | false | When true, the Document Signer step checks if the employee has I-9 enabled and routes to the Employment Eligibility and I-9 signature form steps. |
diff --git a/docs/workflows-overview/employee-termination.md b/docs/surfaces/employee-termination.md
similarity index 100%
rename from docs/workflows-overview/employee-termination.md
rename to docs/surfaces/employee-termination.md
diff --git a/docs/surfaces/employees.mdx b/docs/surfaces/employees.mdx
new file mode 100644
index 000000000..3c217a296
--- /dev/null
+++ b/docs/surfaces/employees.mdx
@@ -0,0 +1,27 @@
+---
+title: Employees
+description: SDK surface for onboarding new employees — admin-driven and employee-driven (self-onboarding) flows.
+order: 2
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The Employees surface covers everything required to onboard new employees, whether the company admin drives the experience end-to-end or the employee completes onboarding themselves.
+
+
diff --git a/docs/surfaces/information-requests/information-requests.mdx b/docs/surfaces/information-requests/information-requests.mdx
new file mode 100644
index 000000000..f13055643
--- /dev/null
+++ b/docs/surfaces/information-requests/information-requests.mdx
@@ -0,0 +1,41 @@
+---
+title: Information Requests
+description: Standalone surface for viewing and responding to outstanding information requests Gusto has issued for a company.
+order: 8
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The Information Requests surface lets a company view and respond to outstanding information requests Gusto has issued — for example, a request for a missing tax document or identity verification artifact. Information requests can also block payroll processing, in which case they surface inline within `Payroll.PayrollBlockerList`; this surface is the dedicated, standalone version.
+
+
+
+## Sub-components
+
+
diff --git a/docs/surfaces/information-requests/sub-components.md b/docs/surfaces/information-requests/sub-components.md
new file mode 100644
index 000000000..0aaa7ec7c
--- /dev/null
+++ b/docs/surfaces/information-requests/sub-components.md
@@ -0,0 +1,94 @@
+---
+title: Sub-components
+description: Standalone sub-components for information requests — render the list or response form individually.
+order: 2
+---
+
+# Information Requests sub-components
+
+Information requests components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../../integration-guide/composition.md).
+
+---
+
+## Information requests list
+
+Displays a list of information requests for a company, including status badges (Open / Submitted) and a "Respond" CTA for open requests. Used as the top-level surface of `InformationRequests.InformationRequestsFlow`, but can be rendered directly when you want to host the response form yourself (e.g. in a custom modal or page).
+
+```jsx
+import { InformationRequests } from '@gusto/embedded-react-sdk'
+
+function MyComponent() {
+ return (
+ {}}
+ />
+ )
+}
+```
+
+#### Props
+
+| Name | Type | Description |
+| ------------------------ | -------- | ----------------------------------------- |
+| **companyId** (Required) | string | The associated company identifier. |
+| **onEvent** (Required) | function | See events table for available events. |
+| dictionary | object | Optional translations for component text. |
+
+#### Events
+
+| Event type | Description | Data |
+| --------------------------- | ------------------------------------------------------- | --------------------- |
+| INFORMATION_REQUEST_RESPOND | Fired when the user clicks "Respond" on an open request | { requestId: string } |
+
+---
+
+## Information request form
+
+The dynamic response form for a single information request. Renders supported question types (text and document upload) based on the request's `requiredQuestions` payload from the API and submits responses via the [Submit information request endpoint](https://docs.gusto.com/embedded-payroll/reference/post-information-requests-submit). Use this component directly when you have built your own list/routing surface and need to host the form (typically inside a modal or page you control).
+
+```jsx
+import { InformationRequests } from '@gusto/embedded-react-sdk'
+
+function MyComponent() {
+ return (
+ {}}
+ />
+ )
+}
+```
+
+#### Props
+
+| Name | Type | Description |
+| ------------------------ | -------- | -------------------------------------------------------- |
+| **companyId** (Required) | string | The associated company identifier. |
+| **requestId** (Required) | string | The identifier of the information request to respond to. |
+| **onEvent** (Required) | function | See events table for available events. |
+| dictionary | object | Optional translations for component text. |
+
+#### Events
+
+| Event type | Description | Data |
+| ------------------------------- | --------------------------------------------- | ----------------------------------------------------- |
+| INFORMATION_REQUEST_FORM_DONE | Fired when the form is successfully submitted | Response from the Submit information request endpoint |
+| INFORMATION_REQUEST_FORM_CANCEL | Fired when the user cancels the form | None |
+
+#### Supported Response Types
+
+The form currently renders inputs for the following `responseType` values:
+
+- **`text`** — single-line text input (max 5,000 characters)
+- **`document`** — file upload restricted to JPEG, PNG, or PDF
+
+Requests with unsupported response types (e.g. `persona`-driven identity verification) display a guidance message instead of the form. In those cases the user must complete the request through the partner's own integration with the underlying provider.
+
+## API Reference
+
+The information requests workflow uses these API endpoints:
+
+- **List information requests**: `GET /v1/companies/{company_uuid}/information_requests`
+- **Submit an information request**: `POST /v1/information_requests/{information_request_uuid}/submit`
diff --git a/docs/surfaces/information-requests/workflow.md b/docs/surfaces/information-requests/workflow.md
new file mode 100644
index 000000000..2eaf376bd
--- /dev/null
+++ b/docs/surfaces/information-requests/workflow.md
@@ -0,0 +1,55 @@
+---
+title: Workflow
+description: Drop-in InformationRequests.InformationRequestsFlow component for viewing and responding to outstanding information requests.
+order: 1
+---
+
+# Information Requests workflow
+
+The Information Requests workflow renders the full list-and-respond experience as a single component. Drop it into your app and the user can view outstanding requests and submit responses without any additional wiring.
+
+---
+
+## Implementation
+
+```jsx
+import { InformationRequests } from '@gusto/embedded-react-sdk'
+
+function MyApp() {
+ return (
+ {}}
+ />
+ )
+}
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| ------------------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| companyId Required | string | | The associated company identifier. |
+| onEvent | function | | See events table for each subcomponent to see available events. |
+| withAlert | boolean | `true` | When true, the submission success alert is rendered at the top of the flow. Set to false when embedding in a parent (e.g. `Payroll.PayrollBlockerList`) that renders the alert elsewhere. |
+| dictionary | object | | Optional translations for component text. |
+
+#### Events
+
+Events emitted by the flow (and by its subcomponents — they bubble up through `onEvent`):
+
+| Event type | Description | Data |
+| ------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| INFORMATION_REQUEST_RESPOND | Fired when the user clicks "Respond" on a request and the form modal opens | { requestId: string } |
+| INFORMATION_REQUEST_FORM_DONE | Fired when an information request is successfully submitted | Response from the Submit information request endpoint |
+| INFORMATION_REQUEST_FORM_CANCEL | Fired when the user cancels the response form (closes the modal without submitting) | None |
+
+## Workflow Steps
+
+1. **List**: The user sees all open and submitted information requests for the company, with status badges and a "Respond" CTA on each open request.
+2. **Respond**: Selecting "Respond" opens a modal with a dynamically rendered form built from the request's required questions (text, document upload). Persona-style questions and other unsupported response types fall back to a guidance message rather than rendering the form.
+3. **Submit**: On successful submit, a dismissible success alert appears at the top of the list (when `withAlert` is true) and the modal closes.
+
+## Integration with Payroll Blockers
+
+Information requests can also block payroll processing. When that happens they are surfaced inside [`Payroll.PayrollBlockerList`](../run-payroll/sub-components#blockers), which embeds `InformationRequests.InformationRequestsFlow` with `withAlert={false}` so the blocker list owns the success alert UX. If you build your own blocker resolution surface, you can use the same pattern.
diff --git a/docs/surfaces/off-cycle-payroll/off-cycle-payroll.mdx b/docs/surfaces/off-cycle-payroll/off-cycle-payroll.mdx
new file mode 100644
index 000000000..ca77f5939
--- /dev/null
+++ b/docs/surfaces/off-cycle-payroll/off-cycle-payroll.mdx
@@ -0,0 +1,46 @@
+---
+title: Off-cycle payroll
+description: Workflow for running payrolls outside the regular pay schedule — bonus or correction — then transitioning into the standard payroll execution.
+order: 2
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The Off-Cycle Payroll workflow runs payrolls outside of a company's regular pay schedule. It supports two off-cycle reasons — **Bonus** (paying a bonus, gift, or commission) and **Correction** (running a correction payment) — and guides users through configuring pay period dates, selecting a reason, choosing employees, and setting deduction and tax withholding preferences. After creation, the flow transitions into the standard payroll execution experience.
+
+
+
+## Sub-components
+
+
diff --git a/docs/surfaces/off-cycle-payroll/sub-components.md b/docs/surfaces/off-cycle-payroll/sub-components.md
new file mode 100644
index 000000000..99662bc4b
--- /dev/null
+++ b/docs/surfaces/off-cycle-payroll/sub-components.md
@@ -0,0 +1,114 @@
+---
+title: Sub-components
+description: Standalone sub-components for off-cycle payroll — render in isolation or compose into a custom workflow.
+order: 2
+---
+
+# Off-Cycle Payroll sub-components
+
+Off-cycle components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../../integration-guide/composition.md).
+
+After creation, the off-cycle flow hands off to the shared [`Payroll.PayrollExecutionFlow`](../run-payroll/sub-components#execution-flow) for the configuration → overview → submission → receipts steps. If you build your own creation step in front of the standard execution UI, render `Payroll.PayrollExecutionFlow` directly with the payroll you created.
+
+---
+
+## Off-cycle creation
+
+The main creation form for off-cycle payrolls. Includes reason selection, pay period date configuration, employee selection, deduction settings, and tax withholding configuration.
+
+```jsx
+import { Payroll } from '@gusto/embedded-react-sdk'
+
+function MyComponent() {
+ return {}} />
+}
+```
+
+#### Props
+
+| Name | Type | Description |
+| ------------------ | --------------------------- | ---------------------------------------------------------- |
+| companyId Required | string | The associated company identifier. |
+| onEvent Required | function | See events table for available events. |
+| payrollType | `'bonus'` \| `'correction'` | Optional pre-selected payroll type. Defaults to `'bonus'`. |
+| dictionary | object | Optional translations for component text. |
+
+#### Events
+
+| Event type | Description | Data |
+| ----------------- | ------------------------------------------- | ----------------------- |
+| OFF_CYCLE_CREATED | Fired when the off-cycle payroll is created | { payrollUuid: string } |
+
+#### Form fields
+
+- **Check-only payroll**: Toggle for check-only payments — when enabled, all employees will be paid by check (not direct deposit), the check date can be set to today or any future date, and start/end dates are not required
+- **Start date**: Beginning of the pay period (required unless check-only; cannot be in the future for correction payrolls)
+- **End date**: End of the pay period (required unless check-only; must be on or after start date)
+- **Payment date (check date)**: The date employees will be paid (must be at least 2 business days from today for direct deposit, unless check-only)
+- **Reason**: Bonus or Correction payment
+- **Employee selection**: Include all employees or select specific employees
+- **Deductions and contributions**: Include or skip regular deductions (see [Deductions setting](#deductions-setting))
+- **Tax withholding rates**: Configure withholding pay period and rate type (regular or supplemental)
+
+---
+
+## Reason selection
+
+Presents the reason selection UI for choosing between a bonus and correction payment.
+
+```jsx
+import { Payroll } from '@gusto/embedded-react-sdk'
+
+function MyComponent() {
+ return {}} />
+}
+```
+
+#### Props
+
+| Name | Type | Description |
+| ------------------ | -------- | ----------------------------------------- |
+| companyId Required | string | The associated company identifier. |
+| onEvent Required | function | See events table for available events. |
+| dictionary | object | Optional translations for component text. |
+
+#### Events
+
+| Event type | Description | Data |
+| ----------------------- | -------------------------------- | ----------------------------------------------------- |
+| OFF_CYCLE_SELECT_REASON | Fired when user selects a reason | { reason: 'bonus' \| 'correction', defaults: object } |
+
+The `defaults` object contains `{ skipDeductions: boolean, withholdingType: 'supplemental' | 'regular' }`.
+
+---
+
+## Deductions setting
+
+Allows users to choose whether to include or skip regular deductions and contributions for the off-cycle payroll. Taxes are always included regardless of the selection.
+
+```jsx
+import { Payroll } from '@gusto/embedded-react-sdk'
+
+function MyComponent() {
+ return {}} />
+}
+```
+
+#### Props
+
+| Name | Type | Description |
+| ------------------------------ | -------- | ------------------------------------------------------- |
+| skipRegularDeductions Required | boolean | Whether regular deductions are currently being skipped. |
+| onEvent Required | function | See events table for available events. |
+| dictionary | object | Optional translations for component text. |
+
+#### Events
+
+| Event type | Description | Data |
+| --------------------------- | --------------------------------------- | ---------------------------------- |
+| OFF_CYCLE_DEDUCTIONS_CHANGE | Fired when deduction preference changes | { skipRegularDeductions: boolean } |
+
+#### Deduction options
+
+- **Include**: Make all the regular deductions and contributions
+- **Skip**: Block all deductions and contributions, except 401(k). Taxes will be included.
diff --git a/docs/surfaces/off-cycle-payroll/workflow.md b/docs/surfaces/off-cycle-payroll/workflow.md
new file mode 100644
index 000000000..467e8cae4
--- /dev/null
+++ b/docs/surfaces/off-cycle-payroll/workflow.md
@@ -0,0 +1,71 @@
+---
+title: Workflow
+description: Drop-in Payroll.OffCycleFlow component that creates the off-cycle payroll and hands off to the standard execution flow.
+order: 1
+---
+
+# Off-Cycle Payroll workflow
+
+The Off-Cycle Payroll workflow renders the full off-cycle experience — bonus or correction creation, then payroll execution — as a single component. After creation, the flow transitions into the standard [Payroll Processing](../run-payroll/run-payroll.mdx) execution experience (configuration, overview, submission, and receipts). All off-cycle payroll types share the same execution steps as regular payrolls — the only difference is how the payroll is created.
+
+---
+
+## Implementation
+
+```jsx
+import { Payroll } from '@gusto/embedded-react-sdk'
+
+function MyApp() {
+ return {}} />
+}
+```
+
+#### Props
+
+| Name | Type | Description |
+| ------------------ | --------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| companyId Required | string | The associated company identifier. |
+| onEvent Required | function | See events table for each subcomponent to see available events. |
+| payrollType | `'bonus'` \| `'correction'` | Optional pre-selected off-cycle reason. When provided, the creation form starts with this reason selected. |
+
+#### Events
+
+Events emitted during the creation phase:
+
+| Event type | Description | Data |
+| ----------------- | ------------------------------------------- | ----------------------- |
+| OFF_CYCLE_CREATED | Fired when the off-cycle payroll is created | { payrollUuid: string } |
+
+Additional events are available when using the standalone subcomponents — see [Sub-components](./sub-components).
+
+Once the payroll is created and the flow transitions to execution, all standard [run payroll events](../run-payroll/workflow#events) are emitted (e.g. `RUN_PAYROLL_CALCULATED`, `RUN_PAYROLL_SUBMITTED`, `RUN_PAYROLL_PROCESSED`).
+
+---
+
+## Workflow steps
+
+1. **Creation**: User configures pay period dates, selects a reason (bonus or correction), chooses employees, and sets deduction/withholding preferences.
+2. **Execution**: The standard payroll execution flow takes over — configure employee compensation, review, submit, and view receipts.
+
+---
+
+## Off-cycle reasons
+
+The creation form presents two reasons with different defaults:
+
+| Reason | Description | Default Deductions | Default Withholding |
+| ---------- | -------------------------------------------------- | -------------------------- | ------------------- |
+| Bonus | Pay a bonus, gift, or commission | Skip regular deductions | Supplemental rate |
+| Correction | Run a payroll outside of your regular pay schedule | Include regular deductions | Regular rate |
+
+When the user changes the reason, deduction and withholding defaults update automatically.
+
+---
+
+## API reference
+
+The off-cycle payroll creation uses the [Create an off-cycle payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-payrolls). After creation, the standard payroll execution endpoints apply:
+
+- **Calculate payroll**: `PUT /v1/companies/{company_id}/payrolls/{payroll_id}/calculate`
+- **Submit payroll**: `PUT /v1/companies/{company_id}/payrolls/{payroll_id}/submit`
+- **Cancel payroll**: `PUT /v1/companies/{company_id}/payrolls/{payroll_id}/cancel`
diff --git a/docs/surfaces/payroll.mdx b/docs/surfaces/payroll.mdx
new file mode 100644
index 000000000..c7bb1d13d
--- /dev/null
+++ b/docs/surfaces/payroll.mdx
@@ -0,0 +1,39 @@
+---
+title: Payroll
+description: SDK surface for running payroll — regular, off-cycle, dismissal, and transition payrolls — and managing payroll history.
+order: 4
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The Payroll surface covers every way a company runs payroll: the regular pay-schedule flow, off-cycle payrolls (bonus or correction), the dismissal payroll for terminated employees, and the transition payroll for pay-schedule changes. All payroll types share the same execution steps; they differ only in how the payroll is created.
+
+
diff --git a/docs/surfaces/run-payroll/run-payroll.mdx b/docs/surfaces/run-payroll/run-payroll.mdx
new file mode 100644
index 000000000..40e4b24a2
--- /dev/null
+++ b/docs/surfaces/run-payroll/run-payroll.mdx
@@ -0,0 +1,92 @@
+---
+title: Payroll processing
+description: End-to-end workflow for running payroll — select a payroll, configure employee compensation, review details, confirm wire transfers, and submit for processing.
+order: 1
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The Payroll Processing workflow guides a company through running a regular payroll: selecting a payroll, configuring employee compensation, reviewing payroll details, confirming wire transfers, and submitting. The full experience can be dropped in as a single component, or assembled from individual sub-components for full control over the surrounding UI.
+
+
+
+## Sub-components
+
+
diff --git a/docs/workflows-overview/run-payroll.md b/docs/surfaces/run-payroll/sub-components.md
similarity index 73%
rename from docs/workflows-overview/run-payroll.md
rename to docs/surfaces/run-payroll/sub-components.md
index c9359b11d..d38cbce3c 100644
--- a/docs/workflows-overview/run-payroll.md
+++ b/docs/surfaces/run-payroll/sub-components.md
@@ -1,77 +1,16 @@
---
-title: Payroll Processing
-description: End-to-end workflow for running payroll — select a payroll, configure employee compensation, review details, confirm wire transfers, and submit for processing.
-order: 3
+title: Sub-components
+description: Standalone sub-components for payroll processing — render in isolation or compose into a custom workflow.
+order: 2
---
-The Run Payroll workflow provides a complete experience for running payroll for a company. It guides users through selecting a payroll, configuring employee compensation, reviewing payroll details, and submitting the payroll for processing.
+# Payroll Processing sub-components
-## Implementation
+Run payroll components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../../integration-guide/composition.md).
-```jsx
-import { Payroll } from '@gusto/embedded-react-sdk'
-
-function MyApp() {
- return {}} />
-}
-```
+---
-### Props
-
-| Name | Type | Description |
-| --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| companyId Required | string | The associated company identifier. |
-| onEvent Required | function | See events table for each subcomponent to see available events. |
-| withReimbursements | boolean | Optional flag to show/hide reimbursements fields. Defaults to true. |
-| defaultValues | object | Optional default values for the workflow. |
-| dictionary | object | Optional translations for component text. |
-| ConfirmWireDetailsComponent | `ComponentType` | Optional custom component to replace the default wire details confirmation UI. See [ConfirmWireDetailsProps](#confirmwiredetailsprops). |
-
-### ConfirmWireDetailsProps
-
-| Prop | Type | Required | Description |
-| --------- | -------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
-| companyId | string | Yes | The company identifier for fetching wire transfer information. |
-| wireInId | string | No | Specific wire-in request identifier. If not provided, your component should handle the first active wire-in request. |
-| onEvent | (type: string, data?: unknown) => void | No | Optional callback to emit events back to the parent flow. |
-
-### Events
-
-| Event type | Description | Data |
-| ------------------------------ | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| RUN_PAYROLL_SELECTED | Fired when user selects a payroll to run | { payrollId: string } |
-| RUN_PAYROLL_BACK | Fired when user navigates back from payroll configuration | None |
-| RUN_PAYROLL_CALCULATED | Fired when payroll calculations are completed | None |
-| RUN_PAYROLL_EDIT | Fired when user makes changes to payroll configuration | None |
-| RUN_PAYROLL_EMPLOYEE_EDITED | Fired when user selects an employee to edit | { employeeId: string } |
-| RUN_PAYROLL_EMPLOYEE_SAVED | Fired when employee payroll changes are saved | { payrollPrepared: object, employee: object } |
-| RUN_PAYROLL_EMPLOYEE_CANCELLED | Fired when user cancels employee payroll editing | None |
-| RUN_PAYROLL_SUBMITTED | Fired when payroll is successfully submitted | [Response from the Submit payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-payrolls-payroll_id-submit) |
-| RUN_PAYROLL_PROCESSED | Fired when payroll processing is completed | None |
-| RUN_PAYROLL_PROCESSING_FAILED | Fired when payroll processing fails | Error details |
-| RUN_PAYROLL_CANCELLED | Fired when a payroll is cancelled | { payrollId: string, result: [Response from the Cancel payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/put-api-v1-companies-company_id-payrolls-payroll_id-cancel) } |
-| RUN_PAYROLL_SUMMARY_VIEWED | Fired when user views payroll summary | { payrollId: string } |
-| RUN_PAYROLL_RECEIPT_VIEWED | Fired when user views payroll receipt | { payrollId: string } |
-
-## Using Payroll Subcomponents
-
-Run payroll components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../integration-guide/composition.md).
-
-### Available Subcomponents
-
-- [Payroll.PayrollLanding](#payrollpayrolllanding)
-- [Payroll.PayrollList](#payrollpayrolllist)
-- [Payroll.PayrollHistory](#payrollpayrollhistory)
-- [Payroll.PayrollConfiguration](#payrollpayrollconfiguration)
-- [Payroll.PayrollEditEmployee](#payrollpayrolleditemployee)
-- [Payroll.PayrollOverview](#payrollpayrolloverview)
-- [Payroll.PayrollExecutionFlow](#payrollpayrollexecutionflow)
-- [Payroll.PayrollReceipts](#payrollpayrollreceipts)
-- [Payroll.PayrollBlockerList](#payrollpayrollblockerlist)
-- [Payroll.RecoveryCases](#payrollrecoverycases)
-- [Payroll.ConfirmWireDetails](#payrollconfirmwiredetails)
-
-### Payroll.PayrollLanding
+## Landing
Provides the main landing page for payroll operations, including tabs for running payroll and viewing payroll history.
@@ -85,13 +24,13 @@ function MyComponent() {
#### Props
-| Name | Type | Description |
-| --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| companyId Required | string | The associated company identifier. |
-| onEvent Required | function | See events table for available events. |
-| withReimbursements | boolean | Optional flag to show/hide reimbursements fields. Defaults to true. |
-| dictionary | object | Optional translations for component text. |
-| ConfirmWireDetailsComponent | `ComponentType` | Optional custom component to replace the default wire details confirmation UI. See [ConfirmWireDetailsProps](#confirmwiredetailsprops). |
+| Name | Type | Description |
+| --------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| companyId Required | string | The associated company identifier. |
+| onEvent Required | function | See events table for available events. |
+| withReimbursements | boolean | Optional flag to show/hide reimbursements fields. Defaults to true. |
+| dictionary | object | Optional translations for component text. |
+| ConfirmWireDetailsComponent | `ComponentType` | Optional custom component to replace the default wire details confirmation UI. See [Workflow props](./workflow#confirmwiredetailsprops). |
#### Events
@@ -100,7 +39,9 @@ function MyComponent() {
| RUN_PAYROLL_SUMMARY_VIEWED | Fired when user views payroll summary | { payrollId: string } |
| RUN_PAYROLL_RECEIPT_VIEWED | Fired when user views payroll receipt | { payrollId: string } |
-### Payroll.PayrollList
+---
+
+## Payroll list
Displays a list of available payrolls that can be run, including pay period dates and status information. Users can run payrolls, submit calculated payrolls, skip payrolls, and view any payroll blockers.
@@ -131,7 +72,9 @@ function MyComponent() {
| PAYROLL_SKIPPED | Fired when a payroll is successfully skipped | { payrollId: string } |
| RUN_PAYROLL_BLOCKERS_VIEW_ALL | Fired when user views all payroll blockers | None |
-### Payroll.PayrollHistory
+---
+
+## History
Displays historical payroll records with advanced filtering and management capabilities:
@@ -164,7 +107,9 @@ function MyComponent() {
| RUN_PAYROLL_RECEIPT_VIEWED | Fired when user views payroll receipt | { payrollId: string } |
| RUN_PAYROLL_CANCELLED | Fired when a payroll is cancelled | { payrollId: string, result: [Response from the Cancel payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/put-api-v1-companies-company_id-payrolls-payroll_id-cancel) } |
-### Payroll.PayrollConfiguration
+---
+
+## Configuration
Handles the configuration phase of payroll processing, allowing users to review and modify employee compensation before calculating the payroll.
@@ -205,7 +150,9 @@ function MyComponent() {
| RUN_PAYROLL_PROCESSING_FAILED | Fired when payroll processing fails | Error details |
| RUN_PAYROLL_BLOCKERS_VIEW_ALL | Fired when user views all payroll blockers | None |
-### Payroll.PayrollEditEmployee
+---
+
+## Edit employee
Used for editing individual employee compensation details within a payroll. This component allows modification of employee pay rates, hours, bonuses, and other compensation elements.
@@ -242,7 +189,9 @@ function MyComponent() {
| RUN_PAYROLL_EMPLOYEE_SAVED | Fired when employee payroll compensation changes are saved | { payrollPrepared: [Response from the Update payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-payrolls), employee: object } |
| RUN_PAYROLL_EMPLOYEE_CANCELLED | Fired when user cancels editing employee payroll compensation | None |
-### Payroll.PayrollOverview
+---
+
+## Overview
Displays the final payroll overview before submission, including totals, employee details, and submission controls. Once submitted, it tracks the processing status and displays confirmation when complete.
@@ -262,16 +211,16 @@ function MyComponent() {
#### Props
-| Name | Type | Description |
-| --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| companyId Required | string | The associated company identifier. |
-| payrollId Required | string | The associated payroll identifier. |
-| onEvent Required | function | See events table for available events. |
-| alerts | array | Optional array of alert objects to display. |
-| showBackButton | boolean | Optional flag to show back button. |
-| withReimbursements | boolean | Optional flag to show/hide reimbursements fields. Defaults to true. |
-| dictionary | object | Optional translations for component text. |
-| ConfirmWireDetailsComponent | `ComponentType` | Optional custom component to replace the default wire details confirmation UI. See [ConfirmWireDetailsProps](#confirmwiredetailsprops). |
+| Name | Type | Description |
+| --------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| companyId Required | string | The associated company identifier. |
+| payrollId Required | string | The associated payroll identifier. |
+| onEvent Required | function | See events table for available events. |
+| alerts | array | Optional array of alert objects to display. |
+| showBackButton | boolean | Optional flag to show back button. |
+| withReimbursements | boolean | Optional flag to show/hide reimbursements fields. Defaults to true. |
+| dictionary | object | Optional translations for component text. |
+| ConfirmWireDetailsComponent | `ComponentType` | Optional custom component to replace the default wire details confirmation UI. See [Workflow props](./workflow#confirmwiredetailsprops). |
#### Events
@@ -286,9 +235,11 @@ function MyComponent() {
| RUN_PAYROLL_RECEIPT_GET | Fired when user requests payroll receipt | { payrollId: string } |
| RUN_PAYROLL_PDF_PAYSTUB_VIEWED | Fired when user views employee paystub PDF | { employeeId: string } |
-### Payroll.PayrollExecutionFlow
+---
-The shared execution flow that runs the **configuration → overview → submission → receipt** steps for a single payroll. This is the inner flow that powers the back half of `Payroll.PayrollFlow`, and it is also reused by the [off-cycle](./off-cycle-payroll.md), [dismissal](./dismissal-payroll.md), and [transition](./transition-payroll.md) flows after they have created their respective payrolls.
+## Execution flow
+
+The shared execution flow that runs the **configuration → overview → submission → receipt** steps for a single payroll. This is the inner flow that powers the back half of `Payroll.PayrollFlow`, and it is also reused by the [off-cycle](../off-cycle-payroll/off-cycle-payroll.mdx), [dismissal](../dismissal-payroll/dismissal-payroll.mdx), and [transition](../transition-payroll/transition-payroll.mdx) flows after they have created their respective payrolls.
Use this component directly when you have built your own payroll-creation step (e.g. a custom intake form) and want to hand the user off to the standard execution experience without re-implementing it. The flow ships with breadcrumb navigation, the standard wire-confirmation UX, and emits the same `RUN_PAYROLL_*` events as the full `PayrollFlow`.
@@ -317,14 +268,16 @@ function MyComponent() {
| initialState | `'configuration'` \| `'overview'` | `'configuration'` | Where the flow starts. Use `'overview'` when you want to drop the user directly on the review screen (e.g. resuming an already-calculated payroll). |
| isDismissalPayroll | boolean | `false` | When true, surfaces dismissal-specific copy and breadcrumbs (used by `Payroll.DismissalFlow`). |
| withReimbursements | boolean | `true` | Optional flag to show/hide reimbursement fields throughout the flow. |
-| ConfirmWireDetailsComponent | `ComponentType` | | Optional custom component to replace the default wire details confirmation UI. See [ConfirmWireDetailsProps](#confirmwiredetailsprops). |
+| ConfirmWireDetailsComponent | `ComponentType` | | Optional custom component to replace the default wire details confirmation UI. See [Workflow props](./workflow#confirmwiredetailsprops). |
| prefixBreadcrumbs | `FlowBreadcrumb[]` | `[]` | Optional breadcrumbs prepended to the flow's own breadcrumb trail. Useful when embedding inside a parent flow (e.g. an off-cycle creation step) so the breadcrumb history remains coherent. |
#### Events
-Emits the same events as `Payroll.PayrollFlow` during execution — see the [main events table](#events) at the top of this page (e.g. `RUN_PAYROLL_CALCULATED`, `RUN_PAYROLL_EMPLOYEE_EDIT`, `RUN_PAYROLL_SUBMITTED`, `RUN_PAYROLL_PROCESSED`, `RUN_PAYROLL_RECEIPT_VIEWED`).
+Emits the same events as `Payroll.PayrollFlow` during execution — see the [main events table](./workflow#events) on the workflow page (e.g. `RUN_PAYROLL_CALCULATED`, `RUN_PAYROLL_EMPLOYEE_EDIT`, `RUN_PAYROLL_SUBMITTED`, `RUN_PAYROLL_PROCESSED`, `RUN_PAYROLL_RECEIPT_VIEWED`).
+
+---
-### Payroll.PayrollReceipts
+## Receipts
Displays a detailed receipt for a completed payroll, including all payment information, deductions, taxes, and totals. This component provides a comprehensive view of a processed payroll for record-keeping and review purposes.
@@ -352,7 +305,9 @@ function MyComponent() {
| ---------------- | ------------------------------ | ---- |
| RUN_PAYROLL_BACK | Fired when user navigates back | None |
-### Payroll.PayrollBlockerList
+---
+
+## Blockers
Displays a list of blockers that prevent payroll from being processed. Blockers indicate issues that must be resolved before a payroll can be calculated or submitted, such as missing employee information, invalid tax setups, or incomplete company configuration.
@@ -376,7 +331,9 @@ function MyComponent() {
This component does not emit any events. It displays blockers fetched from the API and provides information to help users resolve issues.
-### Payroll.RecoveryCases
+---
+
+## Recovery cases
Displays open recovery cases for a company and provides an in-modal resubmit workflow for resolving them. Recovery cases are issues that arise after a payroll has been submitted (for example, a returned ACH transfer) and must be resolved before subsequent payrolls can run cleanly. The component is also embedded inside `Payroll.PayrollBlockerList`, but can be used standalone when you want a dedicated recovery cases surface.
@@ -403,7 +360,9 @@ function MyComponent() {
| RECOVERY_CASE_RESUBMIT_DONE | Fired when the user successfully resubmits a recovery case | Resubmit result payload |
| RECOVERY_CASE_RESUBMIT_CANCEL | Fired when the user cancels the resubmit modal | None |
-### Payroll.ConfirmWireDetails
+---
+
+## Wire transfer confirmation
Provides the wire transfer confirmation workflow for payroll funding. This component displays a banner when wire transfers are awaiting funds and allows users to view wire instructions and confirm transfer details through a modal interface.
diff --git a/docs/surfaces/run-payroll/workflow.md b/docs/surfaces/run-payroll/workflow.md
new file mode 100644
index 000000000..bc620aa56
--- /dev/null
+++ b/docs/surfaces/run-payroll/workflow.md
@@ -0,0 +1,58 @@
+---
+title: Workflow
+description: Drop-in Payroll.PayrollFlow component that renders the entire payroll processing experience.
+order: 1
+---
+
+# Payroll Processing workflow
+
+The Payroll Processing workflow renders the full regular-payroll experience as a single component. Drop it into your app and the user walks through selecting a payroll, configuring employee compensation, reviewing details, confirming wire transfers, and submitting.
+
+---
+
+## Implementation
+
+```jsx
+import { Payroll } from '@gusto/embedded-react-sdk'
+
+function MyApp() {
+ return {}} />
+}
+```
+
+#### Props
+
+| Name | Type | Description |
+| --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| companyId Required | string | The associated company identifier. |
+| onEvent Required | function | See events table for each subcomponent to see available events. |
+| withReimbursements | boolean | Optional flag to show/hide reimbursements fields. Defaults to true. |
+| defaultValues | object | Optional default values for the workflow. |
+| dictionary | object | Optional translations for component text. |
+| ConfirmWireDetailsComponent | `ComponentType` | Optional custom component to replace the default wire details confirmation UI. See [ConfirmWireDetailsProps](#confirmwiredetailsprops). |
+
+#### ConfirmWireDetailsProps
+
+| Prop | Type | Required | Description |
+| --------- | -------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
+| companyId | string | Yes | The company identifier for fetching wire transfer information. |
+| wireInId | string | No | Specific wire-in request identifier. If not provided, your component should handle the first active wire-in request. |
+| onEvent | (type: string, data?: unknown) => void | No | Optional callback to emit events back to the parent flow. |
+
+#### Events
+
+| Event type | Description | Data |
+| ------------------------------ | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| RUN_PAYROLL_SELECTED | Fired when user selects a payroll to run | { payrollId: string } |
+| RUN_PAYROLL_BACK | Fired when user navigates back from payroll configuration | None |
+| RUN_PAYROLL_CALCULATED | Fired when payroll calculations are completed | None |
+| RUN_PAYROLL_EDIT | Fired when user makes changes to payroll configuration | None |
+| RUN_PAYROLL_EMPLOYEE_EDITED | Fired when user selects an employee to edit | { employeeId: string } |
+| RUN_PAYROLL_EMPLOYEE_SAVED | Fired when employee payroll changes are saved | { payrollPrepared: object, employee: object } |
+| RUN_PAYROLL_EMPLOYEE_CANCELLED | Fired when user cancels employee payroll editing | None |
+| RUN_PAYROLL_SUBMITTED | Fired when payroll is successfully submitted | [Response from the Submit payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-payrolls-payroll_id-submit) |
+| RUN_PAYROLL_PROCESSED | Fired when payroll processing is completed | None |
+| RUN_PAYROLL_PROCESSING_FAILED | Fired when payroll processing fails | Error details |
+| RUN_PAYROLL_CANCELLED | Fired when a payroll is cancelled | { payrollId: string, result: [Response from the Cancel payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/put-api-v1-companies-company_id-payrolls-payroll_id-cancel) } |
+| RUN_PAYROLL_SUMMARY_VIEWED | Fired when user views payroll summary | { payrollId: string } |
+| RUN_PAYROLL_RECEIPT_VIEWED | Fired when user views payroll receipt | { payrollId: string } |
diff --git a/docs/surfaces/surfaces.mdx b/docs/surfaces/surfaces.mdx
new file mode 100644
index 000000000..7f8fb3eaa
--- /dev/null
+++ b/docs/surfaces/surfaces.mdx
@@ -0,0 +1,11 @@
+---
+title: Surfaces
+description: Pre-built React experiences covering company, employee, contractor, and payroll workflows.
+order: 4
+---
+
+import SurfacesGrid from '@site/src/components/SurfacesGrid'
+
+The SDK ships pre-built surfaces for the four core areas of running payroll: companies, employees, contractors, and payroll itself. Each surface is a single React component that drops a full multi-step experience into your app.
+
+
diff --git a/docs/workflows-overview/time-off.md b/docs/surfaces/time-off.md
similarity index 100%
rename from docs/workflows-overview/time-off.md
rename to docs/surfaces/time-off.md
diff --git a/docs/surfaces/transition-payroll/sub-components.md b/docs/surfaces/transition-payroll/sub-components.md
new file mode 100644
index 000000000..d0a5e5310
--- /dev/null
+++ b/docs/surfaces/transition-payroll/sub-components.md
@@ -0,0 +1,58 @@
+---
+title: Sub-components
+description: Standalone sub-components for transition payroll — render in isolation or compose into a custom workflow.
+order: 2
+---
+
+# Transition Payroll sub-components
+
+Transition payroll components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../../integration-guide/composition.md).
+
+After creation, the flow hands off to the shared [`Payroll.PayrollExecutionFlow`](../run-payroll/sub-components#execution-flow) for the configuration → overview → submission → receipts steps. If you build your own creation step in front of the standard execution UI, render `Payroll.PayrollExecutionFlow` directly with the payroll you created.
+
+---
+
+## Transition creation
+
+The creation form for transition payrolls. Displays the transition pay period and pay schedule information, and allows configuration of check date, deductions, and tax withholding.
+
+```jsx
+import { Payroll } from '@gusto/embedded-react-sdk'
+
+function MyComponent() {
+ return (
+ {}}
+ />
+ )
+}
+```
+
+#### Props
+
+| Name | Type | Description |
+| ------------------------ | -------- | -------------------------------------------- |
+| companyId Required | string | The associated company identifier. |
+| startDate Required | string | The start date of the transition pay period. |
+| endDate Required | string | The end date of the transition pay period. |
+| payScheduleUuid Required | string | The UUID of the associated pay schedule. |
+| onEvent Required | function | See events table for available events. |
+| dictionary | object | Optional translations for component text. |
+
+#### Events
+
+| Event type | Description | Data |
+| ------------------ | -------------------------------------------- | ----------------------- |
+| TRANSITION_CREATED | Fired when the transition payroll is created | { payrollUuid: string } |
+
+#### Form fields
+
+- **Pay period** (read-only): Displays the transition pay period start and end dates
+- **Pay schedule** (read-only): Shows the name of the associated pay schedule, when available
+- **Check date**: The date employees will be paid (must be at least 2 business days from today for ACH processing)
+- **Deductions and contributions**: Include or skip regular deductions. Defaults to including deductions.
+- **Tax withholding rates**: Configure withholding pay period frequency and rate type (regular or supplemental). Defaults to regular rate with every-other-week frequency.
diff --git a/docs/surfaces/transition-payroll/transition-payroll.mdx b/docs/surfaces/transition-payroll/transition-payroll.mdx
new file mode 100644
index 000000000..ac55911ab
--- /dev/null
+++ b/docs/surfaces/transition-payroll/transition-payroll.mdx
@@ -0,0 +1,35 @@
+---
+title: Transition payroll
+description: Workflow for running payrolls that cover gaps between old and new pay schedules, plus the alert surfaced inside the payroll landing for unprocessed transition periods.
+order: 4
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The Transition Payroll workflow handles payrolls that cover gaps between old and new pay schedules. When a company changes its pay schedule, there may be workdays that fall between the end of the old schedule and the start of the new one — transition payrolls ensure employees are paid for those days. The SDK provides a flow component for running a specific transition payroll and an integrated alert (rendered inside `Payroll.PayrollLanding`) that surfaces unprocessed transition periods.
+
+
+
+## Sub-components
+
+
diff --git a/docs/workflows-overview/transition-payroll.md b/docs/surfaces/transition-payroll/workflow.md
similarity index 54%
rename from docs/workflows-overview/transition-payroll.md
rename to docs/surfaces/transition-payroll/workflow.md
index f90b5455b..8e007a3b5 100644
--- a/docs/workflows-overview/transition-payroll.md
+++ b/docs/surfaces/transition-payroll/workflow.md
@@ -1,15 +1,16 @@
---
-title: Transition Payroll
-description: Workflow for running payrolls that cover gaps between old and new pay schedules, including an alert surfaced in PayrollLanding for unprocessed transition periods.
-order: 7
+title: Workflow
+description: Drop-in Payroll.TransitionFlow component that creates a transition payroll and hands off to the standard execution flow.
+order: 1
---
-The Transition Payroll workflow handles payrolls that cover gaps between old and new pay schedules. When a company changes its pay schedule, there may be workdays that fall between the end of the old schedule and the start of the new one. Transition payrolls ensure employees are paid for those days.
+# Transition Payroll workflow
-The SDK provides a flow component and an integrated alert for transition payrolls:
+The Transition Payroll workflow renders the full experience — creation, then standard payroll execution — for a transition payroll covering the gap between an old and new pay schedule.
-- **`Payroll.TransitionFlow`**: A full creation-to-execution flow for running a specific transition payroll. After creation, the flow transitions into the standard [Payroll Processing](./run-payroll.md) execution experience — the same steps used by regular and other off-cycle payrolls.
-- **Transition Payroll Alert**: An alert automatically rendered within `Payroll.PayrollLanding` when there are unprocessed transition pay periods. It surfaces upcoming transition periods and allows users to run or skip them. This is not a standalone export — it is built into the landing page.
+After creation, the flow transitions into the standard [Payroll Processing](../run-payroll/run-payroll.mdx) execution experience — the same steps used by regular and other off-cycle payrolls.
+
+---
## Implementation
@@ -29,7 +30,7 @@ function MyApp() {
}
```
-### Props
+#### Props
| Name | Type | Description |
| ------------------------ | -------- | ---------------------------------------------------------------- |
@@ -39,7 +40,7 @@ function MyApp() {
| payScheduleUuid Required | string | The UUID of the pay schedule this transition is associated with. |
| onEvent Required | function | See events table for each subcomponent to see available events. |
-### Events
+#### Events
Events emitted during the creation phase:
@@ -47,84 +48,33 @@ Events emitted during the creation phase:
| ------------------ | -------------------------------------------- | ----------------------- |
| TRANSITION_CREATED | Fired when the transition payroll is created | { payrollUuid: string } |
-Once the payroll is created and the flow transitions to execution, all standard [run payroll events](./run-payroll.md) are emitted (e.g. `RUN_PAYROLL_CALCULATED`, `RUN_PAYROLL_SUBMITTED`, `RUN_PAYROLL_PROCESSED`).
-
-## Workflow Steps
-
-1. **Creation**: Displays the transition details (pay period dates, pay schedule name) and allows the user to configure the check date, deduction preferences, and tax withholding rates
-2. **Execution**: The standard payroll execution flow takes over — configure employee compensation, review, submit, and view receipts
-
-## Using Transition Subcomponents
-
-Transition payroll components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../integration-guide/composition.md).
-
-### Available Subcomponents
-
-- [Payroll.TransitionCreation](#payrolltransitioncreation)
-
-After creation, the flow hands off to the shared [`Payroll.PayrollExecutionFlow`](./run-payroll.md#payrollpayrollexecutionflow) for the configuration → overview → submission → receipts steps. If you build your own creation step in front of the standard execution UI, render `Payroll.PayrollExecutionFlow` directly with the payroll you created.
-
-### Payroll.TransitionCreation
-
-The creation form for transition payrolls. Displays the transition pay period and pay schedule information, and allows configuration of check date, deductions, and tax withholding.
-
-```jsx
-import { Payroll } from '@gusto/embedded-react-sdk'
-
-function MyComponent() {
- return (
- {}}
- />
- )
-}
-```
-
-#### Props
-
-| Name | Type | Description |
-| ------------------------ | -------- | -------------------------------------------- |
-| companyId Required | string | The associated company identifier. |
-| startDate Required | string | The start date of the transition pay period. |
-| endDate Required | string | The end date of the transition pay period. |
-| payScheduleUuid Required | string | The UUID of the associated pay schedule. |
-| onEvent Required | function | See events table for available events. |
-| dictionary | object | Optional translations for component text. |
+Once the payroll is created and the flow transitions to execution, all standard [run payroll events](../run-payroll/workflow#events) are emitted (e.g. `RUN_PAYROLL_CALCULATED`, `RUN_PAYROLL_SUBMITTED`, `RUN_PAYROLL_PROCESSED`).
-#### Events
+---
-| Event type | Description | Data |
-| ------------------ | -------------------------------------------- | ----------------------- |
-| TRANSITION_CREATED | Fired when the transition payroll is created | { payrollUuid: string } |
+## Workflow steps
-#### Form Fields
+1. **Creation**: Displays the transition details (pay period dates, pay schedule name) and allows the user to configure the check date, deduction preferences, and tax withholding rates.
+2. **Execution**: The standard payroll execution flow takes over — configure employee compensation, review, submit, and view receipts.
-- **Pay period** (read-only): Displays the transition pay period start and end dates
-- **Pay schedule** (read-only): Shows the name of the associated pay schedule, when available
-- **Check date**: The date employees will be paid (must be at least 2 business days from today for ACH processing)
-- **Deductions and contributions**: Include or skip regular deductions. Defaults to including deductions.
-- **Tax withholding rates**: Configure withholding pay period frequency and rate type (regular or supplemental). Defaults to regular rate with every-other-week frequency.
+---
-## Transition Payroll Alert
+## Transition payroll alert
-The transition payroll alert is automatically rendered within `Payroll.PayrollLanding` when there are unprocessed transition pay periods. It looks ahead 90 days for upcoming transition periods, groups them by pay schedule, and presents options to run or skip each one.
+The transition payroll alert is automatically rendered within [`Payroll.PayrollLanding`](../run-payroll/sub-components#landing) when there are unprocessed transition pay periods. It looks ahead 90 days for upcoming transition periods, groups them by pay schedule, and presents options to run or skip each one.
The alert explains why transition payrolls are needed and warns that skipping means employees will not be paid for the transition period.
> **Important**: Transition pay periods should be resolved (either run or skipped) before the company runs regular payrolls. The Gusto API may enforce this requirement by returning errors when attempting to process regular payrolls while unresolved transition periods exist.
-### Alert Events
+### Alert events
| Event type | Description | Data |
| -------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------- |
| RUN_TRANSITION_PAYROLL | Fired when user chooses to run a transition payroll | { startDate: string, endDate: string, payScheduleUuid: string \| undefined } |
| TRANSITION_PAYROLL_SKIPPED | Fired when a transition payroll is skipped | { startDate: string, endDate: string, payScheduleUuid: string \| undefined } |
-### Handling the Run Transition Event
+### Handling the run transition event
When the `RUN_TRANSITION_PAYROLL` event is emitted from the Payroll Landing page, your application should render the `Payroll.TransitionFlow` component with the provided dates and pay schedule UUID:
@@ -159,11 +109,15 @@ function PayrollPage({ companyId }) {
> **Note**: The example guards on `data.payScheduleUuid` because `Payroll.TransitionFlow` requires it as a prop. In practice, `payScheduleUuid` is expected to be present for transition pay periods, but the event type allows `undefined`. If you need to handle the undefined case, add your own fallback logic (e.g. displaying an error or refetching pay schedule data).
-### Skipping a Transition Payroll
+---
+
+## Skipping a transition payroll
Users can skip transition payrolls directly from the alert. A confirmation dialog warns that skipping means employees will not be paid for the transition period and that it is the employer's responsibility to ensure proper payment. Upon confirmation, the payroll is skipped via the [Skip a payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/post-companies-payroll-skip-company_uuid).
-## API Reference
+---
+
+## API reference
The transition payroll uses these API endpoints:
diff --git a/docs/workflows-overview/information-requests.md b/docs/workflows-overview/information-requests.md
deleted file mode 100644
index 1aa56ba31..000000000
--- a/docs/workflows-overview/information-requests.md
+++ /dev/null
@@ -1,141 +0,0 @@
----
-title: Information Requests
-description: Standalone surface for viewing and responding to outstanding information requests Gusto has issued for a company, such as missing tax or identity documents.
-order: 8
----
-
-The Information Requests workflow surfaces outstanding information requests that Gusto has issued for a company (for example, a request for a missing tax document or identity verification artifact) and lets the user respond to them. Information requests can also block payroll processing, in which case they are surfaced inline within `Payroll.PayrollBlockerList`; this flow provides a dedicated, standalone surface for managing them.
-
-## Implementation
-
-```jsx
-import { InformationRequests } from '@gusto/embedded-react-sdk'
-
-function MyApp() {
- return (
- {}}
- />
- )
-}
-```
-
-### Props
-
-| Name | Type | Default | Description |
-| ------------------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| companyId Required | string | | The associated company identifier. |
-| onEvent | function | | See events table for each subcomponent to see available events. |
-| withAlert | boolean | `true` | When true, the submission success alert is rendered at the top of the flow. Set to false when embedding in a parent (e.g. `Payroll.PayrollBlockerList`) that renders the alert elsewhere. |
-| dictionary | object | | Optional translations for component text. |
-
-### Events
-
-Events emitted by the flow (and by its subcomponents — they bubble up through `onEvent`):
-
-| Event type | Description | Data |
-| ------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------- |
-| INFORMATION_REQUEST_RESPOND | Fired when the user clicks "Respond" on a request and the form modal opens | { requestId: string } |
-| INFORMATION_REQUEST_FORM_DONE | Fired when an information request is successfully submitted | Response from the Submit information request endpoint |
-| INFORMATION_REQUEST_FORM_CANCEL | Fired when the user cancels the response form (closes the modal without submitting) | None |
-
-## Workflow Steps
-
-1. **List**: The user sees all open and submitted information requests for the company, with status badges and a "Respond" CTA on each open request.
-2. **Respond**: Selecting "Respond" opens a modal with a dynamically rendered form built from the request's required questions (text, document upload). Persona-style questions and other unsupported response types fall back to a guidance message rather than rendering the form.
-3. **Submit**: On successful submit, a dismissible success alert appears at the top of the list (when `withAlert` is true) and the modal closes.
-
-## Using Information Requests Subcomponents
-
-Information requests components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../integration-guide/composition.md).
-
-### Available Subcomponents
-
-- [InformationRequests.InformationRequestList](#informationrequestsinformationrequestlist)
-- [InformationRequests.InformationRequestForm](#informationrequestsinformationrequestform)
-
-### InformationRequests.InformationRequestList
-
-Displays a list of information requests for a company, including status badges (Open / Submitted) and a "Respond" CTA for open requests. Used as the top-level surface of `InformationRequests.InformationRequestsFlow`, but can be rendered directly when you want to host the response form yourself (e.g. in a custom modal or page).
-
-```jsx
-import { InformationRequests } from '@gusto/embedded-react-sdk'
-
-function MyComponent() {
- return (
- {}}
- />
- )
-}
-```
-
-#### Props
-
-| Name | Type | Description |
-| ------------------------ | -------- | ----------------------------------------- |
-| **companyId** (Required) | string | The associated company identifier. |
-| **onEvent** (Required) | function | See events table for available events. |
-| dictionary | object | Optional translations for component text. |
-
-#### Events
-
-| Event type | Description | Data |
-| --------------------------- | ------------------------------------------------------- | --------------------- |
-| INFORMATION_REQUEST_RESPOND | Fired when the user clicks "Respond" on an open request | { requestId: string } |
-
-### InformationRequests.InformationRequestForm
-
-The dynamic response form for a single information request. Renders supported question types (text and document upload) based on the request's `requiredQuestions` payload from the API and submits responses via the [Submit information request endpoint](https://docs.gusto.com/embedded-payroll/reference/post-information-requests-submit). Use this component directly when you have built your own list/routing surface and need to host the form (typically inside a modal or page you control).
-
-```jsx
-import { InformationRequests } from '@gusto/embedded-react-sdk'
-
-function MyComponent() {
- return (
- {}}
- />
- )
-}
-```
-
-#### Props
-
-| Name | Type | Description |
-| ------------------------ | -------- | -------------------------------------------------------- |
-| **companyId** (Required) | string | The associated company identifier. |
-| **requestId** (Required) | string | The identifier of the information request to respond to. |
-| **onEvent** (Required) | function | See events table for available events. |
-| dictionary | object | Optional translations for component text. |
-
-#### Events
-
-| Event type | Description | Data |
-| ------------------------------- | --------------------------------------------- | ----------------------------------------------------- |
-| INFORMATION_REQUEST_FORM_DONE | Fired when the form is successfully submitted | Response from the Submit information request endpoint |
-| INFORMATION_REQUEST_FORM_CANCEL | Fired when the user cancels the form | None |
-
-#### Supported Response Types
-
-The form currently renders inputs for the following `responseType` values:
-
-- **`text`** — single-line text input (max 5,000 characters)
-- **`document`** — file upload restricted to JPEG, PNG, or PDF
-
-Requests with unsupported response types (e.g. `persona`-driven identity verification) display a guidance message instead of the form. In those cases the user must complete the request through the partner's own integration with the underlying provider.
-
-## Integration with Payroll Blockers
-
-Information requests can also block payroll processing. When that happens they are surfaced inside [`Payroll.PayrollBlockerList`](./run-payroll.md#payrollpayrollblockerlist), which embeds `InformationRequests.InformationRequestsFlow` with `withAlert={false}` so the blocker list owns the success alert UX. If you build your own blocker resolution surface, you can use the same pattern.
-
-## API Reference
-
-The information requests workflow uses these API endpoints:
-
-- **List information requests**: `GET /v1/companies/{company_uuid}/information_requests`
-- **Submit an information request**: `POST /v1/information_requests/{information_request_uuid}/submit`
diff --git a/docs/workflows-overview/off-cycle-payroll.md b/docs/workflows-overview/off-cycle-payroll.md
deleted file mode 100644
index c2e24a956..000000000
--- a/docs/workflows-overview/off-cycle-payroll.md
+++ /dev/null
@@ -1,172 +0,0 @@
----
-title: Off-Cycle Payroll (Bonus & Correction)
-description: Workflow for running payrolls outside the regular pay schedule — bonus or correction — then transitioning into the standard payroll processing execution.
-order: 5
----
-
-The Off-Cycle Payroll workflow provides a complete experience for running payrolls outside of a company's regular pay schedule. It supports two off-cycle reasons: **Bonus** (paying a bonus, gift, or commission) and **Correction** (running a correction payment). The flow guides users through configuring pay period dates, selecting a reason, choosing employees, setting deduction and tax withholding preferences, and then executing the payroll.
-
-After creation, the flow transitions into the standard [Payroll Processing](./run-payroll.md) execution experience (configuration, overview, submission, and receipts). All off-cycle payroll types share the same execution steps as regular payrolls — the only difference is how the payroll is created.
-
-## Implementation
-
-```jsx
-import { Payroll } from '@gusto/embedded-react-sdk'
-
-function MyApp() {
- return {}} />
-}
-```
-
-### Props
-
-| Name | Type | Description |
-| ------------------ | --------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| companyId Required | string | The associated company identifier. |
-| onEvent Required | function | See events table for each subcomponent to see available events. |
-| payrollType | `'bonus'` \| `'correction'` | Optional pre-selected off-cycle reason. When provided, the creation form starts with this reason selected. |
-
-### Events
-
-Events emitted during the creation phase:
-
-| Event type | Description | Data |
-| ----------------- | ------------------------------------------- | ----------------------- |
-| OFF_CYCLE_CREATED | Fired when the off-cycle payroll is created | { payrollUuid: string } |
-
-Additional events are available when using the standalone subcomponents (`Payroll.OffCycleReasonSelection` and `Payroll.OffCycleDeductionsSetting`) — see their individual event tables below.
-
-Once the payroll is created and the flow transitions to execution, all standard [run payroll events](./run-payroll.md) are emitted (e.g. `RUN_PAYROLL_CALCULATED`, `RUN_PAYROLL_SUBMITTED`, `RUN_PAYROLL_PROCESSED`).
-
-## Workflow Steps
-
-1. **Creation**: User configures pay period dates, selects a reason (bonus or correction), chooses employees, and sets deduction/withholding preferences
-2. **Execution**: The standard payroll execution flow takes over — configure employee compensation, review, submit, and view receipts
-
-## Off-Cycle Reasons
-
-The creation form presents two reasons with different defaults:
-
-| Reason | Description | Default Deductions | Default Withholding |
-| ---------- | -------------------------------------------------- | -------------------------- | ------------------- |
-| Bonus | Pay a bonus, gift, or commission | Skip regular deductions | Supplemental rate |
-| Correction | Run a payroll outside of your regular pay schedule | Include regular deductions | Regular rate |
-
-When the user changes the reason, deduction and withholding defaults update automatically.
-
-## Using Off-Cycle Subcomponents
-
-Off-cycle components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../integration-guide/composition.md).
-
-### Available Subcomponents
-
-- [Payroll.OffCycleCreation](#payrolloffcyclecreation)
-- [Payroll.OffCycleReasonSelection](#payrolloffcyclereasonselection)
-- [Payroll.OffCycleDeductionsSetting](#payrolloffcycledeductionssetting)
-
-After creation, the flow hands off to the shared [`Payroll.PayrollExecutionFlow`](./run-payroll.md#payrollpayrollexecutionflow) for the configuration → overview → submission → receipts steps. If you build your own creation step in front of the standard execution UI, render `Payroll.PayrollExecutionFlow` directly with the payroll you created.
-
-### Payroll.OffCycleCreation
-
-The main creation form for off-cycle payrolls. Includes reason selection, pay period date configuration, employee selection, deduction settings, and tax withholding configuration.
-
-```jsx
-import { Payroll } from '@gusto/embedded-react-sdk'
-
-function MyComponent() {
- return {}} />
-}
-```
-
-#### Props
-
-| Name | Type | Description |
-| ------------------ | --------------------------- | ---------------------------------------------------------- |
-| companyId Required | string | The associated company identifier. |
-| onEvent Required | function | See events table for available events. |
-| payrollType | `'bonus'` \| `'correction'` | Optional pre-selected payroll type. Defaults to `'bonus'`. |
-| dictionary | object | Optional translations for component text. |
-
-#### Events
-
-| Event type | Description | Data |
-| ----------------- | ------------------------------------------- | ----------------------- |
-| OFF_CYCLE_CREATED | Fired when the off-cycle payroll is created | { payrollUuid: string } |
-
-#### Form Fields
-
-- **Check-only payroll**: Toggle for check-only payments — when enabled, all employees will be paid by check (not direct deposit), the check date can be set to today or any future date, and start/end dates are not required
-- **Start date**: Beginning of the pay period (required unless check-only; cannot be in the future for correction payrolls)
-- **End date**: End of the pay period (required unless check-only; must be on or after start date)
-- **Payment date (check date)**: The date employees will be paid (must be at least 2 business days from today for direct deposit, unless check-only)
-- **Reason**: Bonus or Correction payment
-- **Employee selection**: Include all employees or select specific employees
-- **Deductions and contributions**: Include or skip regular deductions (see [OffCycleDeductionsSetting](#payrolloffcycledeductionssetting))
-- **Tax withholding rates**: Configure withholding pay period and rate type (regular or supplemental)
-
-### Payroll.OffCycleReasonSelection
-
-Presents the reason selection UI for choosing between a bonus and correction payment.
-
-```jsx
-import { Payroll } from '@gusto/embedded-react-sdk'
-
-function MyComponent() {
- return {}} />
-}
-```
-
-#### Props
-
-| Name | Type | Description |
-| ------------------ | -------- | ----------------------------------------- |
-| companyId Required | string | The associated company identifier. |
-| onEvent Required | function | See events table for available events. |
-| dictionary | object | Optional translations for component text. |
-
-#### Events
-
-| Event type | Description | Data |
-| ----------------------- | -------------------------------- | ----------------------------------------------------- |
-| OFF_CYCLE_SELECT_REASON | Fired when user selects a reason | { reason: 'bonus' \| 'correction', defaults: object } |
-
-The `defaults` object contains `{ skipDeductions: boolean, withholdingType: 'supplemental' | 'regular' }`.
-
-### Payroll.OffCycleDeductionsSetting
-
-Allows users to choose whether to include or skip regular deductions and contributions for the off-cycle payroll. Taxes are always included regardless of the selection.
-
-```jsx
-import { Payroll } from '@gusto/embedded-react-sdk'
-
-function MyComponent() {
- return {}} />
-}
-```
-
-#### Props
-
-| Name | Type | Description |
-| ------------------------------ | -------- | ------------------------------------------------------- |
-| skipRegularDeductions Required | boolean | Whether regular deductions are currently being skipped. |
-| onEvent Required | function | See events table for available events. |
-| dictionary | object | Optional translations for component text. |
-
-#### Events
-
-| Event type | Description | Data |
-| --------------------------- | --------------------------------------- | ---------------------------------- |
-| OFF_CYCLE_DEDUCTIONS_CHANGE | Fired when deduction preference changes | { skipRegularDeductions: boolean } |
-
-#### Deduction Options
-
-- **Include**: Make all the regular deductions and contributions
-- **Skip**: Block all deductions and contributions, except 401(k). Taxes will be included.
-
-## API Reference
-
-The off-cycle payroll creation uses the [Create an off-cycle payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-payrolls). After creation, the standard payroll execution endpoints apply:
-
-- **Calculate payroll**: `PUT /v1/companies/{company_id}/payrolls/{payroll_id}/calculate`
-- **Submit payroll**: `PUT /v1/companies/{company_id}/payrolls/{payroll_id}/submit`
-- **Cancel payroll**: `PUT /v1/companies/{company_id}/payrolls/{payroll_id}/cancel`
diff --git a/docs/workflows-overview/workflows-overview.md b/docs/workflows-overview/workflows-overview.md
deleted file mode 100644
index 9eee825d8..000000000
--- a/docs/workflows-overview/workflows-overview.md
+++ /dev/null
@@ -1,56 +0,0 @@
----
-title: Workflows Overview
-description: Index of every pre-built workflow in the SDK — onboarding, payroll, contractors, time off, and more — each rendering a multi-step experience as one component.
-order: 4
----
-
-## Introduction to Workflows
-
-Workflows are pre-built UI experiences you can use to quickly and easily incorporate essential payroll functionality into your build, such as onboarding an employee or running payroll.
-
-### Available Workflows
-
-- Company Onboarding
-- Employee Onboarding
-- Employee Self Onboarding
-- Payroll Processing
-- Off-Cycle Payroll (Bonus & Correction)
-- Dismissal Payroll
-- Transition Payroll
-- Contractor Onboarding
-- Contractor Payments
-- Employee Termination
-- Time Off Policy Management
-- Information Requests
-
-### Why should I use a Workflow?
-
-Workflows are incredibly simple to add to your application. A single React component placed in your app can encapsulate an entire complex multi step user experience.
-
-### How to use Workflows
-
-In this example we incorporate the entire employee onboarding flow in our application. This component represents multiple steps including inputting profile details, taxes, and payment info. It can be implemented as follows:
-
-```jsx
-import { EmployeeOnboarding, GustoProvider } from '@gusto/embedded-react-sdk'
-
-function MyApp({ companyId }) {
- return (
-
- {...}} />
-
- )
-}
-```
-
-This example renders a fully functional flow with the following steps:
-
-
-
-As can be seen, using workflow components can allow for implementing complex flows in a simple way.
-
-The following documents in this section will provide more detailed usage examples and implementation guidelines for each flow.