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.



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.


3. 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.


4. Go to Configuration API and use this endpoint GET/configuration/candidate-properties to determine the value of the field you’ve created (each custom candidate field has it’s own “id” generated by the system the moment it’s created - you will need it later on).

5. Use the “id” from the endpoint above in GET/configuration/candidate-properties/{id}/values to determine the fields and values that reflect them.


6. Knowing the value of the field you’ll be looking for, go to GET/candidates  and use the propertyId (“Push to onboarding app?”) and propertyValieId (“Yes”) ids as filters during the pull for candidates. Use onboardingStatus and Status fields as well to narrow down the search and ensure you’re not getting the same candidates more than once or the candidates mistakenly marked as “Yes”.


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


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