With Salsa, it only takes a few steps to onboard a new business (which we call an employer) using our hosted UI experience. In the following sections, you'll learn to create and onboard a new employer, and monitor the status of onboarding throughout the process.

Create an Employer

The first step is to create an Employer with the Create Employer operation, specifying the business name and the country where it's located.

curl --location 'https://api.sandbox.salsa.dev/api/rest/v1/employers' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ${YOUR_API_TOKEN}' \
--data '{
  "businessName": "Shack 22",
  "country": "USA"
}'

{
    "data": {
        "id": "er_a5127cc7-5297-4c62-a91c-ae1c2d75997e",
        "businessName": "Shack 22",
        "country": "USA",
        "externalId": "null",
        "legalName": "null"
    }
}

Save the Employer ID (id), you'll need it to complete the next step.

Start onboarding

The next step is to create a hosted workflow that allows Employers to get setup up within your organization. This is done with the Create Hosted Employer Onboarding operation, passing in the id you obtained after creating an employer.

The Hosted Employer Onboarding object provisions access, provides a URL to onboard the employer, and provides current onboarding status.

curl --location --request POST 'https://api.sandbox.salsa.dev/api/rest/v1/employers/${employerId}/onboardings' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ${YOUR_API_TOKEN}'

{
  "data": {
    "id": "hsteronbrd_1ce965f0-862f-4951-8fac-5dec59c61def",
    "status": "INVITED",
    "inviteUrl": "https://components.sandbox.salsa.dev/hosted/employer-onboarding?id=hsteronbrd_1ce965f0-862f-4951-8fac-5dec59c61def&userToken=eyJhbGciO...zEcE5S-_M",
    "inviteExpirationTime": "2023-04-18T23:29:50.804",
    "completedAt": null
  }
}

Save the inviteUrl, you'll need it to complete the next step.

Share the onboarding URL

Share the inviteUrl that you received in the previous step with the employer. You can share this information through email, text, or directly in your application.

By default, the URL is valid for 30 days. After visiting the URL, the user can complete the onboarding workflow.

🚧

Be careful when sharing the invite URL

The URL for the Hosted Worker Onboarding UI is provisioned to provide access to the experience without requiring any additional authentication. As such, ensure that you are sharing the URL with the intended recipient only.

Monitor onboarding status

After an employer starts the onboarding experience, you can monitor their progress with the Hosted Employer Onboarding object. You can retrieve data from the object by fetching it directly with a GET request, or by listening for updates using Webhooks.

Fetch

To fetch the data directly, use the retrieve the HostedEmployerOnboarding API. For example:

curl --location --request GET 'https://api.sandbox.salsa.dev/api/rest/v1/employers/${employerId}/onboardings/${onboardingId}' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ${YOUR_API_TOKEN}'

{
  "data": {
    "id": "hsteronbrd_1ce965f0-862f-4951-8fac-5dec59c61def",
    "status": "COMPLETED",
    "inviteUrl": "https://components.sandbox.salsa.dev/hosted/employer-onboarding?id=hsteronbrd_1ce965f0-862f-4951-8fac-5dec59c61def&userToken=eyJhbGciO...zEcE5S-_M",
    "inviteExpirationTime": "2023-04-18T23:29:50.804",
    "completedAt": "2023-04-15T00:07:59.189924613"
  }
}

Webhooks

To receive events using Webhooks, you must configure a Webhook endpoint. For more information about configuring a Webhook endpoint, see Consuming webhooks.

Once setup to receive Webhooks events, when the onboarding status changes, we will send you a Employer.onboardingStatus event that contains the IDs of the Worker and Onboarding. The event also includes information about to the status change. You can read the full Webhook event schema for this event type in the Callback section of the Create WebhookEndpoint reference.

Onboarding Status Messages

During the onboarding process, an employer will be in one of the following states:

• INVITED: An onboarding link has been generated to invite the employer to self-onboard through our Hosted Onboarding experience.
• STARTED: The employer has started onboarding.
• INVALIDATED: A new onboarding has been started or the existing link has expired.
• COMPLETED: The employer has finished onboarding.

📘

Check out the event Employer.PayWorkersReadiness.statusChanged which track the full employer onboarding life-cycle. See Employer Readiness for more details