Update a candidate by external ID (Beta)

Partially updates an existing candidate profile, addressed by the caller's own identifier rather than Popp's. Behaves exactly like PATCH /v1/candidates/{id}: send only the fields you want to change — omitting a field leaves the stored value alone, while sending null clears it — and the endpoint never creates. An externalId with no candidate in the caller's organization group returns 404, so a mistyped identifier cannot silently produce a new candidate (use POST /v1/candidates to create or upsert). Organization context is taken from the authenticated API key, never from the body. A supplied documentUrl or documentBase64 is downloaded during the request, so a failed fetch surfaces as a 502. documentUrl is fetched with the organization group's stored credential when one is registered and unauthenticated when it is not, so a presigned or public URL works; the destination must be an https URL resolving to a public address and is not followed through redirects, and one that is refused is a 400 rather than a 502. CV parsing and vectorization always continue asynchronously afterwards, so a 200 means the fields are stored, never that the CV has been parsed or indexed.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required

The caller-supplied identifier the candidate was created with.

Body Params

The fields to change

Payload for partially updating an existing candidate profile. Omitting a field leaves the stored value unchanged; sending null clears it. Organization context is taken from the authenticated API key, never from the body. There is no SYNC/ASYNC choice: a supplied document is downloaded during the request (a failed fetch is a 502), while CV parsing and vectorization remain asynchronous — a 200 means the fields are stored, never that the CV has been parsed or indexed.

string | null

Candidate's first name. Null clears the stored value.

string | null

Candidate's last name. Null clears the stored value.

string | null

Candidate's email address. Null clears the stored value.

string | null

Candidate's phone number. Null clears the stored value, but note a later CV parse can repopulate it: the phone number is filled from the CV when empty.

string | null

URL of the candidate's LinkedIn profile. Null clears the stored value.

string | null

Candidate's current job title. Null clears the stored value.

string | null

Candidate's current company. Null clears the stored value.

string | null

The caller's link back to this candidate in their own system. This is not the candidate's own profile page — use linkedInProfileUrl for that. Null clears the stored value.

customFields
object

Values for the custom fields your organization has defined, keyed by fieldKey. Applied per key over what is already stored, so keys you do not send keep their value. Each key must name a live custom field and each value must match the type configured for it, or the request is rejected.

location
object | null

Candidate's location. The object replaces the stored location wholesale; null clears it. Coordinates are derived by Popp during processing and are not accepted here. When name is omitted it is composed from the other parts. At least one of name, city, region or countryCode must carry a value: an object with none of them, or only blank ones, is rejected — send null to clear the stored location.

skills
object

Candidate skills, with how they combine with values extracted from the CV during processing.

qualifications
object

Candidate qualifications, with how they combine with values extracted from the CV during processing.

tags
array of strings

Candidate tags. These always replace the stored tags — nothing derives tags from a CV, so there is no combine mode. Note that a subsequent ATS sync replaces tags wholesale, so tags set here do not survive one.

tags
string

URL of a CV/document to fetch (using the organization group's stored document credential) and store against the candidate. Downloaded during the request; a failed fetch is a 502.

string

Inline CV/document as a data URI or raw base64. Takes precedence over documentUrl when both are given. Must be valid base64 (optionally as a data URI); a value that is not is rejected rather than stored as an unreadable document.

integer
0 to 2

Priority band for processing: 0 (most urgent), 1 or 2.

date-time

The change time that orders a priority band (ISO 8601), so processing across the organization group stays correctly ordered.

Responses

Language
Credentials
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json