Log in
You can invite candidates using the following API endpoint:
https://api.hackerearth.com/partner/hackerearth/invite/
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.
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
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
Candidates can be invited only for published tests.
client_id, client_secret, test_id, and email_list are the required parameters for making requests to this API endpoint. send_email is an optional parameter which is explained below. report_callback_urls is also supported. Since these are optional parameters one should send these inside extra_parameters.
All the requests to the API must be made using the POST request method.
client_id and client_secret are explained above.
Type: Integer
Description: test_id is a unique integer for your test. Refer to this article for a better understanding. In this article, Recruiter API ID is the test_id.
Example: 5841
Type: List
Description: emails is a list/array which contains emails.
Example: ["foo@bar.com", "bob@alice.com", "hacker@hackerearth.com"]
Note: The minimum limit of the emails array is 1 and the maximum limit is 150.
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.
Type: Integer
Description: auto_expiry_days is an integer field. You can specify only 1, 3, 5, 7, 14, and 28 days in this field. If you fill in any other value, you will see an error on the screen. If this field is filled with a specific number of days, then an invite will expire either after those many days or after the default invite expiry limit is set for your organization. If a default invite expiry limit is not set for your organization, the invite will never expire. For more information, please refer to the example.
Example: 28
Type: Dictionary
Description: Dictionary of optional parameters such as candidate_names, report_callback_urls, redirect_urls. extra_parameters provides an option to override the candidate's default options.
Type: Dictionary
Description: This is part of extra_parameters. The dictionary should contain a mapping of emails and corresponding names. Please refer to the example for more clarification. The name is used in the invite email that is sent to the candidate. Also, this name is set to the candidate's profile if that candidate was not already registered with HackerEarth.
Note: candidate_id is also available as the parameter if the test has the Candidate ID settings turned on under Education details in Candidate Settings.
Type: Dictionary
Description: This is part of extra_parameters. This dictionary should contain a mapping of emails and corresponding report_callback_urls in which the candidate_report is to be posted 1 hour after the candidate completes the test. The data pushed to report_callback_urls is mentioned in this article. You will get the parameters along with their values mentioned in the response section under the candidate_report key. Please refer to the sample for a better understanding.
Type: Dictionary
Description: This is part of extra_parameters. This dictionary should contain the mapping of emails and corresponding redirect_urls in which the candidate will be redirected after the 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,
'auto_expiry_days': 7,
'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/partner/hackerearth/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,
"auto_expiry_days": 7,
"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 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": []
}
Type : String
Description: Message code abbreviated as mcode.
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 |
Type: List
Description: Error codes abbreviated as ecode.
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. |
| EVENTACCESSOFF | Test access is off. |
| 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. |
Type: String
Description: title of the test.
Example:
"title": "he-test"
Type: List
Description: An array of invalid emails
Example:
"invalid_emails": [
"itsnotanemail",
"another@@wrongemail",
"wrong@again"
]
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"
]
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"
]
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"
}
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 access is off from test overview page, then the JSON response returned will look like:
{
"message": "Request failed",
"ecode": [
"EVENTACCESSOFF"
],
"emessage": [
"Test has ended."
],
"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 or 10000 per day) 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 some time."
],
"mcode": "FAILED"
}
and if any other issue occurred do reach us out at api@hackerearth.com
