v1

latestOpenAPI 3.1.02026-07-224239180.9 KB

Candidate

Update a candidate

Updates the supplied hiring-team assignments and candidate profile fields. Omitted fields are preserved; nullable team IDs clear their assignment, clear_preferred_email clears only when true, and an empty conflict list removes all listed conflicts. Some writable fields are intentionally write-only because the candidate summary RPC does not return them.

patch/v1/candidates/{candidateId}

Path parameters

candidateIdstring required

a candidate ID. Accepts the canonical prefixed compact UUID, a prefixed dashed UUID, a bare dashed UUID, or a bare compact UUID; input is case-insensitive.

Example:can_a1b2c3d4e5f64789a1b2c3d4e5f64789

Request body

recruiter_idstring nullable

an employee ID. Accepts the canonical prefixed compact UUID, a prefixed dashed UUID, a bare dashed UUID, or a bare compact UUID; input is case-insensitive.

coordinator_idstring nullable

an employee ID. Accepts the canonical prefixed compact UUID, a prefixed dashed UUID, a bare dashed UUID, or a bare compact UUID; input is case-insensitive.

sourcer_idstring nullable

an employee ID. Accepts the canonical prefixed compact UUID, a prefixed dashed UUID, a bare dashed UUID, or a bare compact UUID; input is case-insensitive.

clear_preferred_emailboolean

True clears the preferred email; omit or false preserves it.

timezonestring

Replaces the timezone; omit to preserve.

preferred_phone_numberstring

Replaces the preferred phone number; omit to preserve. Write-only.

localestring

Replaces the locale; omit to preserve. Write-only.

conflict_of_interest_employee_idsstring[]

Replaces the full conflict-of-interest list; an empty array clears it and omission preserves it. Write-only.

Example request

{
  "recruiter_id": "emp_a1b2c3d4e5f64789a1b2c3d4e5f64789",
  "coordinator_id": "emp_a1b2c3d4e5f64789a1b2c3d4e5f64789",
  "sourcer_id": "emp_a1b2c3d4e5f64789a1b2c3d4e5f64789",
  "conflict_of_interest_employee_ids": [
    "emp_a1b2c3d4e5f64789a1b2c3d4e5f64789"
  ]
}

Response

Success

idstring required

Canonical candidate ID (can_ followed by 32 lowercase hexadecimal UUID characters).

primary_emailstring email nullable required

additional_emailsstring[] nullable required

Additional candidate email addresses. Null means PII was redacted because the candidate is anonymized; an empty array means no additional email addresses.

phone_numbersstring[] nullable required

Candidate phone numbers. Null means PII was redacted because the candidate is anonymized; an empty array means no phone numbers.

timezonestring nullable required

linkedin_urlstring uri nullable required

preferred_namestring nullable required

anonymizedboolean required

created_atstring date-time required

ISO 8601 timestamp.

updated_atstring date-time required

ISO 8601 timestamp.

app_urlstring uri required

Example response

{
  "id": "can_a1b2c3d4e5f64789a1b2c3d4e5f64789",
  "recruiter": {
    "id": "emp_a1b2c3d4e5f64789a1b2c3d4e5f64789"
  },
  "coordinator": {
    "id": "emp_a1b2c3d4e5f64789a1b2c3d4e5f64789"
  }
}