Candidate Intelligence API Integration

Best fit for

Partner Benefits

Why Integrate Candidate Intelligence?

Give your customers additional context before interviews while creating new value inside your platform.

Integration flow

Performance & Latency

Candidate Intelligence is designed to provide a responsive experience directly within recruiter workflows.

Report reuse logic

Reports are uniquely identified by platform + company + candidate.

Authentication

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

Create analysis

{
  "language": "en",
  "client": {
    "id": "client_company_123",
    "first_name": "Jane",
    "last_name": "Smith",
    "company": "Acme Recruiting"
  },
  "candidate": {
    "id": "candidate_456",
    "first_name": "John",
    "last_name": "Doe",
    "company": "Example Company",
    "location": "London, UK",
    "role": "Software Engineer",
    "cv": "Optional plain-text CV content…"
  }
}

202 Accepted

The Location header points to GET /api/v1/analyses/'{'id'}'. Retry-After: 10 indicates when to poll next.

{
  "id": "cmqp23kgg00067gk0rh6jol5o",
  "status": "queued",
  "candidate_id": "candidate_456",
  "created_at": "2026-06-29T12:00:00.000Z"
}

Polling & progressive results

After POST returns 202 Accepted, poll GET /api/v1/analyses/'{'id'}' with the same X-API-Key header. Use the id from the create response.

While status is queued or processing, each GET response includes Retry-After: 10 — wait at least 10 seconds before your next request.

Stop polling when status is completed, failed, or canceled.

{
  "id": "cmqp23kgg00067gk0rh6jol5o",
  "status": "processing",
  "candidate_id": "candidate_456",
  "stage": "enrichment",
  "created_at": "2026-06-29T12:00:00.000Z",
  "updated_at": "2026-06-29T12:00:20.000Z",
  "quick_signal": {
    "level": "Green",
    "reason": "Identity supported by multiple matching signals.",
    "identityConfidence": "Medium"
  },
  "signals": [
    {
      "statement": "Senior engineer at Example Company since 2021.",
      "sourceType": "web",
      "sourceUrl": "https://example.com/…",
      "reliability": "High"
    }
  ],
  "report": null,
  "metadata": null,
  "error": null
}

Fields that populate while processing

Status values

Cancel an analysis

DELETE /api/v1/analyses/'{'id'}' stops a queued or in-progress analysis when a recruiter leaves the candidate profile or dismisses a running report. Use the same X-API-Key header as POST and GET.

If the analysis is already completed, failed, or canceled, the endpoint returns the current resource unchanged — no additional charge or side effects.

// No request body — include X-API-Key header only

200 OK

Returns the analysis resource with status canceled. Partial quick_signal or signals may be present if cancellation happened mid-pipeline. Stop polling once status is canceled.

{
  "id": "cmqp23kgg00067gk0rh6jol5o",
  "status": "canceled",
  "candidate_id": "candidate_456",
  "stage": "enrichment",
  "created_at": "2026-06-29T12:00:00.000Z",
  "updated_at": "2026-06-29T12:00:25.000Z",
  "quick_signal": null,
  "signals": [],
  "report": null,
  "metadata": null,
  "error": null
}

Completed analysis

Returned when status is completed.

{
  "id": "clx_analysis_id",
  "status": "completed",
  "candidate_id": "candidate_456",
  "stage": "done",
  "created_at": "2026-06-29T12:00:00.000Z",
  "updated_at": "2026-06-29T12:00:45.000Z",
  "quick_signal": {
    "level": "Green",
    "reason": "Identity supported by multiple matching signals.",
    "identityConfidence": "Medium"
  },
  "signals": [
    {
      "statement": "…",
      "sourceType": "web",
      "reliability": "High"
    }
  ],
  "report": {
    "candidateName": "John Doe",
    "recommendation": {
      "decision": "GO with validation",
      "confidence": "Medium",
      "reason": "…",
      "evidence": ["…"]
    },
    "summary": "…",
    "whatToValidate": ["…"]
  },
  "metadata": {
    "report_id": "clx_analysis_id",
    "candidate_id": "candidate_456",
    "language": "en",
    "generated_at": "2026-06-29T12:00:45.000Z",
    "pdf_download_url": "https://intelligence.tietalent.com/api/ats/reports/{id}/pdf?sig=…"
  },
  "error": null
}

Recommended partner UI

Add a button inside candidate profiles

Add a "Run candidate intelligence report" button within candidate profiles. When clicked, it changes to "Running intelligence report..." while the report generates. Once ready, the report opens automatically and the button becomes "✕ Close report". When closed, the button reverts to "View Intelligence report" to reopen a report you have already stored — without calling POST again.

Privacy & security