Gather the information necessary to onboard an employer onto payroll by collecting it directly from them with this experience.
Employer onboarding experience
This is a employer facing experience that provides an employer user with a walkthrough of all of the steps that are required to be completed by them in order to get them setup and ready to run payroll.
Embedded usage
Element name: employer-onboarding
Refer to the guide on how to embed an Element with Salsa.js for more detailed instructions.
Options
| Name | Type | Description |
|---|---|---|
userToken | String | Required. A User Token with EMPLOYER_ADMIN or EMPLOYER_ONBOARDING access role for the specified Employer. |
employerId | String | Required. The id of the Employer. |
includeSteps | String[] | An array of the names of the steps which are to be included in the list of onboarding steps. If omitted, all applicable steps will be included by default. Available steps are: add-company-bank, company-signatory, pay-schedule, payroll-history-declaration, tax-info, verify-bank, work-location, and worker-setup. |
Refer to the reference on creating elements for the additional options that are available to all elements.
Workforce-based step visibility
The onboarding steps displayed adapt based on the employer's workforce type:
| Workforce Type | Visible Signatory Step | Notes |
|---|---|---|
| Employees or Both | company-signatory | Full two-step flow: add signatory → sign documents |
| Contractors only | signatory-catch-all | Simplified single-step signatory form (replaces company-signatory and pay-schedule) |
When an employer has a contractors-only workforce, the company-signatory and pay-schedule steps are automatically hidden and replaced with the signatory-catch-all step, which collects the signatory information without requiring document signing.
🚨 Note: For contractors-only employers, the signatory-catch-all step is always required and cannot be hidden via the includeSteps option. The company-signatory step can be excluded for other workforce types, but the catch-all step will always appear and cannot be hidden by configuration.
Alternatively, if the platform supports admonition blocks, you could use:
:::warning
For contractors-only employers, the signatory-catch-all step is always required and cannot be hidden via the includeSteps option. The company-signatory step can be excluded for other workforce types, but the catch-all step will always appear when applicable.
:::
Example
salsa.elements.create('employer-onboarding', {
userToken: 'eyJhbGciO...ajs0Wqw',
employerId: 'er_e8343fc7-9d63-4cc5-81ed-c573fc666d37'
});Events
Refer to the documentation on Element events for more information about events and instructions on how to consume them.
complete event
complete eventThe complete event is triggered when the user completes the onboarding workflow.
Event object properties
| Name | Type | Description |
|---|---|---|
elementType | String | 'employer-onboarding'` |
employerId | String | The id of the Employer. |
Hosted usage
URL path: employer-onboarding
Refer to the guide on how to onboard employers with Salsa UI for more detailed instructions on how you can invite employers to use this hosted UI experience.
Options
| Name | Type | Description |
|---|---|---|
userToken | String | Required. A User Token with EMPLOYER_ONBOARDING access role for the specified Employer. |
id | String | Required. The id of the HostedEmployerOnboarding instance associated with a particular Worker. |
Example
https://components.salsa.dev/hosted/employer-onboarding?id=hsteronbrd_t56022031-54d25-20ce-m790-f0bb4078273&userToken=eyJhbGciO...ajs0Wqw