All write operations are handled asynchronously by the Mutation Engine and follow the same validation and queuing guarantees as candidate creation. This article focuses on updating and deleting existing candidates. Creating candidates and finding them are covered in separate articles.

Start with the /schema endpoint (again)

Before updating a candidate, you should retrieve the schema using the /schema endpoint—this time with operation=update.

GET /schema?operation=update

Update operations differ from create operations:

• All fields are optional

• Patch semantics apply (only provided fields are changed)

• Validation rules still apply to any fields you include

The update schema reflects these differences exactly. Required fields from creation are relaxed, but type constraints, enums, and structure are still enforced.

Updating a candidate by ID

Use PATCH /candidates/{id} to update an existing candidate.

PATCH /candidates/{id}

Key characteristics

• At least one field must be provided

• Only fields present in the payload are updated

• Fields omitted from the request remain unchanged

• Validation happens before the mutation is queued

• Processing is asynchronous via the Mutation Engine

This endpoint is intended for:

• Updating candidate details

• Changing phase or preferences

• Correcting or enriching existing data

Update semantics and constraints

Patch behavior

The update endpoint uses patch semantics:

• Arrays are replaced, not merged

• Scalar values overwrite existing values

• Sending null explicitly clears a nullable field

You should always construct update payloads deliberately and only include fields you intend to change.

Custom fields

Patching custom field values is not supported. You cannot change the values of custom fields via the API after a record has been created. We plan to address this limitation in the next major release.

Archiving vs deleting

There are two ways to remove a candidate, with very different consequences.

Archive a candidate

POST /candidates/{id}/archive

Archiving anonymizes the candidate record, makes it permanently unretrievable, and preserves the integrity of historical reporting.

If a callbackUrl is provided, the candidate record before archival is sent to your callback endpoint.

Delete a candidate

DELETE /candidates/{id}

Deleting permanently removes the candidate record, excludes it from historical reporting, and cannot be undone.

This endpoint should only be used in exceptional cases, such as test data or invalid data cleanup.

Sandbox Support

All candidate update endpoints support sandbox mode via:

• The x-api-sandbox: true header, or

• The /sandbox endpoint prefix

This allows you to test the candidate update flows without affecting production data.