Skip to main content

CvdsIngestRequest

JSON body for POST /api/v1/cvds/candidates. Up to 500 candidates per request. corpus_id may be set at the top level (applies to all candidates) and/or per candidate (overrides the top-level value); every candidate must resolve to a corpus_id or the whole batch is rejected (MISSING_CORPUS_ID).

corpus_idstring

Default corpus for every candidate in this batch. A per-candidate corpus_id overrides it. Required unless every candidate carries its own.

Example: acme-eng-pool
candidates object[]required

Possible values: >= 1, <= 500

  • Array [
    • external_idstringrequired

    Your own candidate id. Unique within a corpus — re-ingesting the same external_id upserts the existing candidate.

    Possible values: non-empty

    Example: cand-001
    parsed_cv objectrequired

    The parsed CV as a JSON object (or array). This is the content that gets embedded for semantic search. It is PII and is never returned by the read endpoints — you keep your own copy.

    oneOf
    object
    corpus_idstring

    Per-candidate corpus, overriding the top-level corpus_id. Required if no top-level corpus_id is set.

    Example: acme-eng-pool
    tagsstring[]

    Optional free-form tags stored with the candidate for your own correlation.

    Example: ["batch-2026-q2"]
    upload_idstring

    Optional opaque id of the upload/source batch, stored for your traceability.

    Example: upl_abc123
  • ]
    • CvdsIngestRequest
    {
      "corpus_id": "acme-eng-pool",
      "candidates": [
        {
          "external_id": "cand-001",
          "parsed_cv": {
            "name": "Jane Doe",
            "skills": [
              "Node.js"
            ]
          }
        }
      ]
    }