Onboarding workers to payroll involves collecting a lot of sensitive information in a timely manner. To simplify this process for you and your users, we provide a hosted UI experience for onboarding workers. This guide assumes that you've already onboarded an employer, and have the employer ID.

In the following sections, you'll learn to create and onboard a new worker, and monitor the status of onboarding throughout the process.

Create a Worker

Create a Worker with the Create Worker operation, passing in the employerId, and specifying the first and last names of the worker.

curl --location 'https://api.sandbox.salsa.dev/api/rest/v1/employers/${employerId}/workers' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ${YOUR_API_TOKEN}' \
--data '{
  "firstName": "Olivia",
  "lastName": "Johnson",
}'

{
    "data": {
        "id": "wr_d4779475-da76-45c9-86e1-6f1f75d9ac1e",
        "displayName": "Olivia Johnson",
        "firstName": "Olivia",
        "lastName": "Johnson",
        "classification": "EMPLOYEE"
    }
}

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

Create a Worker Contract

Create a WorkerContract with the Create WorkerContract operation, passing in the employerId, workerId, and specifying the worker's classification and their overtime eligibility.

curl --location 'https://api.sandbox.salsa.dev/api/rest/v1/employers/${employerId}/workers/${workerId}/contracts' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ${YOUR_API_TOKEN}' \
--data '{
  "classification": "EMPLOYEE",
  "overtimeEligible": "true"
}'

{
    "data": {
        "id": "wrctr_ea2079074-da76-48c9-99e1-9w1f7ou9adw2",
         "classification": "EMPLOYEE",
         "overtimeEligible": true,
         "effectiveDate": "2023-01-01",
         "hireDate": null,
         "endDate":null
    }
}

Start onboarding

The next step is to Create a Hosted Worker Onboarding instance for the worker. Similar to the previous steps, you need to pass in the employerId and workerId.

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

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

{
  "data": {
    "id": "hstwronbrd_9dc3dcea-31e5-43ef-b735-ca821ada1e39",
    "status": "INVITED",
    "inviteUrl": "https://components.sandbox.salsa.dev/hosted/worker-onboarding?id=hstwronbrd_9dc3dcea-31e5-43ef-b735-ca821ada1e39&userToken=eyJhbGciO...ajs0Wqw",
    "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 worker. You can share this information through email, text, or directly in your application. We provide a sample email template as a starting point.

By default, the URL will grant the worker access to setup their information 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 a worker starts the onboarding experience, you can monitor their progress with the Hosted Worker 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 HostedWorkerOnboarding API. For example:

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

{
  "data": {
    "id": "hstwronbrd_9dc3dcea-31e5-43ef-b735-ca821ada1e39",
    "status": "COMPLETED",
    "inviteUrl": "https://components.sandbox.salsa.dev/hosted/worker-onboarding?id=hstwronbrd_9dc3dcea-31e5-43ef-b735-ca821ada1e39&userToken=eyJhbGciO...ajs0Wqw",
    "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 Worker.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, a worker will be in one of the following states:

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