How to create a candidate via API?

This guide will help you to create your first candidate using our API

Before we start...

We recommend you to have a look to Using Postman as developer tool article before starting a candidate creation. We will be on the same page and have the same view on the situation.

Let's create a candidate

Actually, for creating a candidate as an entity, you need just one request with mandatory fields like AccountID, Name, Language, Email, ...  (Check our API documentation for full details

POST /candidates

Using Postman : Regarding the API documentation, each request has a Parameters table where we can find all info about needed Params and Code samples which you can use in the Postman request body tab.

The accountId param is necessary to relate candidates to the needed Account "folder". You can find or create it with Accounts requests Postman collection and the Account API documentation.

And we have a candidate!

So, if everything is ok in the request params - the server returns 200Ok and a candidate ID. This means we have a new candidate, which already can be used on the CheckHub platform by Admin or by the candidate himself. But right now, nothing is required from this candidate. Let's request some document to provide : an ID card & a Driving License

How to create relations between documents and a candidate?

For requesting a document from a candidate we have to create a relation between the needed documentType and the candidate. This relation is named “candidateDocumentTypes”. 

• Firstly, we have to GET documentTypeId
  via Document Type Postman collection. With it, you can CRUD your document types. Also, please check API Document Type.
• Then, we can follow this simple formula:
  candidateId + documentTypeId = candidateDocumentTypes.
  Use API request
  POST /candidateDocumentTypes
• Check the Parameters table and add necessary "keys" and "values" to the request body.
  
  

  
  

Here we go, your created candidate has a requested document type, congratulations! You have the ability to add as many documents to the candidate as you need.

Important: If the documentType has a unique param, it can be only one for one candidate entity.

How to relate resources to the candidate entity?

For requesting a resource from a candidate we have to create a relation between the needed resource entity and the candidate. This relation is named “candidateResources ”.

• Firstly, we have to GET resourceId via Resources Postman collection.
• Then you can use the current formula:
  candidateId + resourceId  = candidateResources.
  Use API request:
  POST /candidateResources
• Check the Parameters table and add necessary "keys" and "values" to the request body.

Congratulations, your new candidate has a requested resource!
As with documents, we have the ability to add as many resources to the candidate entity as you need.

Anything's wrong?

If there is any issue during this guide, we invite you to have a look at our Troubleshooting & Error handling article to track down origin of your problem. If you have questions, please contact us