Skip to content
Documentation
English
Explore guides

For administrators

Candidates

List, create, show, update, and delete candidates in the company.

Contents

Before you start

Send Accept: application/json and Authorization: Bearer YOUR_TOKEN to https://{subdomain}.talentohq.com. See API for authentication.

Path and query identifiers are UUID strings.

Successful responses use 200. Validation failures use 422. Missing or invalid tokens, and records that cannot be found, use 401.

List all candidates

GET /api/v3/candidates

Results are paginated. Pass page to move through pages of 50 records.

Response 200 

[
  {
    "id": "8cc23847-7742-4149-9951-cab9eb5b1571",
    "user_id": null,
    "name": "Candidate name",
    "email": "candidate@name.com",
    "phone": "555-555-555",
    "cover_letter": "Cover letter",
    "registered_on": null,
    "attachment": false
  },
  {
    "id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
    "user_id": "8cc23847-7742-4149-9951-cab9eb5b1571",
    "user_email": "user@user.com",
    "name": "Candidate name2",
    "email": "candidate2@name.com",
    "phone": "666-555-555",
    "cover_letter": "Other cover letter",
    "registered_on": "2024-02-09",
    "attachment": true
  }
]

Create a candidate

POST /api/v3/candidates

Request

{
  "name": "New candidate",
  "email": "new@candidate.com",
  "phone": "777-777-777",
  "cover_letter": "New cover letter",
  "user_id": "8cc23847-7742-4149-9951-cab9eb5b1571",
  "job_step_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
  "registered_on": "2023-01-01",
  "attachment": null
}

Response 200 

{
  "id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
  "user_id": "8cc23847-7742-4149-9951-cab9eb5b1571",
  "user_email": "user@user.com",
  "name": "New candidate",
  "email": "new@candidate.com",
  "phone": "666-555-555",
  "cover_letter": "Other cover letter",
  "registered_on": "2023-01-01",
  "attachment": true
}

Show a candidate

GET /api/v3/candidates/{candidate_id}

Parameter Type Description
candidate_id string (UUID) Candidate id.

Response 200 

{
  "id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
  "user_id": "8cc23847-7742-4149-9951-cab9eb5b1571",
  "user_email": "user@user.com",
  "name": "Candidate name2",
  "email": "candidate2@name.com",
  "phone": "666-555-555",
  "cover_letter": "Other cover letter",
  "registered_on": "2024-02-09",
  "attachment": true
}

Update a candidate

PUT /api/v3/candidates/{candidate_id}

Request

{
  "name": "Updated candidate",
  "email": "updated@candidate.com",
  "phone": "777-888-777",
  "cover_letter": "Updated cover letter",
  "registered_on": "2024-01-01",
  "user_id": "8cc23847-7742-4149-9951-cab9eb5b1571"
}

Response 200 

{
  "id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
  "user_id": "8cc23847-7742-4149-9951-cab9eb5b1571",
  "user_email": "user@user.com",
  "name": "Updated candidate",
  "email": "updated@candidate.com",
  "phone": "666-555-555",
  "cover_letter": "Other cover letter",
  "registered_on": "2024-02-09",
  "attachment": true
}

Delete a candidate

DELETE /api/v3/candidates/{candidate_id}

Response 200 

{}