Tutorial

API documentation might be overwhelming and it might to be hard to understand the intention of some API endpoints and how they are used. This article tries to shine some light of how we intended the API to be used. One is of course free to use the API in any way imaginable.

If someone wants to use this API they will first contact us to get credentials for an API client. An API client is most likely a system/website that have a few customers themselves. We will call these customers organizations.

When an API Client is created we need to use it to authenticate an organization. The client makes all its request on behalf on an organization. We use standard OAuth2 authentication. You can read about it in detail here. For now we assume that an HTTP request from a client is always authenticated.

Making the first authenticated API calls

The first thing we should do is to create a Role. A role is a description of a specific job at an organization. The more information that is added to the role, the better it is. The Role has many properties like role_category, advert_body (text and HTML), location and advert_link. This role is a first class citizen in the API.

The Role is used as a parameter to the Find endpoint which you would use to get more candidates. Candidates will be sent to the advert_link property of the Role.

Start testing candidates

As your candidates come in to your system you can send them for testing. You need to create a Test using the Role. There is usually no need to create more than one test per advert/role. You can reuse one test for many candidates. When a test is created you need to redirect candidates to a "test URL". At that URL candidates will answer the questions in the test and then return back to your application to continue your process.

When the candidates return you will get a candidate_id in the return URL query parameter. This id is how we reference the candidate from now on. Don't lose it!

Match your candidates

When a candidate is tested we run our calculations and give you a Match of how well this candidate fits into the role and the organization. There are different types of matching which vary from "some information" to "all information and test results". You shoud only query what you need.

There could be a good idea to Group candidates. In other words, you put all candidates that applied for a specific job into one group. On that group we can use some additional matching queries to filter or sort the candidates. Queries like "give me top 5 candidates" or "sort candidates in group".

Share performance data

Every API client is required to share performance data back to the API. This is a hard requirement in order to improve our algorithm and provide a better match in the future.

The data we want to have back could be one or more of the following:

• What did the recruiter think of this application?
• Was the candidate called in for interview?
• What score did this candidate get after interview?
• What candidate got hired?
• After 6, 12, 18 months, how well does thic candidate perform according to the manager?
• After 6, 12, 18 months, how well does thic candidate perform according the candidate themself?
• Is there any hard data like sales performance, customer satisfaction etc?

Final thoughts

This was a shory summary of the API's feature. There are more detailed documentation and examples on the endpoint documentation pages. Please continue reading and contact technical support if you want assistance with your implementation.