Create a candidate

post

https://hivemind.hr/api/public/v1/candidates

Creates a candidate and enrols them in the specified pipeline. The
existing pipeline automation fires immediately (first node handler
runs).

Creation does not pre-check credits. Downstream nodes that consume
credits transition the candidate to status: "pending_credits" if
the company's balance is insufficient — same behavior as candidates
submitted through the public application form.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

pipeline_id

uuid

required

string

required

name

string

required

length ≤ 256

resume_url

uri

required

length ≤ 2048

URL the server can fetch — we download and re-upload to our own
bucket. Mutually exclusive with resume; supply one or the other,
never both, never neither.

resume

object

Inline resume payload. The file is base64-encoded in data. Mutually
exclusive with resume_url on a POST /candidates body — provide
one or the other.

name: filename including extension. The extension determines the
stored content type. Allowed: .pdf, .doc, .docx.
data: base64-encoded file bytes. Maximum size after decode: 7MB.

referral_tag

string

length ≤ 256

application_metadata

array of objects | null

Array of { key, answer, question? } triples capturing each
non-core field from the pipeline's application form. The key
values are configured per pipeline — pipeline templates (email,
SMS, assessment) interpolate {key} references by exact match.
Sending a mismatched key (e.g. phone when the pipeline form
uses phonenumber) silently fails to populate that template
variable. Use GET /pipelines/{id} (Phase 3) to discover the
keys a given pipeline expects.

Missing fields don't block creation but may cause downstream
pipeline steps to fail when they try to read the missing key.

application_metadata

Headers

Idempotency-Key

string

^[A-Za-z0-9_-]{8,64}$

Optional. Send the same key on a retry to make the request
idempotent. The first successful 2xx response is cached for
24 hours; subsequent retries with the same key return the
cached response with Idempotent-Replay: true. Reusing a key
with a different request body returns 409
idempotency_conflict. Format: 8–64 chars of [A-Za-z0-9_-]
— a UUID v4 is a fine default.

Responses

201Candidate created.

400Malformed request (validation, bad UUID, unknown filter, etc.).

401Missing, malformed, or invalid API key.

404Pipeline not found or not owned by the caller's company.

409A candidate with the same email already exists in this pipeline. The existing candidate's id is returned in details.candidate_id so the integrator can decide whether to PATCH the existing row or ignore the duplicate.

422Pipeline is not active.

429Rate limit exceeded. Retry after Retry-After seconds.

500Unexpected server-side error. Log the request_id and contact support.