Skip to main content

Assessment API V1/ application workflows FAQ


Why are some assessment offers available for 1 credit and the others for $0?

A: This happens when an assessment is rejected. The system does not recognize if the assessment offer was previously set as free, and returns 1 credit as a failsafe mechanism, so the customer is not charged twice in case of an outside contract, paid independently to SR. 1 credit stands for a universal currency, that can be exchanged for 1 assessment order. This mechanism will kick in even if all the offers are $0. Once the 1 credit offer is consumed again, the “$0” is visible again.

Why is there nothing in the “Provider” section of the assessments?

A: Our system displays the partner’s logo in that section. Please have them include that in their Partner Portal account.

How do I attach files as assessment result?

A: You’ll need resultId parameter’s value to push any attachments through the API:

1)GET /assessments followed by GET /assessments/{assessmentOrderId} which will return assessmentOrderId

2)when done, use the assessmentOrderId to mark assessment as complete in 

POST /assessments/{assessmentOrderId}/complete

The response body will return resultId.

This is the endpoint where you need to state the result type:

"resultType": "Document",

"result": "result.pdf" //although in this case “result” will be ignored- you’ll have a chance to name the file in a moment

3)POST /assessments/{assessmentOrderId}/results/{resultId}/attachments

resultId is obtainable only in the response body of 2)- there is no other way to get it

The file will be added to the candidate’s pool of attachments, in addition to the Assessments section “SEE RESULT” hyperlink.

Can I order assessments automatically for each new candidate?

A: Yes, through auto-triggered assessments. The action can be set by the customer [so it needs to be accepted by the client, independently from the vendor], from the user’s interface level.

How to do it: Settings/ Admin-> Hiring process-> create a new custom hiring process with “NEW” step, then create an auto-triggered assessment and assign it to that step. Such assessment will be automatically sent for each new candidate, the moment they are added to the system (or apply for the job). 

NOTICE: Such auto-triggered assessments will be sent by our system only once. If the candidate does not receive an invite to take the assessment (the vendor rejects it), the recruiter needs to re-send the invite manually. 

The requestor of the assessment is the poster of a job the hiring process is associated with.


How do “knockout questions” work?

A: Knockout questions’ purpose is to check if the candidate meets mandatory requirements for the job (example: if a candidate’s applying for the position as a driver has a driver’s license), to “filter” the candidates and reject all those who are not fit for the role. 

How to do it:

The knockout questions are set for each job or multiple jobs from the Settings/ Admin level. Partner/ job board cannot set them, only the customer can. 

Go to Settings/ Admin-> Screening questions-> pick/ create a question and mark it as “Knock-out”.


-If the candidate “fails” the knockout question, they will still be added to the system, but status “rejected” will be automatically added to them. 

-Auto-triggered assessments will not be triggered for the candidates who fail at least 1 knockout question.


When I visit the candidate's profile the Assessments section is empty.

Why can’t I order any assessments?

A: Most likely you have disabled the ability to order assessments. To change that, log in to your Smartrecruiters account, navigate to Settings/ Admin-> Marketplace Control-> mark Display assessments section on the candidate profile checkbox as “on”


What are Inline Assessments?

A: IN DEVELOPMENT, when a partner pushes inline assessment to be activated, do not activate it and contact the partner to inform it is not ready yet.

Can I change the assessment status after it has been marked as “Complete”?

A: No, if you try to change the status from “Completed” to any other you will get the following error message:

 "httpCode": 400,


  "message": "Cannot change state of an assessment which is completed",

  "helpUrl": ""

What requirements does my SR account need to meet to be able to order assessments?

A: It depends on the user’s privileges, not the account. The accounts with only SmartStart subscription can order assessments.

Standard/ basic users cannot order assessments. Only users with higher tier access with enabled Marketplace control access can order assessments. 

What is assessment URL?

A: URL for a Candidate to take an assessment; will be surfaced on a Candidate Portal. For vendor information only. Useful when periodically checking for comments. This value can be completely ignored (removed) when passing a comment. visible to the SR user and on a Candidate Portal (if passed with the request). 


IMPORTANT: when rejecting an assessment order, just remove the “assessmentURL” parameter from the request body, otherwise, if left empty, the call will not go through.


Error when ordering assessment: “Your payment failed”


A: Make sure “Cost” field in the assessment offer (Partner Portal admin) is correctly set. If it’s free- cost should be set as “Flat rate” and 0. If it’s paid- “Percentage” and 70. The platform seems to use “Cost” field to differentiate paid and free offers and interprets them differently.

The source does not exist

A: If your source has been generated by us (Application API/ Customer API) it is not necessary to include its information in the request body to push the candidate. The candidate will be displayed with the correct source anyway, as it is associated with your Marketplace API key in the background.

What is the aspect ratio of a video interview assessment result, displayed directly in Smartrecruiters user account?

A: (iFrame height) The height is configured with a fixed value (500 pixels). Therefore, you have no control on the aspect ratio of the iFrame. When you resize your browser, you can see that our content dynamically scales, but since the height of the iFrame is fixed, it shows extra space at the bottom, or it cuts off the video. 500px value is indeed fixed. The reason behind this solution revolves around bringing the same experience to all of our customers. This value is the same for all of our video assessment vendors, and changing the value would require going over the internal changes with our product management and engineering team.

Can I pass an assessment result without the “result” field?

A: No, the result object has to be added as well, despite the fact that the system will ignore the URL. By stating that the result will be ignored, it means that our server will not check if the url provided there is valid. If not included, the response body will return error:


  "id": "19ec7010-7825-11ea-ae30-668f82ba4fe0",

  "createdAt": 1586191133227,

  "httpCode": 400,

  "code": "BAD_REQUEST",

  "message": "Request is incorrect. Please provide 'result' field."


The result will be passed with the correct body, even if the url is incorrect. Example below:


  "id": "5e8b5bd1c42ad86ebc1195f5",

  "createDate": "2020-04-06T16:41:53.452+0000",

  "title": "CAST  - Demo",

  "description": "CAST  - Demo",

  "passed": true,

  "score": "0%",

  "author": {

    "firstName": "Test",

    "lastName": "Test",

    "email": "",

    "phone": "123456789"


  "result": "https://www.gooogle.coom",

  "resultType": "VIDEO_URL"


In order to pass the assessment result object successfully, the “result” parameter cannot be left empty.

400 unauthorized to access resource error when trying to push an assessment offer via Offers API

A: The error is most likely caused by an incorrect value in “status” parameter. The server will accept INACTIVE, UNDER_REVIEW, or REJECTED. It will not accept “ACTIVE” status.

When pushing the request body with “status” set to “ACTIVE” you’ll receive an error, because your Marketplace API key does not allow you to automatically activate the offers (Partners Team does this part). 

How to send assessments to multiple candidates?

A: The user needs to:

1) create a Hiring Process substep (instructions)

2) assign an auto-triggered assessment to it (instructions).

When an application moves into the hiring step where the auto-triggered assessment has been enabled, the candidate will be automatically sent the assessment in the background. The same automation would apply to a group of candidates when they are bulk moved to a hiring step that includes an auto-triggered assessment.