Skip to main content

Onboarding apps


Pull candidates, track their progress, collect and provide candidate-related data
Onboarding applications

The core workflow for onboarding applications evolves around pulling the candidates’ information from the Smartrecruiters customer’s account via the endpoint GET/candidates.

Important notes before you start building

Access to Customer API by 3rd party applications is possible only through a secure OAuth connection- using the customer’s API key is not supported for Marketplace Partner integrations. To learn more about setting up this authentication protocol, see here the OAuth 2.0 specifications in SmartRecruiters:

Custom fields and initial configuration

Most onboarding applications would like to transfer specific candidate information from the ATS. This information can be pulled in the form of custom candidate fields. Despite the fact that these fields can be later configured and changed via our API endpoints, they need to be first created on the customer’s account by the Smartrecruiters ADMIN user. More information about the fields set-up can be found here.

Here is a short instruction, how you can test adding the custom candidate fields in your own sandbox account to understand the process:

For testing purposes, this instruction shows the process of creating one custom field. It is possible to create more to reflect the integration needs by replicating this process.

1. Follow the steps from the instruction and create a custom field (preferred type: single select) along with a value (answer) the recruiters can choose from.

Screen Shot 2021-09-20 at 4.34.56 PM.png

2. Using your sandbox account, create a candidate, roll out the “Application fields” overlap, click “Edit” and select the value of the field you’ve just created.

Screen Shot 2021-09-20 at 4.37.44 PM.png

3. Once you've created the field, you can retrieve the id of the candidate field you have created using the endpoint GET/configuration/candidate-properties. You will use this id in the later step.

Screen Shot 2021-09-20 at 4.54.50 PM.png

4. Use the “id” you have retrieved from the last ste to find ids of the values of the candidate field using the endpoint GET/configuration/candidate-properties/{id}/values.

Screen Shot 2021-09-20 at 5.05.39 PM.png

5. Now you've obtained the ids of both the candidate field you have created and its values, you can use the endpoint GET/candidates  to filter for candidates that are ready to onboard. Use the `propertyId={candidate_property_id}` and `propertyValueId={candidate_property_id_values_id} as filters to retrieve a list of candidates who are ready to be onboard. Additionally, you can use onboardingStatus and Status fields as well to narrow down the search and ensure you’re not getting the same candidates more than once.

If you followed the steps correctly, the API endpoint response body should return only the candidates marked as “Yes” with “Push to onboarding app?” field. 

Workflow- what triggers the integration

The integration workflow should always start with connecting the Smartrecruiters account with your solution’s account. Implement a triggering button on your site (eg. Connect to Smartrecruiters), clicking which triggers the OAuth connection and asks the user to grant your service permission to access the user’s data.

It is strongly advised to implement a periodic check to call the GET/candidates endpoint multiple times an hour/ day/ week (depending on your solution).

Register a webhook to notify you each time a candidate’s data has been changed.

Use either application.onboarding-status.updated. Now, each time there’s been a change in the onboarding status of the application, you’ll be automatically notified, and will be able to trigger your polling mechanism to pull the candidate’s data.

It is advised not to rely on updatedAfter. It is best to use more than one field when searching for the candidates to pull.

However, it is recommended to rely on onboardingStatus and at least one custom candidate field.

onboardingStatus field helps to determine if the candidate is ready to be pulled to your solution. It is crucial for this field to be set from the list of preconfigured fields. 

Using “Create custom field” in this case will make it harder for you to correctly map the data.

Log into your sandbox account, go to Settings/ Admin-> Candidate Fields-> Add Field-> Choose field dropdown menu-> Onboarding Status

Screen Shot 2021-09-20 at 5.40.24 PM.png

Screen Shot 2021-09-20 at 5.40.33 PM.png

This field should be applicable to all the candidates. The recruiter will need to choose from available statuses:

-Ready to Onboard

-Onboarding Successful

-Onboarding Failed

NOTICE: Leaving this field empty will result in the system automatically changing it to Ready to Onboard when the candidate’s status changes to Hired!

Useful Endpoints