Invite Candidates


You can invite candidates using following API endpoint:

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

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

Candidates can be invited only for published tests.

client_id, client_secret, test_id and email_list are the required parameters for making request to this API endpoint. send_email is an optional parameter which is explained below. candidate_ids, report_callback_urls are also supported. Since these are optional parameters one should send these inside extra_parameters.

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

emails

Type: List

Description: emails is a list/array which contains emails.

Example: ["foo@bar.com", "bob@alice.com", "hacker@hackerearth.com"]

send_email (Optional)

Type: Boolean value (True/False)

Description: If this field is not provided, by default send_email will be True and candidates will receive invite emails. If this value is False candidates won't receive invite emails.

extra_parameters (Optional)

Type: Dictionary

Description: Dictionary of optional parameters such as candidate_ids, candidate_names, report_callback_urls, redirect_urls.

candidate_ids

Type: Dictionary

Description: This dictionary should contain mapping of emails and corresponding candidate_id. Please refer to example for more clarification.

candidate_names

Type: Dictionary

Description: The dictionary should contain mapping of emails and corresponding names. Please refer to example for more clarification.

report_callback_urls

Type: Dictionary

Description: This dictionary should contain mapping of emails and corresponding report_callback_urls in which the candidate_report to be posted 1 hour after candidate completes the test. Please refer to the example for more clarification.

redirect_urls

Type: Dictionary

Description: This dictionary should contain mapping of emails and corresponding redirect_urls in which the candidate will be redirected after candidate completes the test. Please refer to the example for more clarification.

Sample request using python

#!/usr/bin/env python

import json
import requests

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

payload = {
    'client_id': CLIENT_ID,
    'client_secret': CLIENT_SECRET,
    'test_id': TEST_ID,
    'emails': ['foo@bar.com', 'alice@bob.com', 'yet@another.email'],
    'send_email': False,
    'extra_parameters': {
        'candidate_ids': {
            'foo@bar.com': 1234522,
            'alice@bob.com': 'alpha123',
            'yet@another.email': 'letters'
            },
        'candidate_names': {
            'foo@bar.com': 'Foo Bar',
            'alice@bob.com': 'Alice Bob'
            },
        'redirect_urls': {
            'foo@bar.com': 'http://www.redirecturl.com/',
            'alice@bob.com': 'http://www.redirecturl2.com/'
            },
        'report_callback_urls': {
            'foo@bar.com': 'http://www.callbackurl.com/',
            'alice@bob.com': 'http://www.callbackurl2.com/'
            }
        }
    }
r = requests.post("https://api.hackerearth.com/recruiter/v1/tests/invite/", data=json.dumps(payload))
print r.json()

Using cURL

curl --data '{
"client_id": "7ece23094df344eb6f29d60ee415fcdca3885b71af70.api.hackerearth.com",
"client_secret": "639110ecf3aeb333498c948e3442376253b208c6",
"test_id": 57,
"emails": ["foo@bar.com", "alice@bob.com", "yet@another.email"],
"send_email": false,
"extra_parameters": {
    "candidate_ids": {
        "foo@bar.com": 1234522,
        "alice@bob.com": "alpha123",
        "yet@another.email": "letters"
        },
    "candidate_names": {
        "foo@bar.com": "Foo Bar",
        "alice@bob.com": "Alice Bob"
        },
    "report_callback_urls": {
        "foo@bar.com": "http://www.callbackurl.com/",
        "alice@bob.com": "http://www.callbackurl2.com/"
        }
    }
}' https://api.hackerearth.com/recruiter/v1/tests/invite/


Response

Response returned will be in JSON format.

Sample response

{
  "candidates_already_completed": [],
  "emessage": [],
  "invites_sent_count": 2,
  "mcode": "SUCCESS",
  "invalid_emails": [],
  "message": "Request successful",
  "extra_parameters": {
      "invite_urls": {
          "test@test.com": "https://www.hackerearth.com/your-test-name-here/?login=6fc3af861erb3f5f85baf1bb031ad07b",
          "foo@bar.com": "https://www.hackerearth.com/your-test-name-here/?login=a313381c02458298196219bba2d9e04e"
       }
    },
  "candidates_already_invited": [],
  "ecode": []
}

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.
TESTNOTFOUND Test not found.
INVALIDEMAIL Invalid email(s) exist.
LIMITEXCEEDED Client exceeded its request limit. Please contact support@hackerearth.com.
BUYCREDITS You do not have sufficient credits to invite candidates, please purchase more credits.
PREVIOUSLYINVITED Candidate(s) previously invited.
TESTTAKEN Candidate(s) have taken the test
ACCESSERROR You are not authorized to access this feature. Please contact support@hackerearth.com.

invalid_emails

Type: List

Description: An array of invalid emails

Example:

"invalid_emails": [
    "itsnotanemail",
    "another@@wrongemail",
    "wrong@again"
]

candidates_already_completed

Type: List

Description: This list contains emails of candidates who have taken the test from the emails provided. The candidates are not invited again.

Example:

"candidates_already_completed": [
    "particip@ted.com"
]

candidates_already_invited

Type: List

Description: This parameter contains list of previously invited candidate emails from the emails provided. The candidates are not invited again.

Example:

"candidates_already_invited": [
    "iamalre@dyinvited.com"
]

invites_sent_count

Type: Integer

Description: Count of number of candidates invited successfully for the test

Example:

"invites_sent_count": 2

Sample response for emails with invalid emails:

{
    "invalid_emails": [
        "notanemailaddress"
    ],
    "candidates_already_completed": [],
    "candidates_already_invited": [],
    "message": "Request successful",
    "invites_sent_count": 2,
    "extra_parameters": {
      "invite_urls": {
          "test@test.com": "https://www.hackerearth.com/your-test-name-here/?login=6fc3af861erb3f5f85baf1bb031ad07b",
          "foo@bar.com": "https://www.hackerearth.com/your-test-name-here/?login=a313381c02458298196219bba2d9e04e",
       }
    },
    "ecode": [
        "INVALIDEMAIL"
    ],
    "emessage": [
        "Invalid email(s) exist."
    ],
    "mcode": "SUCCESS"
}


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: 'emails'"
    ],
    "mcode": "FAILED"
}

or

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

If wrong test_id is provided, 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, then 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, then 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"
}

and if any other issue occurred do reach us out at sudip@hackerearth.com

Notifications
View All Notifications

?