Recruitment Marketing
Public
Introduction
The base URL for the Clinch Talent API is:
- https://api.clinchtalent.com/v2/
Data is sent and received as JSON over HTTPS. The Clinch Talent API Server implements the JSON API 1.0 format. You can read about the JSON API Specification here. You can read about client JSON API implementations here.
Online documentation for available APIs is available here.
Generating API Credentials
In order to authenticate with the Clinch Talent API you will need to generate API credentials.
- From the side menu, under Company click API.
- Click the New button.
- Enter a Name.
- Click the Save button.
- On the Your API credential details screen, take a copy of your Key and Secret as it will not be possible to access your API secret again.
- There is also the option to Try out your API credentials with this cURL statement that you can use to verify that your keys are working. The cURL statement is only valid for 15 minutes.
- Click Back to return to the API listing.
Making a request
To make a request to the Clinch Talent API library:
- Set the
Acceptheader to:application/vnd.api+json - Set the
Dateheader to a valid HTTP Date e.g.Thu, 28 Nov 2019 09:44:23 GMT. Note, some browsers don't support setting of theDateheader in XHR requests. - Set the Authorization header (described below)
How requests are signed
Requests to the API must be signed using the HMAC algorithm
Steps
- A canonical string is first created using your HTTP headers containing the content-type, content-MD5, request URI and the timestamp. If content-type or content-MD5 are not present, then a blank string is used in their place. If the timestamp isn't present, a valid HTTP date is automatically added to the request. The canonical string is computed as follows:
canonical_string = 'http method,content-type,content-MD5,request URI,timestamp' - Note: the
request URIshould include both the resource path and any querystring parameters included in that request. For example, when making a request to https://api.clinchtalent.com/v1/jobs?page=1&per_page=5, therequest URIwould be /v1/jobs?page=1&per_page=5 - This string is then used to create the signature which is a Base64 encoded SHA1 HMAC, using the client's private secret key.
- This signature is then added as the Authorization HTTP header in the form:
Authorization = APIAuth 'client access id':'signature from step 2' - On the server side, the SHA1 HMAC is computed in the same way using the request headers and the client's secret key, which is known to only the client and the server but can be looked-up on the server using the client's access ID that was attached in the header. The access ID can be any integer or string that uniquely identifies the client. The signed request expires after 15 minutes in order to avoid replay attacks.
Source: https://github.com/mgomes/api_auth
For more information, refer to the api-auth ruby gem homepage which implements this algorithm.
Endpoints for the API consist of the form https://api.clinchtalent.com/v1/:resources for collections andhttps://api.clinchtalent.com/v1/:resources/:id for individual resources. The IDs for a resource can be obtained by making a request to the collection routes and inspecting the IDs of the resources returned.
Response Format
The Clinch Talent API response format uses the JSON API Specification.
Request/Response for an individual resource
GET /candidates/fec86480734fa3ef1e7a
{
"data": {
"type": "candidates",
"id": "fec86480734fa3ef1e7a",
"attributes": {
// ... this candidate's attributes },
"relationships": {
// ... this candidate's relationships
}
}
}
Request/Response for a collection of resources
GET /candidates/
[{
"data": {
"type": "candidates",
"id": "fec86480734fa3ef1e7a",
"attributes": {
// ... this candidate's attributes },
"relationships": {
// ... this candidate's relationships
}
}
},
{
"data": {
"type": "candidates",
"id": "04777686950a7d399626",
"attributes": {
// ... this candidate's attributes },
"relationships": {
// ... this candidate's relationships }
} }]
Pagination
GET /candidates?per_page=10&page=2
Side Loading
A resource will contain references to other resources e.g. a candidate has a social profile. The Clinch Talent API "side loads" these resources, by supporting an include parameter.
GET /candidates/fec86480734fa3ef1e7a?include=social_profile
{
"data": {
"type": "candidates",
"id": "fec86480734fa3ef1e7a",
"attributes": {
// ... this candidate's attributes
},
"relationships": {
"social_profile": {
"data": {
"id": "8ac9610ec658faf15fc8",
"type": "social_profiles"
}
}
}
},
"included": [
{
"id": "8ac9610ec658faf15fc8",
"type": "social_profiles",
"attributes": {
// ... this social profile's attributes },
"relationships": {
// ... this social profile's relationships
}
}
]
}
To side load several types of resource, join each resource name with a comma, for exampe:
GET /candidates/fec86480734fa3ef1e7a?include=social_profile,page_sessions
For a list of client libraries that can consume these responses, refer to JSON API client libraries.