Skip to main content
Version: 1.0.0

ZenHire CV DeepSearch API

Search a corpus of parsed CVs for the best-matching candidates against a position. CV DeepSearch is the inverse of CV DeepMatch: instead of scoring one CV against one job, you ingest a corpus of candidates once, then run repeated searches that return the best-first candidates for a given position.

The integration is three steps:

  1. Ingest — batch-upload parsed CVs into a corpus (POST /api/v1/cvds/candidates). Each candidate is embedded for semantic retrieval; you poll the embedding status per candidate.
  2. Search — trigger a search against the corpus for one position (POST /api/v1/cvds/search). Returns a run id; the search runs asynchronously.
  3. Consume — poll the run (GET /api/v1/cvds/runs/{id}) or receive the completion webhook to read the best-first results.

All endpoints require an X-API-Key header. The calling client's permissions[] must contain cvdeepsearch — contact support to enable.

Corpus isolation​

Every candidate and search is scoped to a corpus (corpus_id), which you choose. A search only ever reads candidates in the named corpus, and corpora belonging to other clients are never visible. corpus_id is mandatory on ingest and search; a missing one is rejected (MISSING_CORPUS_ID) rather than silently merged into a default pool.

Webhook callback​

Pass a webhook_url on a search to receive a signed POST when the run finishes (HMAC-SHA256 in the X-CVDM-Signature header, Stripe-style t=<unix-ts>,v1=<hex> — the same scheme as CV DeepMatch). The completion payload shape is finalized alongside the results pipeline; see the Search guide for the current envelope and the verification snippet.

Results side (pending): the per-run results — the best-first candidate list on GET /api/v1/cvds/runs/{id}, the GET /api/v1/cvds/runs/{id}/results pagination endpoint, and the final webhook completion payload — are finalized in a follow-up release. Until then, the run poll returns the run's status with results: null and results_pending: true.

Authentication​

API key issued in the ZenHire dashboard. Format: zh_live_… or zh_test_….

Security Scheme Type:

apiKey

Header parameter name:

X-API-Key