Blocks

Address

Form for collecting and updating a contractor's mailing address. Renders a business or home address title based on the contractor type.

Example

import { ContractorOnboarding } from '@gusto/embedded-react-sdk'

function MyComponent() {
  return (
    <ContractorOnboarding.Address
      contractorId="contractor-uuid"
      onEvent={() => {}}
    />
  )
}

AddressProps

Props for Address.

Property	Type	Description
contractorId	string	The associated contractor identifier.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event.
className?	string	Optional class applied to the wrapping <section>.
defaultValues?	AddressDefaultValues	Pre-fill values for address fields. Server data takes precedence when the contractor already has an address on file.
dictionary?	Record<"en", DeepPartial<ContractorAddress>>	Overrides for the component's i18n strings.
FallbackComponent?	(props: FallbackProps) => Element	Custom React component rendered when an unhandled error is caught by the component-level error boundary.
LoaderComponent?	LoaderComponentType	Custom loading indicator rendered while this component's async data is fetching. Overrides the indicator configured on GustoProvider for this instance only.

Events

Event	Description	Data
contractor/address/updated	Fired after the address is saved	The updated ContractorAddress entity
contractor/address/done	Fired after a successful save so the parent flow can advance	—

Endpoints

Method	Path
GET	/v1/contractors/:contractorUuid
GET	/v1/contractors/:contractorUuid/address
PUT	/v1/contractors/:contractorUuid/address

---

ContractorList

Lists a company's contractors with controls to add, edit, delete, cancel self-onboarding, and continue onboarding.

ContractorListProps

Props for ContractorList.

Property	Type	Description
companyId	string	The associated company identifier.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
dictionary?	Record<"en", DeepPartial<ContractorContractorList>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.
successMessage?	string	Success message to display in an alert above the list, typically after a create, update, or delete action.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Events

Event	Description	Data
contractor/create	The add-contractor action was triggered.	—
contractor/update	A contractor row's edit action was triggered.	{ contractorId: string }
contractor/deleted	A contractor was successfully deleted.	{ contractorId: string }
contractor/selfOnboarding/cancelled	A contractor's self-onboarding was cancelled, reverting them to admin onboarding.	The updated contractorOnboardingStatus returned by the API.
contractor/onboarding/continue	The continue action was triggered to advance onboarding.	—

Endpoints

Method	Path
GET	/v1/companies/:companyUuid/contractors
DELETE	/v1/contractors/:contractorUuid
PUT	/v1/contractors/:contractorUuid/onboarding_status
DELETE	/v1/contractors/:contractorUuid/rehire
DELETE	/v1/contractors/:contractorUuid/termination

---

ContractorProfile

Form for creating or editing a contractor profile, supporting both individual and business contractor types.

Remarks

In admin mode (the default), renders different field sets depending on the contractor type (individual vs. business) and wage type (hourly vs. fixed), and exposes a self-onboarding toggle that invites the contractor to complete their own setup. When contractorId is provided, the form fetches the existing contractor and updates it on submit; otherwise it creates a new contractor under companyId.

When isAdmin is false, renders the contractor self-onboarding profile instead: it resolves the existing contractor's type and presents the individual (name + SSN) or business (business name + EIN) fields for the contractor to complete.

Parameters

Parameter	Type	Description
props	ContractorProfileProps	See ContractorProfileProps.

Events

Event	Description	Data
contractor/created	A new contractor was created successfully.	The created contractor entity
contractor/updated	An existing contractor was updated successfully.	The updated contractor entity
contractor/profile/done	The contractor profile step finished.	{ contractorId: string, onboardingStatus?: string, selfOnboarding: boolean }

Endpoints

Method	Path
POST	/v1/companies/:companyUuid/contractors
GET	/v1/contractors/:contractorUuid
PUT	/v1/contractors/:contractorUuid

---

ContractorSubmit

