Talent Update API Integration

Best fit for

Integration flow

vs Candidate Intelligence

Talent Update shares authentication, webhooks, and precompute caps with Candidate Intelligence, but targets a different outcome: structured profile enrichment instead of an LLM hiring report.

• No client object: only candidate (or candidates for batch precompute).
• No language, cv, report_type, or eu_compliant fields.
• No cancel endpoint. Runs are short-lived profile lookups, not long SSE analyses.
• Response is structured fields (identity, work_experience, etc.), not a report object or PDF.
• Same X-API-Key header and X-CI-Signature webhook signing as Candidate Intelligence.

Authentication

X-API-Key: ats_your_api_key_here
Content-Type: application/json

Create talent update

Creates an asynchronous talent-update run. The request body accepts identity anchors only: no CV, free-text document, or file upload.

Optional fields such as profile_urls and experience improve resolution accuracy. Send profile URLs whenever you have them.

{
  "candidate": {
    "id": "cand-9911",
    "first_name": "Alex",
    "last_name": "Rivera",
    "work_email": "alex.rivera@example-corp.com",
    "employer_website": "example-corp.com",
    "company": "Example Corp",
    "role": "Software Engineer",
    "location": "London, UK",
    "profile_urls": [
      "https://linkedin.com/in/alex-rivera-example"
    ],
    "experience": [
      {
        "company": "Previous Corp",
        "role": "Engineer",
        "start_date": "2014-01",
        "end_date": "2016-01"
      }
    ]
  }
}

Request fields

candidate (required object)

candidate.id is always required. At least one identity combination below must also be satisfied.

Required combination (at least one)

Optional top-level fields

Not accepted

No CV, no free-text document, no file upload on this endpoint.

Field rules

Validation failures return 422 with RFC 9457 application/problem+json. Branch on status and detail; do not parse free-form error text in production.

Precompute updates

Use the same POST /api/v1/talent-updates endpoint with mode: "precompute". Poll and retrieve with the same GET /api/v1/talent-updates/{id} as live runs.

Single-candidate precompute

Send mode: "precompute" with a single candidate object.

{
  "mode": "precompute",
  "force_refresh": false,
  "candidate": {
    "id": "cand-9911",
    "first_name": "Alex",
    "last_name": "Rivera",
    "work_email": "alex.rivera@example-corp.com",
    "employer_website": "example-corp.com"
  }
}

Batch precompute

Send mode: "precompute" with candidates (array) instead of candidate. Provide exactly one of candidate or candidates. Maximum 50 candidates per request.

{
  "mode": "precompute",
  "candidates": [
    {
      "id": "cand-9911",
      "first_name": "Alex",
      "last_name": "Rivera",
      "work_email": "alex.rivera@example-corp.com"
    },
    {
      "id": "cand-9912",
      "first_name": "Jordan",
      "last_name": "Lee",
      "employer_website": "acme.example",
      "role": "Product Manager"
    }
  ]
}

Cache behaviour

• Completed runs for the same partner and candidate fingerprint may be reused within a seven-day window.
• Reused runs return status: completed and cached: true immediately on both live and precompute creates.
• force_refresh: true skips completed-cache reuse (live and precompute). An in-flight run for the same fingerprint is still returned instead of starting a duplicate.

Precompute is capped per partner (1,000 net-new runs per UTC day and 10 concurrent in-flight). Exceeding a cap returns 429 Too Many Requests with error precompute-cap-exceeded and Retry-After. Cache hits do not count toward the daily cap. Live runs are exempt from precompute caps.

Create response

A successful create returns <code>202 Accepted</code>. The response includes a <code>cached</code> boolean. Batch precompute returns an <code>items</code> array with one entry per candidate.

Single-candidate response (new run)

{
  "id": "tu_01JCXY",
  "status": "pending",
  "candidate_id": "cand-9911",
  "created_at": "2026-08-28T12:56:44.642Z",
  "cached": false
}

Single-candidate response (cache hit)

When a completed run exists within the seven-day reuse window and force_refresh is not set, the create response may already be status: completed with cached: true.

{
  "id": "tu_01JCXY",
  "status": "completed",
  "candidate_id": "cand-9911",
  "created_at": "2026-08-28T12:56:44.642Z",
  "cached": true
}

Batch precompute response

