Candidate Report


You can get a candidate report for a particular test using following API endpoint:

 https://api.hackerearth.com/recruiter/v1/tests/candidate_report/

Authentication

The client authentication is done using your unique client_id and client_secret.

You can refer to your Dashboard settings, for client_id and client_secret under API details.

client_id

Type: String

Description: client_id is a 67 character random key that serves as an identification for a particular client and must be provided when communicating with the API as a parameter to the API endpoint.

Example: d8a20ae8e475209er4b1faa72ede88a174423cc2029c.api.hackerearth.com

client_secret

Type: String

Description: client_secret is a 40 character random key that serves as an identification for a particular client and must be provided when communicating with the API as a parameter to the API endpoint.

Example: 2b0ff29f4f8751487540604cdab5611e6135f41c


Making requests

Candidate report is accessible only for published test.

client_id, client_secret, test_id and email are the required parameters for making request to this API endpoint.

All the requests to the API must be made using POST request method.

client_id and client_secret are explained above.

test_id

Type: Integer

Description: test_id is an unique integer for your test.
Refer advance settings section under test settings for test_id.

Example: 5841

email

Type: String

Description: The candidate email id for the report to be generated.

Sample request using python

#!/usr/bin/env python

import json
import requests

CLIENT_ID = "d8a20ae8e475209e0eb1faa72ede88a174423cc2029c.api.hackerearth.com"
CLIENT_SECRET = "2b0ff29f4f8751487450604cdab5611e6135f41c"
TEST_ID = 53
EMAIL = "hacker@hackerearth.com"

payload = {
    'client_id': CLIENT_ID,
    'client_secret': CLIENT_SECRET,
    'test_id': TEST_ID,
    'email': EMAIL
}
r = requests.post("https://api.hackerearth.com/recruiter/v1/tests/candidate_report/", data=json.dumps(payload))
print r.json()

Using cURL

curl --data '{"client_id":"d8a20ae8e475209e0eb1faa72ede88a174423cc2029c.api.hackerearth.com","client_secret":"2b0ff29f4f8751487450604cdab5611e6135f41c","test_id":20, "email":"hacker@hackerearth.com"}' https://api.hackerearth.com/recruiter/v1/tests/candidate_report/


Response

Response returned will be in JSON format.

Sample response

{
    "emessage": [],
    "mcode": "SUCCESS",
    "test_info": {
        "total_questions": 2,
        "test_id": 20,
        "max_score": 104,
        "title": "Your test title"
    },
    "candidate_report": {
        "phone_number": "9876543210",
        "status": "active",
        "start_datetime": "02-05-2015 12:31:11 +0000",
        "finish_datetime": "02-05-2015 13:31:11 +0000",
        "full_report_url": "https://www.hackerearth.com/recruiter/your-test-name/candidates-report/hash1/hash2/"
        "time_taken": "1:00:00",
        "name": "Foo Bar",
        "institute": "Foo Bar Institute",
        "score": 0,
        "questions_attempted": 1,
        "graduation_year": "2013",
        "percentage": 0,
        "email": "hacker@hackerearth.com",
        "candidate_id": ""
   },
   "ecode": [],
   "message": "Request successful"
}

mcode

Type : String

Description: Message code abbreviated as mcode.

message

Type: String

Description: A message for user regarding the success of request.

message and mcode are related to each other according to the following table:

mcode message
SUCCESS Request successful
FAILED Request failed

ecode

Type: List

Description: Error codes abbreviated as ecode.

emessage

Type: List

Description: A message explaining the error occurred during request processing.

emessage and ecode are related to each other according to the following table:

ecode emessage
AUTHFAILED Authentication Failed
ARGMISSING Request argument missing
MUSTBEINT Test ID must be integer
INVALIDEMAIL Invalid email(s) exist.
TESTNOTFOUND Test not found
CANDIDATENOTFOUND Candidate not found
NOREPORT No report exist.
LIMITEXCEEDED Client exceeded its request limit. Please contact support@hackerearth.com.
ACCESSERROR You are not authorized to access this feature. Please contact support@hackerearth.com.

candidate_report

Type: Dictionary (JSON)

Description: This JSON will contain all the details about the candidate i.e. name, phone_number, status, start_datetime, finish_datetime, time_taken, institute, full_report_url, score, questions_attempted, graduation_year, questions_attempted, percentage, email, candidate_id.

test_info

Type: Dictionary (JSON)

Description: This JSON will contain all the details about test i.e total_questions, test_id, title, max_score.


Errors (Mishandled API responses)

If you have provided wrong client_id or client_secret, the JSON response returned will look like:

{
    "message": "Request failed",
    "ecode": [
         "AUTHFAILED"
    ],
    "emessage": [
        "Authentication Failed"
    ],
    "mcode": "FAILED"
}

If mandatory POST arguments are not provided, the JSON response returned will look like:

{
    "message": "Request failed",
    "ecode": [
        "ARGMISSING"
    ],
    "emessage": [
        "Request argument missing: 'test_id'"
    ],
    "mcode": "FAILED"
}

If the type of test_id is not integer, then the JSON response returned will look like:

{
    "message": "Request failed",
    "ecode": [
        "MUSTBEINT"
    ],
    "emessage": [
        "Test ID must be integer"
    ],
    "mcode": "FAILED"
}

If wrong test_id is provided or the test has already been deleted, then the JSON response returned will look like:

{
    "message": "Request failed",
    "ecode": [
        "TESTNOTFOUND"
    ],
    "emessage": [
        "Test not found"
    ],
    "mcode": "FAILED"
}

If user is not authorized to access the test, the JSON response returned will look like:

{
    "message": "Request failed",
    "ecode": [
        "ACCESSERROR"
    ],
    "emessage": [
        "You are not authorized to access this feature. Please contact support@hackerearth.com."
    ],
    "mcode": "FAILED"
}

If the API request limit has exceeded, the JSON response returned will look like:

{
    "message": "Request failed",
    "ecode": [
        "LIMITEXCEEDED"
    ],
    "emessage": [
        "Client exceeded its request limit. Please contact support@hackerearth.com."
    ],
    "mcode": "FAILED"
}

If no candidates have taken the test, then the JSON response returned will look like:

{
    "message": "Request failed",
    "ecode": [
        "NOREPORT"
    ],
    "emessage": [
        "No report exist."
    ],
    "mcode": "FAILED"
}

If invalid email id provided, then the JSON response returned will be like:

{
    "message": "Request failed",
    "ecode": [
        "INVALIDEMAIL"
    ],
    "emessage": [
        "Invalid email(s) exist"
    ],
    "mcode": "FAILED"
}

If the candidate with the provided email id was not invited for the test or has not taken the test, then the JSON response returned will be like:

{
    "message": "Request failed",
    "ecode": [
        "CANDIDATENOTFOUND"
    ],
    "emessage": [
        "Candidate not found"
    ],
    "mcode": "FAILED"
}

If any other issue occurred do reach us out at api@hackerearth.com

Notifications
View All Notifications

?