Finalizes contractor onboarding by updating the onboarding status, and in the self-onboarding flow can trigger an invitation to the contractor.

ContractorSubmitProps

Props for ContractorSubmit.

Property	Type	Description
contractorId	string	UUID of the contractor being submitted.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
dictionary?	Record<"en", DeepPartial<ContractorSubmit>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.
selfOnboarding?	boolean	When true, adjusts the submission for the self-onboarding flow, surfacing the invite step before the contractor's onboarding status is finalized.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Events

Event	Description	Data
contractor/onboardingStatus/updated	The contractor's onboarding status was successfully updated.	The updated contractorOnboardingStatus returned by the API.
contractor/invite/selfOnboarding	The invite action was triggered for a self-onboarding contractor.	{ contractorId: string }
contractor/submit/done	The submission step finished — fired after a successful status update, after an invite, or when the contractor was already onboarded.	{ message: string }, optionally with onboardingStatus when the contractor was already completed.

Endpoints

Method	Path
GET	/v1/contractors/:contractorUuid
GET	/v1/contractors/:contractorUuid/documents
GET	/v1/contractors/:contractorUuid/onboarding_status
PUT	/v1/contractors/:contractorUuid/onboarding_status
GET	/v1/documents/:documentUuid/pdf

---

DocumentSigner

Contractor onboarding step for reading and signing required contractor documents.

Remarks

Composes the contractor DocumentsList and SignatureForm into a single signing workflow: the document list is shown first, selecting a document routes to its signature form, and signing (or navigating back) returns to the list. The list refetches automatically once a document is signed. The flow completes when every document that requires signing has been signed and the user continues.

DocumentSignerProps

Props for DocumentSigner.

Property	Type	Description
contractorId	string	The associated contractor identifier.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
dictionary?	Record<"en", DeepPartial<ContractorDocumentsList>>	Overrides for the document list copy shown by the signing flow.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from Omit.

Events

Event	Description	Data
contractor/documents/view	Fired when a document's "Sign" action is selected from the document list	{ uuid: string; title?: string }
contractor/documents/sign	Fired after a document is successfully signed	The signed document
contractor/documents/done	Fired when all required documents have been signed and the parent flow can advance	—
cancel	Fired when the user navigates back from the signature form to the document list	—

Components

• DocumentsList
• SignatureForm

---

DocumentsList

Lists a contractor's documents and lets the contractor open each one for signing.

Remarks

