Introduction

The Application API enables our customers and partners to integrate the SmartRecruiters application process into their own career site or job board while maintaining full control of the candidate experience. With the Application API, the candidate can submit their application without visiting the SmartRecruiters job ad.

The Application API exposes the full candidate application, allows new applications to be submitted, and exposes the status of applications previously submitted through the API.

Authentication: All endpoints are protected, take a look at Authentication docs to learn more about the subject.

When using OAuth 2.0, scope candidate_applications_manage is required to access Application API.

The following endpoints are exposed:

Endpoint 1 – Get Application Screening Questions

Use this endpoint to fetch the required screening and diversity questions and privacy policies for a specific job:
GET /postings/:uuid/configuration

Endpoint 2 – Create a New Candidate Application

Use this endpoint to create a new application in SmartRecruiters for a specific job:
POST /postings/:uuid/candidates

Endpoint 3 – Get Candidate Application Status

Use this endpoint to get the application status of a specific candidate for a specific job:
GET /postings/:uuid/candidates/:candidateId/status

Mandatory Addition to the Application Process

Along with the screening questions data that we expose via this endpoint, the following must be included as part of the application process:

Separate diversity from non-diversity questions: questions with the complianceType “DIVERSITY” must be presented below all other questions. Note: you should always display the questions in the order they are provided. If you do this, the diversity questions will always be below the others.
Include a “Confidential Diversity Questions” instruction above diversity questions:
Confidential Diversity Questionnaire Any information you choose to provide will not be considered for employment purposes and will be treated as confidential. Your voluntary cooperation will be appreciated.
Recognize Markdown markers present in the API response labels. For example: “Gender, Race and Ethnicity (definitions)”.
It is mandatory to add the privacy policy of the customer. You can retrieve it via the Endpoint 1 explained above: GET /postings/:uuid/configuration. Here is the text you can use:

By checking this box, you will declare that you read and agree to [CompanyName]’s Privacy Policy.

If this is displayed, you might set the candidate’s consent status to “true” acquired. If not, then the status should be set to “false” required.

In the case where there is no privacy policy displayed, please use the following disclaimer:

Please be informed that your application to this job offer will trigger some processing of your personal data by the recruiting company, the data controller. SmartRecruiters, the data processor, has no control over such personal data processing. For more information on these personal data processing, please refer to the recruiting company’s privacy policy.

The consent status should be set to “false” required.

GDPR Regulation imposes an opt-in consent so we suggest you to add a checkbox in front of the above text.

Throttling and limits

To properly support all our users and ensure stability and continuity of our services we use adaptive throttling meaning that the limits of calls per second actively change according to the platform’s load at a given time. From your perspective it means that response times may vary significantly depending on the current state of the platform. Of course we will serve your requests as quickly as possible taking into account that the platform is shared and other users need to get the service too. You have a great influence on how your service behaves in the shared environment. If you follow the tips listed below you will get responses from the system faster and allow other users to use the platform unaffected:

API calls are limited at 8 concurrent requests.
Program your software in the way that it does not make all the calls at one specific point of time, e.g.: 8 am, 9 am, etc. Build in instead some randomness and therefore distribute the calls in time more evenly. Our tooling detects traffic spikes and will not allow to serve too many requests simultaneously so that you can get significantly longer response times or receive errors if you try to execute too many requests at a specific time.
Ensure that timeout of your requests is set to at least 128s. You shall receive response from our API servers within this time (a valid response or an error code). Of course we will do our best to answer your request as quickly as possible.
Make no more simultaneous calls than the current limit allows. Parallel calls above the limit will return an http error code 429.