TABLE OF CONTENTS


Introduction

This article is aimed at developers and technical colleagues who have knowledge of REST APIs and serves as a guide to integrate Ezekia API endpoints into your applications. These are from a collection of questions that are frequently asked to our developers. Whether the application is a WordPress application or an external service, we hope this guide will help.


When developing your application you may not want to use customers' live data. We can provide you with a sandbox environment where you can create your own dummy data and test your APIs without any issue. If you are interested please let us know.


Examples below are shown in either Postman or PHP cURL. When making calls, you will need a bearer token. Details can be found here:

https://ezekia.freshdesk.com/support/solutions/articles/101000504349-api-user-credentials


A list of these REST API endpoints and their documentation can be found at https://ezekia.com/api/documentation.


Ezekia also supports Webhooks. https://ezekia.freshdesk.com/en/support/solutions/articles/101000503988-api-webhooks

Probable workflow for a candidate applying for a job role on a WordPress or similar website

1. Check if the person's email already exists in Ezekia

GET /api/v2/people?query={email}&filterOn=email


If the email does not exist, create a new person and add their profile details

POST /api/v2/people


If the email does exist, then retrieve the ID of that person and update their profile details

PUT /api/v2/people/{id}


However, if there are multiple instances of the same email address, then you will need to determine which of those users are applying.


2. Creating/updating a person and then uploading their CV and/or cover letter

When creating or updating a person, you can send key/values such as first name, last name, emails, etc in an 'application/json' request and then send the CV/cover letter in a different API call. This will allow you to send any type of document such as CV and/or cover letter. The example below shows it being attached to the person section.


POST /api/v2/people (application/json)

or

PUT /api/v2/people/{id} (application/json)

 

and then 

POST /api/people/{id}/documents (multipart/form-data)


3. Alternatively, parse a CV and extracting the contents to create or update a person


Alternatively you can just set the header to 'multipart/form-data' and upload the CV to the API and the contents of the CV will automatically be parsed and the data extracted will be saved to Ezekia. There is no need for any other data to be sent.


Please note, if you update the person and parse the CV automatically, it will replace existing data with that from the CV.

POST /api/v2/people (multipart/form-data)

or

PUT /api/v2/people/{id} (multipart/form-data)


4. You want to save the person's CV/cover letter to an assignment rather than to a person

After creating/updating a person, you may want to save the CV to the assignment rather than a person by including the assignment or project id.

POST /api/assignments/{id}/documents (multipart/form-data)


5. Assign that person to an assignment to make them a candidate

When you create a new person you can just add the 'assignmentId' key to the request.

POST /api/v2/people


Alternatively, you can use this endpoint. You will need the person id and assignment id.

POST /api/assignments/{id}/candidates


6. Add a status tag to the candidate of an assignment

POST /api/assignments/{id}/candidates/statuses


You can add a custom field to a person and scope it to 'Assignment (as candidate).

PUT /api/people/{id}/additional-info



Custom Fields


How do I return results by type (projects, people or companies) with their custom fields and values?

GET /api/<type>?fields=manager.customValues

How do I return results that contain specific custom field values?

If you want to retrieve all records where 'Place of birth' is 'Japan', you will need to do:

GET /api/<type>?fields=manager.customValues&filterOn=customField&query=Japan


NOTE: At present you cannot search by specific custom fields only by custom fields are a whole.


How do I return custom fields and their values belonging to a specific type?


Including type details

GET /api/<type>/<id>?fields=manager.customValues

Just custom fields and their values:


GET /api/<type>/<id>/additional-info



How do I set custom values belonging to a specific type?


You will need to retrieve the IDs of the custom fields you want to use. We are using 'people' in this example. You can use 'projects' or 'companies' depending on the custom field type.

GET /api/custom-fields/<type>



Using the custom field IDs, you can now set the custom fields on a specific person.


GET /api/<type>/<id>/additional-info


The custom fields and their values will can now be seen on the platform.



How do I clear a custom field value?

This time you need to set the value to null. 

When you run this then the value is removed and no longer shows.


Pagination

How do I paginate the results returned from the API?

Results are paginated by default. To change the default number of results per page, change the 'count' parameter. For example, to view 50 results per page and go to page 3 (records 101-150) you would do:

GET /api/projects?count=50&page=3

count=50 - Return 50 results per page.

page=3 - Return the third page of results.


Why am I getting errors when trying to retrieve more than 10K results?

We are in the process of upgrading our API to overcome the hard limit of 10K. In the meantime, we have implemented a solution that will allow you to retrieve the records over that limit. 

 

