Recruitment Marketing Public

Introduction

The base URL for the Clinch Talent API is:

Data is sent and received as JSON over HTTPS. The Clinch Talent API Server implements the JSON API 1.0 format. You can find information about the JSON API Specification here and the details on client JSON API implementations here.

Online documentation for available APIs is available here:

Generating API Credentials

To authenticate with the Clinch Talent API you will need to generate API credentials.

1. From the side menu under Company click API.
2. Click the New button.
3. Enter a Name.
4. Click the Save button.
5. 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.
6. 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.
7. Click Back to return to the API listing.

Making a request

To request the Clinch Talent API library:

1. Set the Accept header to: application/vnd.api+json
2. Set the Date header to a valid HTTP Date (e.g. Thu, 28 Nov 2019 09:44:23 GMT).
   

   Note: Some browsers don't support setting of the Date header in XHR requests.

3. 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 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 URI should include both the resource path and any querystring parameters included in that request. For example, when making a request to https://api.clinchtalent.com/v2/jobs?page=1&per_page=5, the request URI would be /v2/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 string will be used in the following step.
• This signature is then added as the Authorization HTTP header in the form: Authorization = APIAuth 'client access id':'signature generated in the previous step'
• On the server side, the SHA1 HMAC is computed in the same way using the request headers and the client's secret key. The secret key is known to only the client and the server but can be searched for 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 to avoid replay attacks.
• For modifying requests such as POST or PUT, a request header called X-AUTHORIZATION-CONTENT-SHA256 is set. The value of this header is calculated by first performing a SHA256 digest of the request body, and then calculating a Base64 encoding of that digest e.g. in JavaScript:

  // using the javascript 'crypto-es' library
  if (request.method === "POST" || request.method === "PUT") {
    const bodySha256 = CryptoES.SHA256(request.body)
    request.headers["X-AUTHORIZATION-CONTENT-SHA256"] = CryptoES.enc.Base64.stringify(bodySha256)
  }

Source: HMAC authentication for Rails and HTTP Clients 

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/v2/:resources for collections andhttps://api.clinchtalent.com/v2/: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 resources, join each resource name with a comma. For example:

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.