Skip to main content
POST
Create or Update Candidate

Create or Update Candidate

Create a new candidate or update an existing one. Supports form element data, OG variable updates, document uploads, and stage transitions.

Endpoint

Authentication

[!NOTE] Requires a valid company API key in the Authorization header (format: Api-Key <key>).

Request Body

Send as multipart/form-data to support file uploads alongside data fields. Identification (at least one required): Candidate data: Form element data: Any key that is a valid form element ID will be treated as a form element update. The value can be a string or a file upload. OG variable paths: Keys containing two or more dots (e.g., namespace.category.variable) are treated as OG variable paths. Only updatable variables are accepted.

Example Request

Responses

200: OK

Synchronous success. All form elements processed (including OCR), application status updated, and automations triggered.

202: Accepted

Async accepted. Documents uploaded but OCR, status updates, and automations run asynchronously. Returned when requires_async_processing is enabled.

400: Bad Request

Missing identification fields, invalid flow ID, invalid file type, or form element validation failure.

404: Not Found

Application not found for the given application_id and company.

500: Internal Server Error

Failed to create/retrieve the candidate or error updating the application status.