Skip to main content
PATCH
/
v1
/
update-candidate
curl --location --request PATCH 'https://api.hirempire.com/v1/update-candidate' \
--header 'Authorization: Bearer sk-••••••••••••' \
--header 'Content-Type: application/json' \
--data-raw '{
    "candidate_id": "8fc4ea3c-ecc4-4a92-96fd-a14436a79a1b",
    "status": "rejected"
}'

{
  "success": true,
  "id": "8fc4ea3c-ecc4-4a92-96fd-a14436a79a1b",
  "status": "rejected"
}
Send only the fields you want to change. All fields except candidate_id are optional.

​
Authentication

​
Authorization
string
required
Bearer authentication header of the form Bearer <token>, where <token> is your API token.

​
Request Body

​
candidate_id
string
required
The candidate to update.
​
status
string
New pipeline status. One of: applied screening phone_screen interview technical offer hired rejected withdrawn on_hold shortlisted qualified uploaded.
​
tags
string[]
Array of free-form tags. Replaces the existing tag list.
​
pool_stage
string
Talent-pool stage. One of: cold warm hot not_interested. Pass null to clear.
​
note_to_candidate
string
Recruiter note attached to the candidate (used in follow-up emails). Pass null to clear.
At least one field beyond candidate_id must be provided. Otherwise the response is 400 At least one updatable field must be provided.
curl --location --request PATCH 'https://api.hirempire.com/v1/update-candidate' \
--header 'Authorization: Bearer sk-••••••••••••' \
--header 'Content-Type: application/json' \
--data-raw '{
    "candidate_id": "8fc4ea3c-ecc4-4a92-96fd-a14436a79a1b",
    "status": "rejected"
}'

​
Response

​
success
boolean
Indicates if the candidate status was updated successfully
​
id
string
The unique identifier of the updated candidate
​
status
string
The new pipeline status of the candidate
{
  "success": true,
  "id": "8fc4ea3c-ecc4-4a92-96fd-a14436a79a1b",
  "status": "rejected"
}

​
Error Responses

​
400 Bad Request

{
  "success": false,
  "error": "candidate_id is required and must be a UUID"
}

{
  "success": false,
  "error": "status is required"
}

{
  "success": false,
  "error": "status must be one of: applied, screening, phone_screen, interview, technical, offer, hired, rejected, withdrawn, on_hold, shortlisted, qualified, uploaded"
}

​
401 Unauthorized

{
  "success": false,
  "error": "Invalid token"
}

{
  "success": false,
  "error": "Invalid candidate id"
}