Skip to main content
PATCH
/
api
/
v1
/
candidates
/
{id}
Update candidate
curl --request PATCH \
  --url https://app.outhire.ai/api/v1/candidates/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Jane Doe",
  "rating": 5,
  "stage": "phonescreen",
  "notes": "Spoke with hiring manager",
  "ats_candidate_id": "ext-456",
  "location": "Melbourne, Australia"
}
'
{
  "data": {
    "id": 419,
    "public_id": "e3745169-a137-4b99-8fcc-373d6d4c8d60",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+61412345678",
    "linkedin": "https://linkedin.com/in/janedoe",
    "location": "Sydney, Australia",
    "stage": "applied",
    "rating": 4,
    "fit_score": 82,
    "application_source": "public_api",
    "ats_candidate_id": "ext-456",
    "job": {
      "id": 40,
      "title": "Senior Engineer"
    },
    "created_at": "2026-03-11T10:21:54.289003Z",
    "updated_at": "2026-03-11T10:21:54.544000Z",
    "applied_at": "2026-03-11T10:21:54.289003Z",
    "resume_url": "https://api.outhire.ai/storage/cv/example.pdf?token=eyJhbGciOiJIUzI1NiIs...",
    "resume_data": {
      "personalInfo": {
        "name": "Jane Doe",
        "email": "jane@example.com"
      },
      "summary": "Senior engineer with 8 years of experience"
    },
    "resume_status": "processed"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
integer
required

Numeric candidate id.

Body

application/json

Request body for updating a candidate.

All fields are optional, but at least one recognized field must be present. Several fields are nullable and can be explicitly cleared by sending null. stage is not nullable in the current implementation.

​
name
string

Candidate name after trimming.

Required string length: 1 - 200
Example:

"Jane Doe"

​
email
string<email> | null

Optional candidate email. Used in duplicate detection by job.

Example:

"jane@example.com"

​
phone
string | null

Candidate phone number, or null to clear it.

Maximum string length: 100
Example:

"+61 412 345 678"

​
linkedin
string<uri> | null

LinkedIn profile URL, or null to clear it.

Example:

"https://linkedin.com/in/janedoe"

​
location
string | null

Freeform location, or null to clear it.

Maximum string length: 500
Example:

"Melbourne, Australia"

​
notes
string | null

Optional note that creates a note_added activity row.

Maximum string length: 2000
Example:

"Spoke with hiring manager"

​
rating
integer | null

Candidate rating from 1 to 5, or null to clear it.

Required range: 1 <= x <= 5
Example:

5

​
ats_candidate_id
string | null

External ATS candidate id, or null to clear it.

Maximum string length: 255
Example:

"ext-456"

​
stage
enum<string>

New candidate stage. Cannot be null in the current implementation.

Available options:
prospect,
applied,
phonescreen,
inprogress,
hired,
rejected
Example:

"phonescreen"

Response

Candidate updated

Wrapper for a single candidate resource.

​
data
object
required

Public representation of a candidate.

Example:
{
  "id": 419,
  "public_id": "e3745169-a137-4b99-8fcc-373d6d4c8d60",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "+61412345678",
  "linkedin": "https://linkedin.com/in/janedoe",
  "location": "Sydney, Australia",
  "stage": "applied",
  "rating": 4,
  "fit_score": 82,
  "application_source": "public_api",
  "ats_candidate_id": "ext-456",
  "job": { "id": 40, "title": "Senior Engineer" },
  "created_at": "2026-03-11T10:21:54.289003Z",
  "updated_at": "2026-03-11T10:21:54.544000Z",
  "applied_at": "2026-03-11T10:21:54.289003Z",
  "resume_url": "https://api.outhire.ai/storage/cv/example.pdf?token=eyJhbGciOiJIUzI1NiIs...",
  "resume_data": {
    "personalInfo": {
      "name": "Jane Doe",
      "email": "jane@example.com"
    },
    "summary": "Senior engineer with 8 years of experience"
  },
  "resume_status": "processed"
}