cURL
Python
JavaScript
PHP
Go
Java
curl --request POST \
--url https://api.bindbee.dev/api/ats/v1/candidates \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-connector-token: <x-connector-token>' \
--data '{
"data": {
"first_name": "John",
"last_name": "Doe",
"company": "Google",
"title": "SOFTWARE ENGINEER",
"is_private": true,
"can_email": true,
"locations": [
"San Francisco",
"New York"
],
"phone_numbers": [
"123-456-7890"
],
"email_addresses": [
"john@doe.com"
],
"urls": [
{
"type": "LINKEDIN",
"value": "https://www.linkedin.com/in/johndoe"
}
],
"tags": [
"JUNIOR",
"INTERMEDIATE"
],
"applications": [
"018b4bfb-5ece-70b1-ad5e-862a9433aa65"
],
"attachments": [
"018b4bfb-5ece-70b1-ad5e-862a9433aa65"
],
"avatar": "https://www.example.com/avatar.jpg",
"job_interview_stage_id": "018b4bfb-5ece-70b1-ad5e-862a9433aa65",
"job_id": "018b4bfb-5ece-70b1-ad5e-862a9433aa65"
},
"remote_user_id": "018b4bfb-5ece-70b1-ad5e-862a9433aa65",
"job_requisition_id": "R-00007"
}'
To create an candidate in ATS, you first need to fetch the request body structure that ATS expects. This structure varies based on the ATS provider (e.g., Greenhouse, Teamtailor, BambooHR). The request body consists of three parts:
Model Keys : Standard attributes required for all candidate.
Additional Attributes : Specific fields required by the chosen ATS.
Custom Fields : Extra metadata for specific implementations.
Note: Some attributes may have allowed_values
, meaning only specific values are permitted based on the customer’s ATS configuration. Ensure you check for these constraints before submitting the request.
Step 1: Fetch the Required Request Body
Before calling the Create Candidate API, you need to get the request structure using the Meta Create Candidate API.
Step 2: Create an Candidate
Once you have the request body structure, use the Create Candidate API to send the request.
Bearer authentication header of the form Bearer <token>
, where <token>
is your auth token.
CreateCandidate AtsCandidateWrite The candidate's first name.
The candidate's last name.
The name of the company where candidate has applied.
The position for which the candidate has applied
Whether the candidate's information is private.
Whether the candidate can be emailed.
The location of the candidate.
Example: ["San Francisco", "New York"]
The candidate's phone numbers.
The candidate's email addresses.
The candidate's URLs. This can include a personal website, LinkedIn profile, or other relevant URLs.
The type of site. Possible values include: PERSONAL, COMPANY, PORTFOLIO, BLOG, SOCIAL_MEDIA, OTHER, JOB_POSTING. In cases where there is no clear mapping, the original value passed through will be returned.
Example: [
{
"type": "LINKEDIN",
"value": "https://www.linkedin.com/in/johndoe"
}
]
The candidate's tags. Tags are used to categorize candidates and can be used to filter candidates in the UI.
Example: ["JUNIOR", "INTERMEDIATE"]
The candidate's applications.
Example: ["018b4bfb-5ece-70b1-ad5e-862a9433aa65"]
The candidate's attachments.
Example: ["018b4bfb-5ece-70b1-ad5e-862a9433aa65"]
Example: "https://www.example.com/avatar.jpg"
data. job_interview_stage_id
The job stage id for the candidate
Example: "018b4bfb-5ece-70b1-ad5e-862a9433aa65"
The job id for the candidate
Example: "018b4bfb-5ece-70b1-ad5e-862a9433aa65"
Example: "018b4bfb-5ece-70b1-ad5e-862a9433aa65"
The job requisition id in external ATS
The candidate's first name.
The candidate's last name.
The name of the company where candidate has applied.
The position for which the candidate has applied
Whether the candidate's information is private.
Whether the candidate can be emailed.
The location of the candidate.
Example: ["San Francisco", "New York"]
The candidate's phone numbers.
The candidate's email addresses.
The candidate's URLs. This can include a personal website, LinkedIn profile, or other relevant URLs.
The type of site. Possible values include: PERSONAL, COMPANY, PORTFOLIO, BLOG, SOCIAL_MEDIA, OTHER, JOB_POSTING. In cases where there is no clear mapping, the original value passed through will be returned.
Example: [
{
"type": "LINKEDIN",
"value": "https://www.linkedin.com/in/johndoe"
}
]
The candidate's tags. Tags are used to categorize candidates and can be used to filter candidates in the UI.
Example: ["JUNIOR", "INTERMEDIATE"]
The candidate's applications.
Example: ["018b4bfb-5ece-70b1-ad5e-862a9433aa65"]
The candidate's attachments.
Example: ["018b4bfb-5ece-70b1-ad5e-862a9433aa65"]
Example: "https://www.example.com/avatar.jpg"
data. job_interview_stage_id
The job stage id for the candidate
Example: "018b4bfb-5ece-70b1-ad5e-862a9433aa65"
The job id for the candidate
Example: "018b4bfb-5ece-70b1-ad5e-862a9433aa65"
Example: "018b4bfb-5ece-70b1-ad5e-862a9433aa65"
The job requisition id in external ATS
Fields related to models other than employee Model
Example: {
"contract_end_date": "2025-12-31T00:00:00",
"previous_employer": "TechCorp"
}
The custom fields related to the model
Example: { "customTshirtSize": "XXL" }
The candidate's first name.
The candidate's last name.
The name of the company where candidate has applied.
The position for which the candidate has applied
The date of the last interaction with the candidate.
Whether the candidate's information is private.
Whether the candidate can be emailed.
The location of the candidate.
Example: ["San Francisco", "New York"]
The candidate's phone numbers.
The candidate's email addresses.
The candidate's URLs. This can include a personal website, LinkedIn profile, or other relevant URLs.
The type of site. Possible values include: PERSONAL, COMPANY, PORTFOLIO, BLOG, SOCIAL_MEDIA, OTHER, JOB_POSTING. In cases where there is no clear mapping, the original value passed through will be returned.
Example: [
{
"type": "LINKEDIN",
"value": "https://www.linkedin.com/in/johndoe"
}
]
The candidate's tags. Tags are used to categorize candidates and can be used to filter candidates in the UI.
Example: ["JUNIOR", "INTERMEDIATE"]
The candidate's applications.
Example: ["018b4bfb-5ece-70b1-ad5e-862a9433aa65"]
Please share the details like this, AtsAttachmentWrite model fields are shared in model_fields key
The AtsAttachmentWriteForCandidate object is used to represent a file attachment linked to a candidate's application within the ATS.
The name of the file attached.
The URL where the file is stored and can be retrieved.
Required string length: 1 - 2083
Example: "https://example.com/path/to/resume.pdf"
attachments. attachment_type
The type of attachment, such as 'resume', 'cover letter', etc.
The MIME type of the file (e.g., 'application/pdf', 'image/png').
The candidate to whom the attachment belongs.
Example: "018b4bfb-5ece-70b1-ad5e-862a9433aa65"
attachments. remote_user_id
The id of user using the integration
Example: "018b4bfb-5ece-70b1-ad5e-862a9433aa65"
When the third party's candidate was created.
When the third party's candidate was last updated.
Example: "https://www.example.com/avatar.jpg"
The job id for the candidate
Example: "018b4bfb-5ece-70b1-ad5e-862a9433aa65"
The response is of type any
.