Our suggestion is to use the ‘from’ parameter when retrieving the records, looping through each page and using the last id returned to fetch the next set of records (starting from the last id).

GET /api/people?count=100&page=100&sortBy=id&from=8853342

sortBy=id - Sort the results by ID.

from=8853342 - start the results from id 8853342.


Uploading CVs/resumes and other documents

How do I upload a CV/resume belonging to a person?

Method 1 - When creating a new person.


Use POST /api/people and then choose multipart/form-data. This method will scan the CV/resume and will identify the person’s details and add them to the platform automatically.

resume - The file attachment (ensure you select 'File').

assignmentId - If you want to link the person to a specific assignment, then add the assignment/project id.


The above screenshot is only valid in Postman and Insomnia. To achieve this using cURL, then do:


curl --location 'https://ezekia.com/api/people' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--form 'resume=@"/Users/cvs/Downloads/john-smith.pdf"' \
--form 'assignmentId="530"' \
--form 'ownerId="13520"'


Method 2 - When updating an existing person.


Use POST /api/people/{id} and again choose multipart/form-data. Don’t forget to use _method=PUT.


curl --location 'ezekia.com/api/people/15236' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--form '_method="PUT"' \
--form 'resume=@"/Users/cvs/Downloads/john-smith.pdf"' \
--form 'assignmentId="530"'

If you are using WordPress, you may want to use:

<?php
// needless to say, but replace everything wrapped in < > with correct values

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://ezekia.com/api/people/15236',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array('resume'=> new CURLFILE('<ABSOLUTE FILE PATH>'),'_method' => 'PUT'),
  CURLOPT_HTTPHEADER => array(
    'Accept: application/json',
    'Authorization: Bearer <TOKEN>'
  ),
));

$response = curl_exec($curl);

// Response HTTP code
$responseCode = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);

curl_close($curl);

// ECHO BEING USED FOR TESTING PURPOSES ONLY
// $response will be either a person object, if the request was successful OR
// it will be a message object (see below)
echo $response;


How do I attach other documents such as cover letters to a record?

To attach a document to a person, project or company model, use the documents endpoint as shown below.

POST /api/<model>/<id>/documents


You can add an array of files to the request.


curl --location 'ezekia.com/api/people/14736/documents' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--form 'files[]=@"/Users/cvs/Downloads/test.pdf"'


How do I retrieve all uploaded document information for all candidates on a specific project?

Enter the project id in GET /api/projects/<id>/candidates?fields=manager.attachments.

Add fields=manager.attachments parameter to ensure all documents are returned.

Downloading Documents

How do I download and store documents I have previously uploaded to Ezekia?


The best way is to use cURL in your own application to retrieve the people, company and project documents and download it to your own server.

You need to retrieve the list of documents from an endpoint. In this case, we will retrieve all candidates attachments from a specific project.


You will need to do:

GET /api/projects/<id>/candidates?fields=manager.attachments


This will return an array of attachments in the 'manager' object. You will need to retrieve the attachment id, attachment filename and the person id.


In your own web application, you would retrieve the documents and download it using CURL similar to the example below:


<?php
$fp = fopen ('attachment.pdf', 'w+');
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_FILE => $fp,
  CURLOPT_URL => 'ezekia.test/api/v2/people/14269/documents/947',
  CURLOPT_BINARYTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni.....'
  ),
));

$response = curl_exec($curl);
$error = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ($error === 404) {
  echo 'not found';
}
curl_close($curl);
fclose($fp);


Pipeline Tags

How do I retrieve pipeline tags for all candidates on a specific project?

Enter the project id in GET /api/projects/<id>/candidates?fields=meta.candidate.

Add fields=meta.candidate parameter to ensure pipeline tags are returned.


Bulk Imports

I want to import many project or person records into the API?

The API does not support bulk uploads but there is a file import feature on the platform.


For more information, see https://ezekia.freshdesk.com/support/solutions/articles/101000415132-what-is-the-basic-spreadsheet-import-process-



Incremental updates

I want to poll new or updated records periodically?

To check for new or updated records, it is recommended to use webhooks. Alternatively, you can filter by the 'since' parameter and order by the date/time of creation or update. Set the 'since' parameter to the last timestamp when the records were checked.

POST /api/people?since=1620136853&sortBy=createdAt&sortOrder=desc

Notes

How do I add a note to a candidate on a specific assignment?

To add a note, enter the person id in POST /api/people/<id>/notes. Inside the context array, add the assignment id and enter assignment as type.