Fetches the contractor's documents via useContractorDocumentsList and renders them in a table. The Continue action is disabled until every document the contractor can sign has been signed; a document that isn't signable yet (e.g. a W-9 whose fields haven't been generated) surfaces a warning instead of blocking the flow.

DocumentsListProps

Props for DocumentsList.

Property	Type	Description
contractorId	string	The associated contractor identifier.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
dictionary?	Record<"en", DeepPartial<ContractorDocumentsList>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Events

Event	Description	Data
contractor/documents/view	Fired when a document's "Sign" action is selected	{ uuid?: string; title?: string }
contractor/documents/done	Fired when all required documents are signed and the user continues	—

Endpoints

Method	Path
GET	/v1/contractors/:contractorUuid/documents

---

Landing

Landing page for the contractor self-onboarding flow. Displays a welcome message and the list of onboarding steps the contractor needs to complete.

LandingProps

Props for the Landing component.

Property	Type	Description
contractorId	string	UUID of the contractor entering the self-onboarding flow.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
companyId?	string	Deprecated UUID of the company the contractor belongs to.
dictionary?	Record<"en", DeepPartial<ContractorLanding>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Endpoints

Method	Path
GET	/v1/contractors/:contractorUuid

---

NewHireReport

Collects new hire reporting information for a contractor and persists it to the contractor record.

Asks whether a new hire report should be filed and, when the answer is yes, captures the work state used for filing. Submitting writes both values back to the contractor.

Remarks

Set selfOnboarding to true when this component is rendered as part of the contractor's own self-onboarding flow rather than admin onboarding.

Example

import { ContractorOnboarding } from '@gusto/embedded-react-sdk'

function NewHireReportStep() {
  return (
    <ContractorOnboarding.NewHireReport
      contractorId="contractor-uuid"
      onEvent={() => {}}
    />
  )
}

NewHireReportProps

Props for the NewHireReport component.

Property	Type	Description
contractorId	string	Identifier of the contractor whose new hire report is being collected.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
dictionary?	Record<"en", DeepPartial<ContractorNewHireReport>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.
selfOnboarding?	boolean	When true, adjusts the form for the contractor self-onboarding flow. Defaults to false.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Events

Event	Description	Data
contractor/newHireReport/updated	Fired when the new hire report is saved	The API response object; access the updated contractor at .contractor
contractor/newHireReport/done	Fired after the new hire report step completes	—

Endpoints

Method	Path
GET	/v1/contractors/:contractorUuid
PUT	/v1/contractors/:contractorUuid

---

OnboardingSummary

Confirmation screen shown at the end of the contractor self-onboarding flow. Lets the contractor know their information has been submitted and emits contractor/selfOnboarding/done when they acknowledge it.

OnboardingSummaryProps

Props for OnboardingSummary.

Property	Type	Description
contractorId	string	UUID of the contractor who completed self-onboarding.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
dictionary?	Record<"en", DeepPartial<ContractorOnboardingSummary>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Events

Event	Description	Data
contractor/selfOnboarding/done	Fired when the contractor acknowledges completion and clicks the Done button	{ contractorId: string }

---

PaymentMethod

Manages a contractor's payment method, capturing a bank account for direct deposit or recording check as the payment method.

Displays the current payment type, lets the user switch between direct deposit and check, and collects bank account details (account holder name, routing number, account number, and account type) when direct deposit is selected. Direct deposit creates the bank account (which updates the payment method server-side); check updates the contractor's payment method type directly.

Example

import { ContractorOnboarding } from '@gusto/embedded-react-sdk'

function PaymentMethodStep() {
  return (
    <ContractorOnboarding.PaymentMethod
      contractorId="contractor-uuid"
      onEvent={() => {}}
    />
  )
}

PaymentMethodProps

Props for the PaymentMethod component.

Property	Type	Description
contractorId	string	Identifier of the contractor whose payment method is being managed.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
dictionary?	Record<"en", DeepPartial<ContractorPaymentMethod>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Events

Event	Description	Data
contractor/bankAccount/created	Fired on the direct deposit path after the bank account is created	The created bank account at .contractorBankAccount
contractor/paymentMethod/updated	Fired on the check path after the payment method type is updated	The updated payment method at .contractorPaymentMethod
contractor/paymentMethod/done	Fired when the payment method step completes	—

Endpoints

Method	Path
GET	/v1/contractors/:contractorUuid/bank_accounts
POST	/v1/contractors/:contractorUuid/bank_accounts
GET	/v1/contractors/:contractorUuid/payment_method
PUT	/v1/contractors/:contractorUuid/payment_method

---

SignatureForm

Standalone form for signing an individual contractor document (W-9).

Remarks

Lower-level building block used internally by ContractorDocumentSigner for its signing view. Use this component directly when you need full control over navigation between the document list and the signature form.

Event	Description	Data
contractor/documents/sign	Fired when the document is successfully signed	The signed document
CANCEL	Fired when the user navigates back from the signature form	—

SignatureFormProps

Props for SignatureForm.

Property	Type	Description
contractorId	string	The associated contractor identifier.
documentUuid	string	The UUID of the contractor document to sign.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
dictionary?	Record<"en", DeepPartial<ContractorSignatureForm>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.

Inherits children, className, defaultValues, FallbackComponent, LoaderComponent from BaseComponentInterface.

Endpoints

Method	Path
GET	/v1/documents/:documentUuid
GET	/v1/documents/:documentUuid/pdf
PUT	/v1/documents/:documentUuid/sign

---

Utility types

AddressDefaultValues

AddressDefaultValues = RequireAtLeastOne<ContractorAddressFormData>

Pre-fill values accepted by Address. At least one of street1, street2, city, state, or zip must be provided.

---

ContractorProfileAdminProps

Props for ContractorProfile in admin mode.

Remarks

Renders the admin create/edit form. When contractorId is omitted, the form creates a new contractor under companyId. When provided, it fetches and updates the existing contractor.

Extends

• BaseComponentInterface<"Contractor.Profile">

Properties

Property	Type	Description
companyId	string	UUID of the company the contractor belongs to.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
children?	ReactNode	Optional child content rendered inside the component's layout.
className?	string	CSS class name applied to the component's root element.
contractorId?	string	UUID of an existing contractor to edit. When omitted, the form creates a new contractor.
defaultValues?	Partial<ContractorDetailsFormData>	Initial values for the contractor profile form fields.
dictionary?	Record<"en", DeepPartial<ContractorProfile>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.
FallbackComponent?	(props: FallbackProps) => Element	Custom React component rendered in place of the component when an unhandled error is caught by the component-level error boundary. Receives error and resetErrorBoundary as props. Defaults to the SDK's built-in InternalError fallback.
isAdmin?	true	When true (the default), renders the admin create/edit form.
LoaderComponent?	LoaderComponentType	Custom loading indicator rendered while the component's async data is fetching. Overrides the indicator configured on GustoProvider for this component instance only.

---

ContractorProfileFormData

Renames and re-exports ContractorDetailsFormData

---

ContractorProfileProps

ContractorProfileProps = ContractorProfileAdminProps | ContractorProfileSelfOnboardingProps

Props for ContractorProfile.

Remarks

Discriminated by isAdmin. See ContractorProfileAdminProps and ContractorProfileSelfOnboardingProps for the specific prop shapes.

---

ContractorProfileSelfOnboardingProps

Props for ContractorProfile in self-onboarding mode.

Remarks

Renders the contractor self-onboarding profile. The contractor must already exist so its type (individual vs. business) can be resolved to determine which fields to display.

Extends

• BaseComponentInterface<"Contractor.Profile">

Properties

Property	Type	Description
companyId	string	UUID of the company the contractor belongs to.
contractorId	string	UUID of the existing contractor completing self-onboarding. Required in self-onboarding mode.
isAdmin	false	When false, renders the contractor self-onboarding profile.
onEvent	OnEventType<EventType, unknown>	Callback invoked each time the component emits an event — user interactions, successful API responses, step transitions, or errors. Receives the event type constant and an optional payload whose shape varies by event. See the Event Handling guide and each component's event table for the full list of emitted events.
children?	ReactNode	Optional child content rendered inside the component's layout.
className?	string	CSS class name applied to the component's root element.
defaultValues?	Partial<ContractorDetailsFormData>	Initial values for the contractor profile form fields.
dictionary?	Record<"en", DeepPartial<ContractorProfile>>	Overrides for the component's i18n strings. Supply a partial object whose keys match the component's resource namespace — any omitted keys fall back to SDK defaults. See the Translation guide for details.
FallbackComponent?	(props: FallbackProps) => Element	Custom React component rendered in place of the component when an unhandled error is caught by the component-level error boundary. Receives error and resetErrorBoundary as props. Defaults to the SDK's built-in InternalError fallback.
LoaderComponent?	LoaderComponentType	Custom loading indicator rendered while the component's async data is fetching. Overrides the indicator configured on GustoProvider for this component instance only.

---

OnboardingFlowDefaultValues

OnboardingFlowDefaultValues = RequireAtLeastOne<{ address?: AddressDefaultValues; profile?: Partial<ContractorDetailsFormData>; }>

Default pre-fill values for the contractor onboarding flow. At least one of profile or address must be provided.