Create a candidate (Beta)

post

https://api.joinpopp.com/v1/candidates

Creates a candidate profile in the caller's organization, or upserts an existing one when the same externalId is re-posted. Organization context is taken from the authenticated API key, never from the body. mode controls only how much of the work the request waits for — specifically, whether the document is downloaded before responding. In SYNC mode the profile is created and, when documentUrl is supplied, the document is downloaded during the request (201 when newly created, 200 when an existing profile was upserted), so a failed download surfaces as a 502 on this call. In ASYNC mode the work is queued and 202 is returned immediately with the resolved candidate id, and the document is downloaded in the background. CV parsing and vectorization are always asynchronous, in both modes: a 2xx means the profile exists — and in SYNC, that the document was fetched — never that the CV has been parsed or indexed. A CV can be attached via documentUrl or inline documentBase64 (SYNC only). documentUrl is fetched server-side: the organization group's stored credential is sent when one is registered, and the URL is fetched unauthenticated when it is not, so a presigned or otherwise public URL works without any credential being set up. The destination must be an https URL resolving to a public address and is not followed through redirects; one that is refused is a 400, not a 502, because retrying cannot help.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Candidate payload

Payload for creating (or upserting) a candidate profile. The organization group is always taken from the authenticated API key and can never be set from the body. The organization within that group defaults to the API key's own, and may be chosen with externalOrganizationId, which is authorised against the access of the user the key belongs to.

mode

string

enum

required

Controls how much of the work the request waits for — specifically whether the document is downloaded before responding. SYNC creates/upserts the profile and downloads the document (when documentUrl is supplied) during the request, returning 201 when newly created or 200 when an existing profile was upserted; a failed download surfaces as a 502. ASYNC queues the work and returns 202 immediately with the resolved id, downloading the document in the background. CV parsing and vectorization are always asynchronous in both modes. documentBase64 is not supported in ASYNC mode.

Allowed:

externalId

string

length ≥ 1

Caller-supplied identifier (typically matching ^[\w.-]+$). Drives the deterministic candidate profile id and de-duplication; re-posting the same externalId upserts the existing profile. Leading and trailing whitespace is trimmed before the id is derived, so " abc " and "abc" address the same candidate; a value that is empty once trimmed is rejected.

externalOrganizationId

string

length ≥ 1

Your own identifier for the organization this candidate belongs to, used instead of relying on the organization the API key defaults to. Resolved to a Popp organization within your organization group and checked against the access of the user the API key belongs to. For a new candidate it sets the organization the candidate is created in, instead of the organization the API key defaults to. For a candidate that already exists it is additive: the named organization is added to the ones the candidate already has, and none are removed. A candidate cannot be moved between organizations, because its vector-DB tenant follows the organizations it belongs to and a vector cannot be withdrawn from a tenant it has already been indexed into. Unknown or ambiguous values are rejected with a 400, and an organization the user cannot reach with a 403. Leading and trailing whitespace is trimmed before it is matched; a value that is empty once trimmed is rejected.

firstName

string

Candidate's first name.

lastName

string

Candidate's last name.

string

Candidate's email address.

phoneNumber

string

Candidate's phone number.

linkedInProfileUrl

string

URL of the candidate's LinkedIn profile.

title

string

Candidate's current job title.

company

string

Candidate's current company.

externalUrl

string

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.

customFields

object

Values for the custom fields your organization has defined, keyed by fieldKey. Each key must name a live custom field, and each value must match the type configured for it, or the request is rejected. Manage the definitions through the custom-fields endpoints. In SYNC mode an unknown key or a mistyped value is rejected here; in ASYNC mode the request is accepted and the same problem is reported on the candidate processing webhook.

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.

200

201

202

400

401

403

500

502