Skip to main content

Use of Customer API with Assessment API


This article describes how to obtain more candidate’s data in addition to these returned in the Assessment API, with the use of Customer API. Useful when you want to obtain additional data of the candidate the assessment has been ordered for. NOTICE: OAuth authentication needed.

The Assessment API refers in this article has entered the sunset period and will be deprecated in the future. Consider using the new Assessment API (2021) if you are potential partner who is considering to build an assessment integration with SmartRecruiters.

This article is based on the following information:

  • UUID of a candidate from Assessment API corresponds to candidate ID used in Customer API.
  • UUID of a job from Assessment API corresponds to job ID used in Customer API.

Screen Shot 2022-01-25 at 4.50.44 PM.png

1. Obtain your Marketplace API key by creating your Partner Portal account

2. Create the offer and contact Partners Team to activate it

3. Use your sandbox account to create the candidate and order the assessment for them

4. Log in to your sandbox account, go to the candidate’s profile, pick your assessment from the list and click “Select”, followed by “Continue”. When it’s done, click “Send”

5. Use the Marketplace API key from the Partner Portal to fetch the assessment order: GET /assessments

NOTICE: remember to use your Marketplace API key to authorize.

6. Find your assessment order in the feed, take the uuid of the candidate and use it here GET/candidates/{id} (OAuth needed to authorize)

The same workflow can be applied to the job, which details you wish to obtain. 

Following from step 5:

1. Obtain the uuid of a job posting from GET /assessments

2. Go to GET/jobs/{jobId} and use the uuid to obtain the information about the job

The results still must be passed to the system using POST /assessments/{assessmentOrderId}/results

Obtaining and passing additional information from Candidate Fields

Such data can be obtained directly from the candidate’s profile, using the Candidate API. Custom candidate fields cannot be created via API endpoints- make sure you’ve notified the customer to create the fields.

  • Method 1

WARNING: This method works only if you are sure that the candidate is assigned to one job. The GET/properties will return the candidate fields (properties) in context of one job - the one with the most recent activity (called primaryAssignment in the API). 

If the candidate is assigned to more than one job, you’ll need to check the properties for each application, as different applications might have different candidate fields selected for them. 

Candidate property is not a value fixed for the candidate in context of all jobs, and may vary. Valid only if you’re pulling fields, if you’re going to push them, pull all of the available at the beginning of the integration:

Example: SSN data (Social Security Number)

1) The user creates the Candidate Field and names it accordingly.

2) Follow the standardized process steps to obtain the assessment order, followed by obtaining the candidate’s data (up to step 4).

3) Use GET/candidates/{id} to obtain the candidate properties - they will be returned in the form of a url you need to make an additional call to with an appropriate authorization token (for partners: OAuth authentication bearer).



"properties": {

      "method": "GET",

      "url": ""

Proper URL to call:

Example response:


    "content": [


            "id": "394d999a-198c-474e-b711-8f6d411367dd",

            "label": "Social Security Number",

            "type": "TEXT",

            "value": "567-948",

            "actions": {

                "configuration": {

                    "url": "",

                    "method": "GET"




  • Method 2

This method is recommended to obtain the candidate properties, chosen by the recruiter in the context of a specific job. This action needs to be repeated for each job a candidate is linked to separately.

1. Obtain the candidate ID of a candidate and all the jobs they’ve applied for using followed by

2. Take the candidateID and jobID from the response body of the endpoint above and use them here

3. Use the IDs to obtain the values of the candidate fields. The response body will return the name of the candidate field (label) and the value that has been chosen for it.

4. Go to point 2. And repeat for every job the candidate has applied for. TIP: first 2 positions will be displayed as primaryAssignment and secondaryAssignment. Each next job will be displayed as just the id number.

Pushing additional data to Smartrecruiters

If you gather additional candidate’s information during the assessment process, you can push it to Smartrecruiters. Eg. the customer would like to obtain SSN (Social Security Number) of a candidate using your solution and be able to see that data inside their Smartrecruiters account in certain candidate’s profile (recommended when passing data in a comment to the assessment result is insufficient).

1) Follow the workflow up to step 5 to get to know which candidate to update: GET/candidates/{id}

At this point you’ll be able to:

2) Use POST/candidates to overwrite the candidate’s data. In order to do that, use the same first and last name of the candidate, the same email address and source that has been assigned to that candidate.

3) PATCH/candidates/{id} to update the basic candidate information

4) Update a certain pre-configured field, selected among the others. From responses of GET/candidates/{id}, obtain properties assigned to this candidate (custom fields), the value of the object should be URLs you can use to retrieve to the candidate's custom fields

5) Make calls to the obtained URL with API key/ OAuth token to retrieve the candidate’s custom fields (properties). The correct call should return the properties as in the example below:


    "content": [


         "id": "e2144fde-fc56-4e0e-beae-5006ccfe8d0f",

            "label": "Last Name",

            "type": "TEXT",

            "value": "123",

            "actions": {

                "configuration": {

                    "url": "",

                    "method": "GET"





            "id": "a292dd29-e996-4250-9c4e-4dcdfb90bb26",

            "label": "HRDiversify",

            "type": "BOOLEAN",

            "value": true,

            "actions": {

                "configuration": {

                    "url": "",

                    "method": "GET"




6) Use POST/configuration/candidate-properties/{id}/values to change the values. 

Values are available only for SINGLE_SELECT type of candidate property. You need to use already pre-configured values. Candidate fields need to be created manually by the user first.

Sorting candidates based on assessment results

It is not possible to determine the next steps for the candidate based on the assessment results, as there is no option to filter the candidates by their assessment results. This fact is determined by the possibility to add a free text as a result (score, scale, performance report, etc.) which renders the results unscalable. If you introduce a sorting mechanism on your side, it is possible to merge it with our solutions.

Sorting by candidate status
  1. Follow the workflow up to step 5.

  2. Filter the assessment results and determine which candidate passes to the next recruitment step.

  3. Use PUT/candidates/{id}/jobs/{jobId}/status to change the candidate’s status within the context of a job they’ve applied for. List of available statuses: LEAD, NEW, IN_REVIEW, INTERVIEW, OFFERED, HIRED, REJECTED, WITHDRAWN, TRANSFERRED

You’ll need id and jobId parameters which can be obtained via GET/candidates/{id}

If the candidate did not pass the assessment or did not meet the expectations in any way, change the status to WITHDRAWN or REJECTED. Using these statuses requires stating a reason for rejection. Use the pre-configured reasons, obtainable here:

You can create custom candidate statuses as a Hiring Process substep, devided by the candidate’s performance during the assessment.

Sorting by application fields (custom candidate fields)  

From Smartrecruiters UI perspective, it is also possible to filter the candidates by the application fields. Go to the People tab and select the desired field from the column to the left.

Screenshot 2020-09-10 at 12.58.22.png