NAV Navbar
shell ruby
  • Introduction
  • Authentication
  • Tests (Assessments)
  • Candidates
  • Pagination
  • Errors
  • Introduction

    Screenom-B2B allows our partners to integrate Screenom’s assessment tool using REST APIs and white labelled web interface.

    Once you have a Screenom account setup with API access, you should be able to get Screenom integrated with your applications such as Applicant Tracking System, Job boards or any tools / products in the pre-hiring, post-hiring tools that require talent assessment capability.

    Current set of APIs are built for Screenom's Assessment product. Sign up to Screenom as evaluator / employer to get a feel of the Assessment workflow.

    Some API Endpoints

    # Tests
    GET: https://screenom.com/api/v/1/b/tests
    
    # Assigned Candidates
    GET: https://screenom.com/api/v/1/b/tests/<TEST ID>/candidates
    
    # Candidate Test Report
    GET: https://screenom.com/api/v/1/b/tests/<TEST ID>/candidates/<CANDIDATE-ID>
    
    api_tests="https://screenom.com/api/v/1/b/tests"
    
    api_test_candidates="https://screenom.com/api/v/1/b/tests/<TEST ID>/candidates"
    
    api_candidate_test_report="https://screenom.com/api/v/1/b/tests/<TEST ID>/candidates/<CANDIDATE-ID>"
    

    Authentication

    Authenticate your account access when using the API by using the client id and token in the request. Manage your account API client id and token on Screenom under the API settings page.

    If you have a Screenom evaluator / employer account and you don't see API settings, reach out to support@screenom.com to get the API access enabled.

    All the API calls are stateless and will be on HTTPS. Calls made over regular HTTP will fail.

    Example request that has Authentication headers

    require 'httparty'
    
    headers = {
        "Screenom-Client-Id" => "MYCLIENTID",    
        "Authorization" => "Token token=MYTOKEN",
        "Content-type" => "application/json",
        "Accept" => "application/json"
    } 
    
    api = "https://screenom.com/api/v/1/b/tests"
    
    response = HTTParty.get(api, { headers: headers })
    
    puts response.body, response.code, response.message, response.headers.inspect
    
    # With shell, you can just pass the correct header with each request
    curl "https://screenom.com/api/v/1/b/tests" \
      -H "Screenom-Client-Id: <MYCLIENTID>" \
      -H "Authorization: Token token=<MYTOKEN>" \
      -H "Content-type: application/json"
    

    Make sure to replace <MYCLIENTID> and <MYTOKEN> with the API client id and token configured for your Screenom account.

    Request Headers

    API client id and token should be included as headers in all the API requests. Below are the two headers,

    Name Value
    Authorization "Token token=MYTOKEN"
    Screenom-Client-Id "MYCLIENTID"

    You must replace MYCLIENTID and MYTOKEN with the actual values for your Screenom account.

    Login to Screenom and find your API client id and token under API settings page. You may also request to generate new token.

    Tests (Assessments)

    Test is an assessment definition or test definition. A test has a title, a few skills, test questions of different categories, coding & multiple choice question types etc.

    Tests API supports listing, paginating and viewing test definitions that are defined in your Screenom account.

    List Tests

    Use this API to paginate through to get all the tests.

    curl "http://screenom.com/api/v/1/b/tests" \
      -H "Screenom-Client-Id: <MYCLIENTID>" \
      -H "Authorization: Token token=<MYTOKEN>" \
      -H "Content-type: application/json" \
      -H "Accept: application/json" 
    
    require 'httparty'
    
    headers = {
        "Screenom-Client-Id" => "MYCLIENTID",    
        "Authorization" => "Token token=MYTOKEN",
        "Content-type" => "application/json",
        "Accept" => "application/json"
    } 
    api = "https://screenom.com/api/v/1/b/tests"
    response = HTTParty.get(api, { headers: headers })
    
    puts response.body, response.code, response.message, response.headers.inspect
    

    Example response:

    {
        "tests":
        [
            {
                "id":525,
                "name":"Php Programmer",
                "link":"https://screenom.com/api/v/1/b/tests/525",
                "created_at":"2017-10-26T09:51:23.000Z",
                "updated_at":"2017-10-28T10:23:46.000Z"
            },
            {
                "id":526,
                "name":"Php Multiple",
                "link":"https://screenom.com/api/v/1/b/tests/526",
                "created_at":"2017-10-27T00:17:37.000Z",
                "updated_at":"2017-10-27T00:17:37.000Z"
            }
        ]
    }
    

    Request

    Query Parameters

    Parameter Default Description
    page 1 page number, default is 1
    per_page 10 page size. default is 10. Pagination links go in the response header 'Link'

    Response

    Field Type Description
    tests[] Array List of test definitions
    tests[].id Number Test identifier
    tests[].name String Title or name of the test
    link String URL of the test detail api
    created_at String Date/time when the test was created
    updated_at String Date/time when the test was updated

    Test Detail

    URL of this API can be read from the link field of individual test items in Test Listing API response.

    curl "https://screenom.com/api/v/1/b/tests/526" \
      -H "Screenom-Client-Id: <MYCLIENTID>" \
      -H "Authorization: Token token=<MYTOKEN>" \
      -H "Content-type: application/json" \
      -H "Accept: application/json" 
    
    require 'httparty'
    
    headers = {
        "Screenom-Client-Id" => "MYCLIENTID",    
        "Authorization" => "Token token=MYTOKEN",
        "Content-type" => "application/json",
        "Accept" => "application/json"
    }  
    api = "https://screenom.com/api/v/1/b/tests/526"
    response = HTTParty.get(api, { headers: headers })
    
    puts response.body, response.code, response.message, response.headers.inspect
    

    Example response:

    {
        "test": {
            "id": 526,
            "name": "PHP Developer - II",
            "questions_selection": "Random",
            "questions_type": "Multiple Choice Questions",
            "coding": false,
            "mc": true,
            "mc_skills": [
                "PHP"
            ],
            "mc_questions_count": 15,
            "test_length_mins": 15,
            "test_proctored": false,
            "candidates": {
                "invited_pending": 2,
                "invited_complete": 2,
                "archived": 0,
                "total": 5,
                "link": "https://screenom.com/api/v/1/b/tests/526/candidates"
            },
            "created_at": "2017-10-27T00:17:37.000Z",
            "updated_at": "2017-10-27T00:17:37.000Z"
        }
    }
    

    Use this API to the details of a given test and that'll include the basic test details, type of test questions, skills assigned, count of candidates invited/completed and a link to fetch all the assigned candidates and their test statuses.

    Request

    Response

    Field Type Description
    id Number Test identifier
    name String Test name / title
    question_selection String Values can either be 'Random' or 'Custom'.
    questions_type String Value depends on the type of the questions included in the test
    coding Boolean true if the test includes coding questions and false if only MCQ.
    mc Boolean true if the test includes MCQ and false if only coding questions.
    mc_skills Array List of skills for MCQ. Based on the list of skills, questions will be distributed to multiple skills.
    coding_skills Array List of programming languages for the candidate to pick from.
    mc_questions_count Number number of MCQ assigned to every candidate that take this test
    coding_questions_count Number number coding quesitons assigned to every candidate that take this test
    test_length_mins Number Test lenth in minutes. Max time that a candidate can take to complete the test.
    test_proctored Boolean If the test was configured to have proctoring enabled, value will be true. false otherwise.
    candidates.invited_pending Number number of candidates that are invited but not taken the test
    candidates.invited_complete Number number of candidates that have taken the test
    candidates.archived Number number of candidates invited/completed but have been archived
    candidates.total Number total of all the candidates - invited/incomplete/complete/archived
    candidates.link String API link to get list of candidates assigned to this test
    created_at String Date/time when the test was created
    updated_at String Date/time when the test was updated

    Candidates

    Candidates API supports the following,

    Invite Candidate

    Screenom will assign a given candidate to the test and send an email invitation with a test link. Use this API to assign and invite a candidate to take the test.

    If you need to email the test invitation to the candidate from your system or application, you can have Screenom suppress email test invitation.

    curl "https://screenom.com/api/v/1/b/tests/208/candidates" \
      -H "Screenom-Client-Id: <MYCLIENTID>" \
      -H "Authorization: Token token=<MYTOKEN>" \
      -H "Content-type: application/json" \
      -H "Accept: application/json" \
      -X POST \
      -d '{
          "candidate": {
              "email": "candidate-email@gmaill1.comm",
              "first_name": "some first name",
              "last_name": "some last name",
              "invite": true
          }
      }'
    
    require 'httparty'
    
    headers = {
        "Screenom-Client-Id" => "MYCLIENTID",    
        "Authorization" => "Token token=MYTOKEN",
        "Content-type" => "application/json",
        "Accept" => "application/json"
    }
    
    req_body = {
        candidate: {
            email: "candidate-email@gmaill1.comm",
            first_name: "some first name",
            last_name: "some last name"
        }
    }
    
    api = "https://screenom.com/api/v/1/b/tests/208/candidates"
    response = HTTParty.post(api, { headers: headers, query: req_body } )
    
    puts response.body, response.code, response.message, response.headers.inspect
    

    Example JSON response:

    {
        "candidate": {
            "id": 403,
            "message": "assigned to test",
            "link": "https://screenom.com/api/v/1/b/tests/208/candidates/424"
        }
    }
    

    Request

    Field Type Description
    candidate.email String valid email address of the candidate to be assgined to the test
    candidate.first_name String candidate's first name
    candidate.last_name String candidate's last name
    candidate.invite Boolean Default true. If set to false, Screenom will not email the test invitation to candidate

    Response

    Field Type Description
    candidate.id Number Some identifier of assignment
    candidate.message String Confirmation or error message. Response code 200 or 201 is a success.
    candidate.link String API link to get the candidate's test invitation, detail and report.

    Candidate Listing

    Use this API to list and paginate through all the candidates that have been assigned to a test.

    curl "https://screenom.com/api/v/1/b/tests/526/candidates" \
      -H "Screenom-Client-Id: <MYCLIENTID>" \
      -H "Authorization: Token token=<MYTOKEN>" \
      -H "Content-type: application/json" \
      -H "Accept: application/json" 
    
    require 'httparty'
    
    headers = {
        "Screenom-Client-Id" => "MYCLIENTID",    
        "Authorization" => "Token token=MYTOKEN",
        "Content-type" => "application/json",
        "Accept" => "application/json"
    } 
    api = "https://screenom.com/api/v/1/b/tests/526/candidates"
    response = HTTParty.get(api, { headers: headers })
    
    puts response.body, response.code, response.message, response.headers.inspect
    

    Example JSON response:

    {
        "candidates": [
            {
                "id": 2394,
                "first_name": "Chandra",
                "last_name": "S",
                "email": "candidate.one1@gmailll.comm",
                "candidate_test": {
                    "status": "New",
                    "archived": false,
                    "assigned_at": "2017-11-02T20:57:18.000Z"
                }
            },
            {
                "id": 2396,
                "first_name": "Chandra",
                "last_name": "Chandra",
                "email": "candidate.2396@mailinatorr.com",
                "candidate_test": {
                    "status": "Emailed",
                    "test_invitation": {
                        "emailed": true,
                        "emailed_at": "2017-11-02T21:05:19.000Z",
                        "expires_at": "2017-11-12T21:05:19.000Z",
                        "expired": false,
                        "test_web_link": "https://screenom.com/c/tests/xxx...yyy"
                    },
                    "archived": false,
                    "assigned_at": "2017-11-02T21:05:19.000Z"
                }
            },        
            {
                "id": 2391,
                "first_name": "Nick",
                "last_name": "S",
                "email": "candidate.2347@mailinatorr.com",
                "candidate_test": {
                    "status": "Completed",
                    "link": "https://screenom.com/api/v/1/b/tests/526/candidates/2391.json",
                    "terminated": false,
                    "archived": false,
                    "assigned_at": "2017-10-28T22:46:40.000Z",
                    "started_at": "2017-10-28T22:47:36.000Z",
                    "completed_at": "2017-10-28T23:00:41.000Z"
                }
            }
        ],
    }
    

    Request

    Response

    Field Type Description
    candidates[] Array List of candidates assigned to test
    candidates[].id Number Id of assigned candidate. If the candidate was assigned to another test, the id will be different.
    candidates[].first_name String First name of the candidate that is supplied in the Assign Candidate API or if the candidate entered a different name before taking the test.
    candidates[].last_name String Last name
    candidates[].email String Email address. This will be same as what is supplied when the candidate was assigned to the test
    candidates[] .candidate_test Object Available if the candidate initiated the test session
    candidates[] .candidate_test.status String Status of candidate's test session. Possible values are - Completed, Emailed, Started, New
    candidates[] .candidate_test.link String API to get more details of the candidate's test & report
    candidates[] .candidate_test.terminated String If the test session went over max time or if the test was abondaned and eventually expired.
    candidates[] .candidate_test.archived String If the candidate was / test report was archived by the admin or the owner who created the test.
    candidates[] .candidate_test.assigned_at String Timestamp when the candidate was assigned to the test
    candidates[] .candidate_test.started_at String Timestamp when the candidate started the test session
    candidates[] .candidate_test.completed_at String Timestamp when the candidate completed the test session. This will also be the time when the test session was either expired or terminated.
    candidates[] .test_invitation Object Test invitation.
    candidates[] .test_invitation.emailed Boolean True if Screenom emailed the test invitation. False otherwise.
    candidates[] .test_invitation.emailed_at String Timestamp when the email invitation with a test link was sent to the candidate
    candidates[] .test_invitation.expires_at String Timestamp when the test link will expire. This is generally 72 hours from the time invitation email goes out.
    candidates[] .test_invitation.expired Boolean True if the test link is expired. False otherwise.
    candidates[] .test_invitation.test_web_link String Web url for the test. If you chose Screenom not email the test invitation, you'll need to send this to the candidate.

    Detail & Report

    URL of this API can be read from the link field under candidate_test section of individual candidate items in Candidate Listing API response.

    curl "https://screenom.com/api/v/1/b/tests/526/candidates/2375" \
      -H "Screenom-Client-Id: <MYCLIENTID>" \
      -H "Authorization: Token token=<MYTOKEN>" \
      -H "Content-type: application/json" \
      -H "Accept: application/json" 
    
    require 'httparty'
    
    headers = {
        "Screenom-Client-Id" => "MYCLIENTID",    
        "Authorization" => "Token token=MYTOKEN",
        "Content-type" => "application/json",
        "Accept" => "application/json"
    } 
    api = "https://screenom.com/api/v/1/b/tests/526/candidates/2375"
    response = HTTParty.get(api, { headers: headers })
    
    puts response.body, response.code, response.message, response.headers.inspect
    

    Example JSON response:

    {
        "candidate": {
            "first_name": "Nick",
            "last_name": "S",
            "email": "candidate.2346@mailinator.com",
            "candidate_test": {
            "status": "Completed",
            "report_web_link": "https://screenom.com/r/candidate_tests/2375/test_reports",
            "summary": {
                "assigned_at": "2017-10-27T00:17:49.000Z",
                "started_at": "2017-10-27T01:12:21.000Z",
                "completed_at": "2017-10-27T01:21:25.000Z",
                "archived": false,
                "mc_questions_count": 15,
                "test_length_mins": 15,
                "skills": [
                    "PHP"
                ]
            },
            "score": {
                "percentage": "80.95",
                "total_points": 525,
                "scored_points": 425
            },
            "skill_scores": 
                [
                    {
                    "skill_name": "PHP",
                    "total_count": 15,
                    "coding": false,
                    "answered_count": 15,
                    "correct_answer_count": 12,
                    "total_points": 525,
                    "scored_points": 425,
                    "percentage": "80.95"
                    }
                ]
            }
        }
    }
    

    Use this API to get the details of a candidate & test report. API Responds with candidate's test session summary and total & skill-wise score in points and also percentage.

    Request

    Response

    Field Type Description
    candidate.first_name String First name
    candidate.last_name String Last name
    candidate.email String Email address
    candidate .candidate_test Object Available if the candidate initiated the test session
    candidate .candidate_test .status String Status of candidate's test session. Possible values are - Completed, Emailed, Started, New
    candidate .candidate_test .report_web_link String URL to the Screenom portal where you can view the report. One additional information on that report is question & answer details, plus the proctoring / code-play view.
    candidate .candidate_test .summary Object Summary of the test session
    candidate .candidate_test .summary.test_invitation Object Test invitation details.
    candidate .candidate_test .summary.test_invitation.emailed Boolean True if Screenom emailed the test invitation. False otherwise.
    candidate .candidate_test .summary.test_invitation .emailed_at String Timestamp when the email invitation with a test link was sent to the candidate
    candidate .candidate_test .summary.test_invitation .expires_at String Timestamp when the test link will expire. This is generally 72 hours from the time invitation email goes out.
    candidate .candidate_test .summary.test_invitation .expired Boolean True if the test link is expired. False otherwise.
    candidate .candidate_test .summary.test_invitation.test_web_link String Web url for the test. If you chose Screenom not email the test invitation, you'll need to send this to the candidate.
    candidate .candidate_test .summary.terminated String If the test session went over max time or if the test was abondaned and eventually expired.
    candidate .candidate_test .summary.termination_status String If terminated, the reason
    candidate .candidate_test .summary.archived Boolean If the candidate was / test report was archived by the admin or the owner who created the test.
    candidate .candidate_test. summary.assigned_at String Timestamp when the candidate was assigned to the test
    candidate .candidate_test .summary.started_at String Timestamp when the candidate started the test session
    candidate .candidate_test .summary.completed_at String Timestamp when the candidate completed the test session. This will also be the time when the test session was either expired or terminated.
    candidate .candidate_test .summary.mc_questions_count Number Count of multiple choice questions in the test session.
    candidate .candidate_test .summary .coding_questions_count Number Count of coding questions in the test session.
    candidate .candidate_test .summary.test_length_mins String Test length in minutes
    candidate .candidate_test .summary.skills[] String List of skills - MC question skills as well as the coding language the candidate has chosen.
    candidate .candidate_test .score Object Overal test score details
    candidate .candidate_test .score.percentage Decimal Overall score in percentange
    candidate .candidate_test .score.total_points Number Total questions' points (weightage)
    candidate .candidate_test .score.scored_points Number Scored points
    candidate .candidate_test .skill_scores Array List of skills and scores
    candidate .candidate_test .skill_scores[].skill_name String Skill name
    candidate .candidate_test .skill_scores[].coding Boolean Boolean if questions included for this skill were coding type
    candidate .candidate_test .skill_scores[].total_count Number Number of questions for the skill
    candidate .candidate_test .skill_scores[].answered_count Number Number of questions answered
    candidate .candidate_test .skill_scores[].correct_answer_count Number Number of questions answered and are correct
    candidate .candidate_test .skill_scores[].total_points Number Total points for the questions under this skill
    candidate .candidate_test .skill_scores[].scored_points Number Scored points
    candidate .candidate_test .skill_scores[].percentage Number Percentage score for the skill

    Pagination

    Requests that return multiple items will be paginated to 10 items by default. You can specify further pages with the page parameter. For some resources, you can also set a custom page size up to 100 with the per_page parameter.

    # First page with default page size
    curl -v "https://screenom.com/api/v/1/b/tests/208/candidates" \ 
      -H "Screenom-Client-Id: <MYCLIENTID>" \
      -H "Authorization: Token token=<MYTOKEN>" \
      -H "Content-type: application/json" \
      -H "Accept: application/json" 
    
    # Second page with page size as 20 instead of default 10
    curl -v "https://screenom.com/api/v/1/b/tests/208/candidates?page=2&per_page=20" \ 
      -H "Screenom-Client-Id: <MYCLIENTID>" \
      -H "Authorization: Token token=<MYTOKEN>" \
      -H "Content-type: application/json" \
      -H "Accept: application/json" 
    
    require 'httparty'
    
    headers = {
        "Screenom-Client-Id" => "MYCLIENTID",    
        "Authorization" => "Token token=MYTOKEN",
        "Content-type" => "application/json",
        "Accept" => "application/json"
    } 
    
    # First page with default page size
    api_page_1 = "https://screenom.com/api/v/1/b/tests/208/candidates"
    response = HTTParty.get(api, { headers: headers } )
    puts "Total count", response.headers["x-total-count"].to_i
    puts "Links", (response.headers["Link"] || "").split(", ")
    
    # Second page with page size as 20 instead of default 10
    api_page_2 = "https://screenom.com/api/v/1/b/tests/208/candidates?page=2&per_page=20"
    # response = HTTParty.get(api, { headers: headers, query: { page: 2, per_page: 20 } } )
    response = HTTParty.get(api, { headers: headers } )
    puts "Total count", response.headers["x-total-count"].to_i
    puts "Links", (response.headers["Link"] || "").split(", ")
    

    The Link header includes pagination information:

    Link: <https://screenom.com/api/v/1/b/tests?page=2&per_page=20>; rel="next", <https://screenom.com/api/v/1/b/tests?page=10&per_page=20>; rel="last", <https://screenom.com/api/v/1/b/tests?page=1&per_page=20>; rel="first"

    This Link response header contains comma separate pagination link relations. Possible rel values are,

    Name Description
    next Immediate next page of results
    next Last page of results
    first First page of results
    prev Immediate previous page of results

    Total count

    Read the response header X-TOTAL-COUNT value for the total result size. Use this along with other pagination links to define pagination links based on your UI and back-end needs.

    Errors

    Screenom uses standard HTTP response codes to indicate the success or failure of an API request.

    curl "https://screenom.com/api/v/1/b/tests/208/candidates" \
       -H "Screenom-Client-Id: <MYCLIENTID>" \
      -H "Authorization: Token token=<MYTOKEN>" \
      -H "Content-type: application/json" \
      -H "Accept: application/json" \
      -X POST \
      -d '{
          "candidate": {
              "email": "SOME BAD OR DUPLICATE EMAIL ADDRESS"
          }
      }'
    
    require 'httparty'
    
    headers = {
        "Screenom-Client-Id" => "MYCLIENTID",    
        "Authorization" => "Token token=MYTOKEN",
        "Content-type" => "application/json",
        "Accept" => "application/json"
    }
    
    req_body = {
        candidate: {
            email: "SOME BAD OR DUPLICATE EMAIL ADDRESS"
        }
    }
    
    api = "https://screenom.com/api/v/1/b/tests/208/candidates"
    response = HTTParty.post(api, { headers: headers, query: req_body } )
    
    puts response.body, response.code, response.message, response.headers.inspect
    

    Response for bad invalid email address:

    {
        "errors": {
            "candidate": {
                "email": [
                    "is invalid"
                ]
            }
        }
    }
    

    Response if candidate is already assigned to test:

    {
        "errors": {
            "candidate": {
                "email": [
                    "already assigned to this test"
                ]
            }
        }
    }
    

    Response if the test id (in the URL) is invalid

    {
        "errors": {
            "message": "test not found"
        }
    }
    

    Response Code

    In general, below is how the responde codes indicate,

    Error Code Meaning
    200 Success
    201 Success
    400 Bad request
    401 Unauthorized. Check the authentication headers
    403 Forbidden
    404 Not found. Bad URI path or API
    422 Unprocessable entity - due to validation errors
    500 Internal server error or exception
    503 Service unavailable - temporary outage due to maintenance

    Response Body

    Response body structure of Invite Candidate API on errors,

    Field Type Description
    errors Object Includes error message or validation error of requested resource type
    errors.message String Error message
    errors.candidate Object this depends on the type of api. If it was an error on assign candidate request due to some validation errors, errors.candidate will have field specific validation errors
    errors.candidate.email[] Array of String values For individual fields of resource (candidate in this case), list validation errors. Email field specific errors in this case.