Getting Started

Introduction

The base url for the Clinch Talent API is  https://api.clinchtalent.com/v1/.

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.

Generating API Credentials

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

  • Login to your Clinch Talent account
  • Navigate to Settings > Clinch API
  • Click the red button to create a new API Credential. Supply a name and click 'Save'.

You will be brought to a temporary screen containing your API Access ID and Secret. Please take note of these at this point as it will not be possible to access your API secret again.

This screen also contains a sample cURL statement that you can use to verify that your keys are working. Note that the cURL statement is only valid for 15 minutes.


Client Libraries

To use the Clinch Talent API you can use our  existing ruby client. This client will implement the HMAC algorithm and sign your requests so that they can be received by the Clinch Talent API.

Alternatively, you can use API by implementing your own client.

How to make a request

To make a request to the Clinch Talent API library:

  • Set the Accept header to: application/vnd.api+json
  • Set the Date header to a valid HTTP Date e.g. Thu, 10 Dec 2015 09:44:23 GMT. Note, some browsers don't support setting of the Dateheader 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 = 'content-type,content-MD5,request URI,timestamp'
  • 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.

(referenced from  https://github.com/mgomes/api_auth)

For more information, please visit 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  includeparameter.

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 e.g.

GET /candidates/fec86480734fa3ef1e7a?include=social_profile,page_sessions
			

Here is a list of all side loadable resources:

  • page_sessions
  • timeline_entries
  • form_submissions
  • web_sessions.events.user_agent
  • web_sessions.events.call_to_action
  • web_sessions.events.form_submission.fields
  • web_sessions.events.city
  • messages.from
  • list_memberships
  • cities
  • recent_city
  • newest_event

For a list of client libraries that can consume these responses, see  JSON API client libraries.

Still need help? Contact Us Contact Us