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.

Deciding whether to mount the element

On a returning employer's visit, check whether they still need onboarding before rendering this experience. Either:

• Query Salsa. If onboardingSummary.completedAt is set on the employer, onboarding is done.
• Track it yourself. Keep a lifecycle state on your own employer record (for example onboarding → active), advanced by the Employer.onboardingStatus webhook described below. Most integrations prefer this: it avoids a call to Salsa on every page load, and gives you somewhere to represent states Salsa doesn't know about, such as cancelled or suspended, so your app can render those views too.

query EmployerOnboardingState($employerId: ID!) {
  employer(id: $employerId) {
    onboardingSummary {
      status
      completedAt
    }
  }
}

📘

Completing onboarding is not the same as being ready to run payroll

Onboarding completion means the employer finished the flow. It doesn't mean they can run payroll yet, and it doesn't mean their workers are set up. See Employer readiness and Worker payment readiness.

Embedded usage

Element name: employer-onboarding

Refer to the guide on how to embed an Element with Salsa.js for more detailed instructions.

Options

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:

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

The complete event is triggered when the user completes the onboarding workflow.

Event object properties

After completion

When onboarding completes, stop rendering this element and render the employer-dashboard element in its place. Two separate signals tell you it's done, and they reach different parts of your integration.

In the browser: the complete event above. The element emits it into your frontend. It does not reach your server. Use it to swap the component immediately:

const onboarding = salsa.elements.create('employer-onboarding', {
  userToken: 'eyJhbGciO...ajs0Wqw',
  employerId: 'er_e8343fc7-9d63-4cc5-81ed-c573fc666d37'
});

onboarding.on('complete', ({ employerId }) => {
  // stop rendering employer-onboarding, render employer-dashboard
});

On your server: the Employer.onboardingStatus webhook, sent with status: "COMPLETED". Salsa sends it as an HTTP request to an endpoint you register. It does not reach your frontend. Use it to update the employer's state in your own database. See Consuming webhooks to set up an endpoint, and the Employer.onboardingStatus event reference for the payload.

📘

Embedded vs. hosted

The Employer.onboardingStatus webhook and the complete element event are sent for embedded onboardings. For hosted onboardings, completion is tracked through the HostedEmployerOnboarding resource: its status moves through INVITED, STARTED and COMPLETED (or INVALIDATED if the link expires or a new onboarding replaces it), and completedAt is set once the employer finishes. Read it with Get HostedEmployerOnboarding, or use onboardingSummary.completedAt on the employer as described in Deciding whether to mount the element.

🚧

Don't use Employer.PayWorkersReadiness.statusChanged to detect completion

Readiness tracks the employer's setup data, which can become complete while the user is still inside the flow adding workers. It may therefore fire before the user finishes onboarding. Use it for Employer readiness, not for swapping the UI.

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

Example

https://components.salsa.dev/hosted/employer-onboarding?id=hsteronbrd_t56022031-54d25-20ce-m790-f0bb4078273&userToken=eyJhbGciO...ajs0Wqw