Skip to main content
SmartRecruiters

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.

 

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.



 

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

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”

 

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

 

5. 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 4:

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.

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

 

EXAMPLE:

 

"properties": {

      "method": "GET",

      "url": "https://api.smartrecruiters.com/cand...2a0/properties"

Proper URL to call: https://api.smartrecruiters.com/cand...ken=1234567890

Example response:

{

    "content": [

        {

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

            "label": "Social Security Number",

            "type": "TEXT",

            "value": "567-948",

            "actions": {

                "configuration": {

                    "url": "https://api.smartrecruiters.com/conf...1-8f6d411367dd",

                    "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 

https://dev.smartrecruiters.com/customer-api/live-docs/candidate-api/#/candidates/candidates.all followed by https://dev.smartrecruiters.com/customer-api/live-docs/candidate-api/#/candidates/candidates.get



2. Take the candidateID and jobID from the response body of the endpoint above and use them here https://dev.smartrecruiters.com/customer-api/live-docs/candidate-api/#/candidates/candidates.getApplication

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.

Example below: candidate field/ property name: ”Test of order 2” 

Chosen value: “Test 1”


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. Example: 

-GET/candidates/{id}

 

-obtain properties assigned to this candidate (custom fields)

-use the obtained URL with API key/ OAuth token to obtain 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": "https://api.smartrecruiters.com/conf...e-5006ccfe8d0f",

                    "method": "GET"

                }

            }

        },

        {

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

            "label": "HRDiversify",

            "type": "BOOLEAN",

            "value": true,

            "actions": {

                "configuration": {

                    "url": "https://api.smartrecruiters.com/conf...e-4dcdfb90bb26",

                    "method": "GET"

                }

            }

        }

 

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

NOTE: 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

NOTE: you’ll need id and jobId parameters- both obtainable in GET/candidates/{id}

 

Changing the candidate’s status reflects directly moving the candidate to another step of the hiring process from the user’s level.

 

 

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:

GET/configuration/withdrawal-reasons

GET/configuration/rejection-reasons 

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