Onboard an employer
Learn how to onboard an employer onto Salsa with our hosted UI experience.
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
Updated 4 months ago