Quickstart

To support an optimal candidate onboarding experience with minimal development, we will prioritize data transfer between systems on both ends of the process. To provide an optimal recruiter experience, we will leverage the Onboarded engine to reduce the amount of manual selection that a recruiter needs to do for every candidate.

The experience will be driven completely through the Onboarded API.

Setting The Scene

ACME Inc. is ready has decided to hire Ryan Jackson to be their first employee for their widget shop. Ryan will be a cashier. Ryan Jackson will need to complete their I-9 and W-4 to start working. Let's get Ryan onboarded!

Create the Employer

Because this is ACME Inc.'s first employee, we need to create an employer object in Onboarded to create the employee object under. You can create the employer at any time. An employer can exist without any employees.

To create the employer we'll use the below payload with POST /v1/employers.

{
  "name": "ACME Inc.",
  "ein": "123456789",
  "phone": "123-456-7890",
  "entity_structure": "corporation",
  "address": {
    "street": "123 Widget St",
    "secondary": "Suite 123",
    "city": "New York",
    "state": "NY",
    "zip": "10000",
    "country": "USA"
  }
}

The only required fields to create an employer are the name, ein, and address. You may also use the API to populate custom_attributes which must be created through the dashboard ahead of time.

You should get back a response that looks like this:

{
  "id": "er_HVf2NFdLDi1Bin3LgUmZA", // The er_ will be the same, but the string will differ
  "name": "ACME Inc.",
  "ein": "123456789",
  "dba_name": null,
  "phone": "123-456-7890",
  "employee_count": null,
  "entity_structure": "corporation",
  "naics_code": null,
  "address": {
    "street": "123 Widget St",
    "secondary": "Suite 123",
    "city": "New York",
    "state": "NY",
    "zip": "10003",
    "country": "USA"
  },
  "custom_attributes": {},
  "created_at": "2023-11-07T05:31:56Z", // yours will be different
  "updated_at": "2023-11-07T05:31:56Z" // yours will be different
}

Save the id, you'll need it for later!

Create the Employee

Now we need to create the employee. Similar to employers the employee object doesn't need an employer, client, or job to exist on the account to be created. The employee is associated with the account, not with any other entity until creating the placement, which is next up.

To create the employee we'll use the below payloadd with POST /v1/employees

{
  "first_name": "Ryan",
  "middle_name": "Micah",
  "last_name": "Jackson",
  "email": "ryan@example.com", // nothing will be sent to the email provided here
  "phone": "1234567890",
  "date_of_birth": "1990-01-01",
  "social_security_number": "123-45-6789",
  "has_middle_name": true,
  "address": {
    "street": "123 Random St",
    "secondary": "",
    "city": "New York",
    "state": "NY",
    "zip": "10000",
    "country": "USA"
  }
}

The only required fields when creating an employee are the first_name, last_name, and address (except for secondary). Similar to the employer object, you may use the API to populate custom_attributes which must be created through the dashboard ahead of time.

You should get a response that looks like this:

{
    "id": "ee_oYhyCTBJJABaQUr5FNir8", // yours will be different, except for the ee_
    "first_name": "Ryan",
    "middle_name": "Micah",
    "last_name": "Jackson",
    "email": "ryan@example.com",
    "phone": "1234567890",
    "date_of_birth": "1990-01-01",
    "social_security_number": "123-45-6789",
    "has_middle_name": true,
    "address": {
        "street": "123 Random St",
        "secondary": null,
        "city": "New York",
        "state": "NY",
        "zip": "10000",
        "country": "USA"
    },
    "custom_attributes": {},
    "created_at": "2024-05-14T21:46:48.861Z", // yours will be different
    "updated_at": "2024-05-14T21:46:48.861Z" //  yours will be different
}

Save the id, you'll need it for the next step!

Create a Placement

Now that we have created our employee and employer objects, we can place Ryan with his new employer. Placements is how Onboarded knows what employer, job, and client an employee should be associated with. Further, creating a placement triggers the policy engine. When the policy engine is triggered, it looks at all the associated entity data and determines what tasks are applicable for this placement.

To create the placement we'll use the below payloadd with POST /v1/Placements

{
  "employee_id": " ", // use the ID from the "Create an Employee" step earlier
  "employer_id": " " // use the ID from the "Create an Employer" step earlier
  "create_tasks": true
}

The only required field when creating a placement is the employee_id, all other fields are optional. However, it's not often that you'll have a task that is relevant across the entire account. Therefore, it's always recommended that you associate an employee with at least an employer object.

You should get a response that looks like this:

{
    "id": "pla_f99Q8OHWoV3b1oFFrupHF", // this will be differnet, other than the pla_
    "employee_id": "ee_", // this should be the ID you use for employee_id
    "employer_id": "er_", // this should be the ID you use for employer_id
    "created_at": "2024-05-14T23:27:37.480Z", // this will be different 
    "suggested_tasks": [
        {
            "form_id": "form_01hvsp3rp6f0paqn0wq2cd61dh"
        }
    ]
}

You may get back more forms depending on how many were created during your account set up. form_id can be used to manually create tasks but when create_tasks is set to true they will automatically be created instead.

Create an Onboarding URL

Once the placement has been created, we can generate an onboarding URL for the employee! The onboarding URL is our hosted-experience whereby the employee goes through each task field-by-field. This experience may include an e-signature step, which will capture the users's IP address, signed timestamp, and signature.

To create the onboarding URL we'll use the following GET request /v1/employees/:id/onboarding, where :id is the ID from the employee object we created earlier.

This will generate an employee-facing onboarding URL. You can also use query parameters to create an employer-facing onboarding URL which will contain tasks assigned to the employer. This is particularly relevant for forms like the I-9 which require an employer to review the uploaded documents to establish work authorization.

You should get a response that looks like this:

{
    "url": "https://app.onboarded.com/onboarding/auth?token=<token>" // the token will be provided in the response
}

🎉 Congratulations, you've created an onboarding URL! This URL can be sent to Ryan and will automatically collect all of the data they provide. Any tasks that generate a PDF, such as the W-4, are also accessible once completed.