Overview
This document is meant for partners who wish to develop an integration with HackerRank for Work. We are constantly working with ATS vendors to develop integrations for a better user experience. This document will give you all the information you need to develop an integration yourself.
Background
A number of our enterprise customers - i.e those who use HackerRank for Work Tests and Interviews for the evaluation phase, also use some other IT systems to manage their overall hiring process. These systems could either be Commercial Off-the-shelf (COTS) systems such as Oracle Taleo, Jobvite, Greenhouse, Lever, Kenexa, RecruiterBox, etc., or some bespoke home-grown system. We will refer to these apps jointly as Applicant Tracking Systems (ATS).
Such customers frequently ask for integration between their ATS and HackerRank for Work so that routine actions of managing their candidates can be done inside their ATS workflow. Examples of such routine actions include (a) inviting a shortlisted candidate to take a HackerRank for Work test, (b) viewing the results of a test for such candidates in their ATS, (c) scheduling a HackerRank interview session between an engineer and a selected candidate, (d) viewing Interview reports within the ATS interface, etc. Thus, the most commonly requested integration points involve pulling data from an existing HackerRank for Work account and doing specific actions from inside the ATS interface. We have API calls that will help implement these actions from within the ATS UI.
General Workflow
The integration typically involves adding functionality to the ATS via a plugin or customization using the HackerRank for Work API. This is best explained visually using the following diagrams.
Conventions Used in the workflows below:
Integration Setup - One Time activity
Note: Every official ATS integration will have a section within HackerRank for Work where each company’s account admin will be able to generate a key. Your ATS will appear in the following location: https://www.hackerrank.com/work/settings/api
Overall Test Flow
Overall CodePair (Interviews API) Flow
The integration Process
Sign up for a Free Trial
Head to https://www.hackerrank.com/work/signup to sign up for a free 14 day trial of our product. This account will be required in order to explore our API (see below) and to test your integration.
Explore our API
We have a simple RESTful API that will form the basis for the integration. You should start learning about our API here:
https://www.hackerrank.com/work/apidocs
Note: The above documentation is written with our end customers in mind. You should explore the API in your test account as an end customer. If you have any questions about the API you should reach out to your HackerRank point of contact or raise a support request by writing to support@hackerrank.com
Register your Integration
Once you have familiarized yourself with the API and mapped out the flows you want to support, please reach out to your HackerRank point of contact or write to us at support@hackerrank.com asking for a partner key and secret token. You will also be issued a ‘Company-wide API Key’ to use with your integration.
Change Authentication Mechanism in your Integration Code
You will have to make three changes:
- Add a custom header “X-HRW-Partner-Authorization: abcd” where abcd should be replaced with a base64-encoded version of PartnerKey:PartnerSecret.
- Add a custom header “HRW-User-Email: user@email.com” where user@email.com should be replaced with the email of the user initiating the request through your application. This should match an existing user in the customer's HRW account.
- Use the Company-wide API Key in the place of the Personal Access Token you would have used while you explored the API in your account.
- With every call you make you may also choose to include some additional metadata in your payload if there is metadata you need HackerRank to save. Some commonly seen fields include
- user_email should identify the user initiating the request. This should match an existing user in the customer's HRW account.
- candidateId may be the unique identifier for this candidate in your system. Some API calls are not candidate-specific, and in such cases, you can ignore this field.
- applicationId can be used if a candidate is able to apply to more than one Req. This can be a different field and identify the specific application. Some API calls are not candidate-specific, and in such cases, you can ignore this field.
{
...
"metadata": {
"candidateId": "16651587",
"applicationId": "25145412",
"user_email": "abcd@example.com"
}
}
Using the Partner authorization token and per-company keys are important as we have a different set of policies and rate limits. It also helps us troubleshoot customer issues originating from you more easily leading to a better user experience.
Integration Validation
Once you have modified the integration to use the above partner-authorization, we will evaluate the integration for happy paths and also some of the known corner cases we have run into with integrations in the past.
Review of End User Documentation will be an important part of the validation exercise.
General Availability
Once the validation is completed we will add an entry in the ATS Integrations page that shows all the supported integrations. Using that interface common customers will be able to enable or disable your integration by themselves.
Your integration will be available as an option on our Integration Settings Page: https://www.hackerrank.com/work/settings/api
Integration Best Practices
Error Scenarios
In our experience with ATSes, some common scenarios that lead to errors in inviting candidates are:
- The API Key is not valid for your HackerRank for Work account. (Needs to be the per-company Key and the Partner-authorization should be working properly)
- The recruiter's email address for the ATS account (sent via the metadata) is different than the email used within HackerRank for Work (e.g. using sriram.karra@hackerrank.com in the ATS account and sriram@hackerrank.com in your HRW accounts). It does not matter which one you fix as long as they are the same.
- Candidate email address is missing or invalid
- Candidate with this email has already been invited.
- Recruiter does not have a "Recruitment Seat" on HackerRank, and as such does not have the privilege to invite candidates
- Recruiter does not have permission to access a particular test
- Recruiter's HackerRank Account is not activated.
We recommend that you test your integration for all of the above scenarios and ensure the application behavior is graceful.
Error Handling
Tests API
For test API we return errors in two different formats - you need to cover both formats of responses and show the right type of message to the end-user.
Case 1: The error is local to the candidate, for example re-inviting a candidate. This has the following format:
{
"data": {
"username": “error@hackerrank.com",
"password": "96d3efe9",
"test_link": “link",
"status": false,
"error": 1002,
"error_message": "Candidate has already been invited to take the same test. If you want to reinvite, cancel the invite in your HackerRank for Work account first."
},
"message": "No candidates invited.",
}
The bolded fields indicate that an error has occurred. If there are uncaught errors in creating the candidate, they also display in this format.
Case 2: If there is an error in the recruiter’s configuration itself (usually as a result of bad config or bad format), it is returned in the following format:
{
"data": {},
"status": false,
"message": "No such test exists",
}
Actions triggering this error include invalid recruiter account, invalid emails, incorrect test id, etc.
Successful requests will be returned with 200 response codes.
Incorrect Access Token: In addition to these two error scenarios, if the user has configured the integration with an incorrect access code, we will return the error in the following format with response code 401:
{
"model": {},
"message": "Invalid Access Token"
}
CodePair API (Interviews API)
Incorrect Access Token: If the access token present in the request is invalid, we will return an empty response with a 403 status code.
Invalid information: In case the request has one or more errors other than the access token error, we will return a list of all of the errors in the errors field with a request status of 422. For example:
{
"errors": [
"title is a required field",
"interview time range is invalid",
"......."
]
}