FAfactorialhr
Ats > Candidate

Creates a Candidate

Changed on

Creates candidates related to a particular company in an ATS

post/api/2026-10-01/resources/ats/candidates

Request

  • Base URL
    https://api.factorialhr.com
  • URL
    https://api.factorialhr.com/api/2026-10-01/resources/ats/candidates
  • Auth
    • OAuth 2
      Authorization code: https://id.factorialhr.com/oauth/authorize
      Token URL: https://id.factorialhr.com/api/oauth/token scopes: recruitment
    • or API key in header x-api-key

Request body

first_namestring required

first name of the candidate.

last_namestring required

last name of the candidate.

emailstring

email of the candidate.

company_idstring required

company identifier, refers to /core/me endpoint.

talent_poolboolean

is the candidate part of talent pool?

consent_given_atstring

date when the consent was given.

sourcestring

source of the candidate.

mediumstring

specifies additional details related to the source of the candidate, such as the referrer name for example if the source is referred.

phone_numberstring

phone number of the candidate.

personal_urlstring

personal web resource from the candidate.

genderstring

gender of the candidate.

Example request

{
  "first_name": "Ana",
  "last_name": "Fernandez Perez",
  "email": "ana@factorial.com",
  "company_id": "1",
  "talent_pool": true,
  "consent_given_at": "2021-01-01T00:00:00Z",
  "source": "referred",
  "medium": "email",
  "personal_url": "https://anaperez.factorial.com",
  "gender": "female"
}

Response

CREATED

idstring required

identifier of the candidate.

company_idstring

company identifier.

first_namestring required

name of the candidate.

last_namestring required

last name of the candidate.

full_namestring required

full name of the candidate.

emailstring

email of the candidate.

talent_poolboolean required

is the candidate part of talent pool?

phone_numberstring

phone number of the candidate.

created_atstring required

creation date of the candidate.

updated_atstring required

last update of the candidate.

consent_given_atstring

date when the consent was given.

inactive_sincestring

date when the candidate became inactive.

ats_job_posting_idsstring[]

list of job posting identifiers.

personal_urlstring

personal web resource from the candidate.

consent_expiration_datestring

date when the consent expires.

consent_to_talent_poolboolean

consent to talent pool.

mediumstring

specifies additional details related to the source of the candidate, such as the referrer name for example if the source is referred.

source_idstring

candidate source identifier, refers to ats/candidate_sources endpoint.

gender'female' | 'male' | 'unanswered' | 'other'

gender of the candidate.

scorenumber

score of the candidate.

Example response

{
  "id": "1",
  "company_id": "1",
  "first_name": "Ana",
  "last_name": "Fernandez Perez",
  "full_name": "Ana Fernandez Perez",
  "email": "ana@factorial.com",
  "talent_pool": true,
  "created_at": "2021-01-01T00:00:00Z",
  "updated_at": "2021-01-01T00:00:00Z",
  "consent_given_at": "2021-01-01T00:00:00Z",
  "inactive_since": "2021-01-01T00:00:00Z",
  "ats_job_posting_ids": [
    "1",
    "2",
    "3"
  ],
  "personal_url": "https://anaperez.factorial.com",
  "consent_expiration_date": "2021-01-01T00:00:00Z",
  "consent_to_talent_pool": true,
  "medium": "email",
  "source_id": "1",
  "gender": "female",
  "score": 7
}

Changes