{
  "items": [
    {
      "id": "tu_01JCXY",
      "status": "completed",
      "candidate_id": "cand-9911",
      "created_at": "2026-08-28T12:56:44.642Z",
      "cached": true
    },
    {
      "id": "tu_01JCXZ",
      "status": "pending",
      "candidate_id": "cand-9912",
      "created_at": "2026-08-28T12:56:45.102Z",
      "cached": false
    }
  ]
}

Get talent update

Call GET /api/v1/talent-updates/{id} to check progress and retrieve the completed profile.

status values

While status is pending

{
  "id": "tu_01JCXY",
  "status": "pending",
  "candidate_id": "cand-9911",
  "created_at": "2026-08-28T12:56:44.642Z",
  "completed_at": null,
  "error": null,
  "identity": {
    "confidence": null,
    "full_name": null,
    "headline": null,
    "current_employer": null,
    "location": null
  },
  "work_experience": [],
  "education": [],
  "online_presence": []
}

When status is completed

{
  "id": "tu_01JCXY",
  "status": "completed",
  "candidate_id": "cand-9911",
  "created_at": "2026-08-28T12:56:44.642Z",
  "completed_at": "2026-08-28T12:57:26.031Z",
  "error": null,
  "identity": {
    "confidence": "high",
    "full_name": "Alex Rivera",
    "headline": "Software Engineer at Example Corp",
    "current_employer": "Example Corp",
    "location": "London, UK"
  },
  "work_experience": [
    {
      "company": "Example Corp",
      "role": "Software Engineer",
      "start_date": "2016-01",
      "end_date": null,
      "is_current": true,
      "confidence": "high"
    }
  ],
  "education": [
    {
      "institution": "Example University",
      "qualification": "Bachelor of Science",
      "confidence": "high"
    }
  ],
  "online_presence": [
    {
      "platform": "linkedin",
      "url": "https://linkedin.com/in/alex-rivera-example",
      "confidence": "high"
    }
  ]
}

Response fields

Every GET response includes the profile shape (identity, work_experience, education, online_presence). While status is pending, those fields are null or empty arrays; when completed, they hold resolved data.

Timestamps are UTC with a Z. Employment dates are typically YYYY-MM.

Enumerations

Every enum may gain new members. Treat an unrecognised value as its safest neighbour, not as an error.

Errors

Non-2xx responses use application/problem+json (RFC 9457). Branch on status and stable error codes where present.

Example problem response

{
  "type": "https://intelligence.tietalent.com/errors/invalid-request",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "work_email must be a corporate address, not a personal mailbox."
}

Rate limits & versioning

Rate limits

Requests are rate-limited per IP and per partner. 429 responses include Retry-After (seconds). Back off exponentially with jitter.

Retry-After: 42

Versioning

The version is in the path (/v1). Additive response fields may appear without a version bump.

Webhooks

Polling is supported but webhooks are preferred when configured. Delivery is at-least-once; handlers must be idempotent on event id. Treat GET /api/v1/talent-updates/{id} as authoritative at all times.

Event types

Signature verification

Every delivery carries an X-CI-Signature header: t=<unix>,v1=<hmac-sha256> over "{t}.{raw_body}", HMAC-SHA256 with your whsec_... secret. Verify the signature and reject timestamps older than five minutes.

X-CI-Signature: t=<unix>,v1=<hmac-sha256>

# Signed over "{t}.{raw_body}". Reject timestamps older than five minutes.

The webhook payload is a thin pointer: result_url, talent_update_id, and candidate_id. Fetch the full profile via authed GET.

api_environment mirrors the label of the API key that authenticated the run (Production, Staging, or Test): the same value shown in your admin API key list.

{
  "id": "evt_01JDABC",
  "type": "talent_update_ready",
  "created_at": "2026-08-28T12:57:26.031Z",
  "api_environment": "Production",
  "data": {
    "candidate_id": "cand-9911",
    "status": "completed",
    "result_url": "https://intelligence.tietalent.com/api/v1/talent-updates/tu_01JCXY",
    "talent_update_id": "tu_01JCXY"
  }
}

{
  "id": "evt_01JDABD",
  "type": "talent_update_failed",
  "created_at": "2026-08-28T12:57:30.031Z",
  "api_environment": "Production",
  "data": {
    "candidate_id": "cand-9911",
    "status": "failed",
    "result_url": "https://intelligence.tietalent.com/api/v1/talent-updates/tu_01JCXY",
    "talent_update_id": "tu_01JCXY",
    "error_code": "internal_error"
  }
}

Known limits

Publishing these limits is what makes the numbers trustworthy.