Retrieve candidates

You can retrieve candidates using the API.

Request

This method allows you to search for one or more candidates:

POST /company/{companyID}/search/applicants

Parameters

Parameter	In	Type	Required	Description	Example
companyId	path	string	✔️	Company identifier	Wy3EOp2NP3p1KMq8
firstname	payload	string		firstname of the candidate	John
lastname	payload	string		lastname of the candidate	Doe
email	payload	string		email of the candidate	john.doe@mail.fr
hired	payload	boolean		Whether the candidate was hired or not	true
column	payload	string		title of the column where the candidate is located	HR Interview
start	payload	string		Date in MM/DD/YY format to search for candidates created from a given date	11/15/22
end	payload	string		Date in MM/DD/YY format to search for candidates created before a given date	12/25/22
start_update	payload	string		Date in MM/DD/YY format to search for candidates modified from a given date	11/15/22
end_update	payload	string		Date in MM/DD/YY format to search for candidates modified before a given date	12/25/22
company	payload	string		Search across multiple companies for multi-account setups
vacancy	payload	string		id of the listing where the candidate applied	k5aMxpQoK7nGZ2Oz
phone	payload	string		Candidate phone number	06 06 06 06 06

Request examples

Name

cURL request

curl -X POST https://api.flatchr.io/company/Wy3EOp2NP3p1KMq8/search/applicants
    -H "Authorization: Bearer {token}"
    -H 'Content-Type: application/json'
    -d '{"lastname":"{name}"}'

Email

cURL request

curl -X POST https://api.flatchr.io/company/Wy3EOp2NP3p1KMq8/search/applicants
    -H "Authorization: Bearer {token}"
    -H 'Content-Type: application/json'
    -d '{"email":"{mail@mail.com}"}'

Hired

cURL request

curl -X POST https://api.flatchr.io/company/Wy3EOp2NP3p1KMq8/search/applicants
    -H "Authorization: Bearer {token}"
    -H 'Content-Type: application/json'
    -d '{"hired":"true"}'

Archived

cURL request

curl -X POST https://api.flatchr.io/company/Wy3EOp2NP3p1KMq8/search/applicants
    -H "Authorization: Bearer {token}"
    -H 'Content-Type: application/json'
    -d '{"status": 0}'

Since 12/25/2021

cURL request

curl -X POST https://api.flatchr.io/company/Wy3EOp2NP3p1KMq8/search/applicants
    -H "Authorization: Bearer {token}"
    -H 'Content-Type: application/json'
    -d '{"start":"12/25/21"}'

Between 01/01/2022 and 01/10/2022

cURL request

curl -X POST https://api.flatchr.io/company/Wy3EOp2NP3p1KMq8/search/applicants
    -H "Authorization: Bearer {token}"
    -H 'Content-Type: application/json'
    -d '{"start":"01/01/22", "end":"01/10/22"}'

Multi-account

cURL request

curl -X POST https://api.flatchr.io/company/Wy3EOp2NP3p1KMq8/search/applicants
    -H "Authorization: Bearer {token}"
    -H 'Content-Type: application/json'
    -d '{"hired":"true","company":"{company}"}'

Response

Name	Type	Description
applicant	string	Candidate ID
vacancy	string	Name of the listing they applied to
column	string	Column where the candidate is located
vacancy_id	integer	Listing identifier
external_id	string	External ID
status	integer	Candidate status (0: Archived, 1: Active)
score	integer	Candidate score
hired	boolean	Whether the candidate was hired
firstname	string	First name
lastname	string	Last name
email	string	Email
phone	string	Phone
created_at	timestamp	Candidate creation date (DD/MM/YY)
updated_at	timestamp	Candidate update date (DD/MM/YY)
source	string	Application source
reason	string	Hiring or rejection reason
import	boolean	Whether the candidate was imported
creator	string	Full name of the member who referred the candidate
cv.key	string	CV key
cv.extension	string	CV file extension

Response example

Standard response

[{
    "applicant": "BEjyY9lke8nZl7o2",
    "vacancy": "Sales Representative - Paris - Permanent",
    "column": "HR Interview",
    "vacancy_id": "1zj8Md6kD8nYZ70J",
    "external_id": "",
    "status": 1,
    "score": 90,
    "hired": false,
    "firstname": "michelle",
    "lastname": "dekerre",
    "email": "michelle.d@mail.com",
    "phone": "",
    "created_at": "15/11/24",
    "source": "Career site",
    "import": true,
    "cv": {
        "key": "candidates/2024/11/c18f5238-a774-4609-8d59-f022a8f781db/dekerre-michelle",
        "extension": "pdf"
    }
}]

Archived

[{
    "applicant": "2o7lZn8ekl9YyjEB",
    "vacancy": "Sales Representative - Paris - Permanent",
    "column": "HR Interview",
    "vacancy_id": "1zj8Md6kD8nYZ70J",
    "external_id": "",
    "status": 0,
    "score": 10,
    "hired": false,
    "firstname": "Joe",
    "lastname": "Seant",
    "email": "joe.seant@mail.com",
    "phone": "",
    "created_at": "15/11/24",
    "source": "Career site",
    "reason": "Insufficient experience for the position",
    "import": true
}]