Invite Candidates


You can invite candidates using following API endpoint:

 https://api.hackerearth.com/partner/hackerearth/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 and client_secret should be passed through the body.

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. extra_parameters provides option to override the candidates default options.

candidate_names

Type: Dictionary

Description: This is part of extra_parameters. The dictionary should contain mapping of emails and corresponding names. Please refer to example for more clarification. The name is used in invite email that is sent to the candidate. Also, this name is set to candidate's profile if that candidate was not already registered with HackerEarth.

report_callback_urls

Type: Dictionary

Description: This is part of extra_parameters. 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 is part of extra_parameters. 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_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_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/partner/hackerearth/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.
BADDATA
TESTNOTFOUND Test not found.
TESTNOTPUBLISHED Test not published.
EVENTFINISHED Test has ended.
INVALIDEMAIL Invalid email(s) exist.
LIMITEXCEEDED Client exceeded its request limit. Please contact support@hackerearth.com.
RATELIMITEXCEEDED The rate at which the API requests are made has reached. Please try again after one minute.
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.

title

Type: String

Description: title of the test.

Example:

"title": "he-test"

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,
    "title": "test12345",
    "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 test is not published, then the JSON response returned will look like:

{
    "message": "Request failed",
    "ecode": [
        "TESTNOTPUBLISHED"
    ],
    "emessage": [
        "Test is not published."
    ],
    "mcode": "FAILED"
}

If the test is ended, then the JSON response returned will look like:

{
    "message": "Request failed",
    "ecode": [
        "EVENTFINISHED"
    ],
    "emessage": [
        "Test has ended."
    ],
    "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 limit of API requests (15000 requests) is reached, then the JSON response that is returned is as follows:

{
    "message": "Request failed",
    "ecode": [
        "LIMITEXCEEDED"
    ],
    "emessage": [
        "The limit of the API requests has been reached. Contact support@hackerearth.com."
    ],
    "mcode": "FAILED"
}

If the rate (60 per min) at which API requests are made by a specific user is reached, then the JSON response that is returned is as follows:

{
    "message": "Request failed",
    "ecode": [
        "RATELIMITEXCEEDED"
    ],
    "emessage": [
        "The rate at which the API requests are made has reached. Please try again after one minute."
    ],
    "mcode": "FAILED"
}

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

Notifications
View All Notifications

?