Contents

v1 · Beta

Partner API

Candidate Intelligence API Integration

Give recruiters more confidence before interviews

Run Candidate Intelligence reports directly inside your ATS to verify candidate information, surface unexpected signals, and generate interview questions in seconds.

Request API Access

Best fit for

Applicant Tracking Systems (ATS)

Recruitment CRMs

Job Boards

Internal Talent Platforms

Executive Search Firms

HR Tech Vendors

Partner Benefits

Why Integrate Candidate Intelligence?

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

📈

Increase Recruiter Engagement

Keep recruiters inside your ATS by providing candidate verification, interview preparation, and additional hiring insights directly within candidate profiles.

💰

Create a New Revenue Stream

Offer Candidate Intelligence reports to your customers and earn recurring revenue through the partner program.

⭐

Differentiate Your Platform

Stand out from competing ATS and recruitment solutions with built-in Candidate Intelligence capabilities.

🔍

No Additional Research Required

Help recruiters uncover relevant information beyond the CV without leaving their workflow.

🎯

Improve Hiring Quality

Help recruiters and hiring managers make more informed decisions by providing additional context beyond the CV, highlighting verified findings, surfacing potential risks, and identifying areas that require further validation.

⚡

Fast Integration

Typical implementation requires only a few API endpoints and can be completed in less than a day.

Integration flow

Get approved and receive an API key

Request access from TieTalent. Once approved, you receive an API key (prefix ats_) for your integration.

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 generated.

Call the TieTalent API when clicked

POST to /api/v1/analyses with the candidate, client (recruiter), and language. Use your own external IDs on client.id and candidate.id.

TieTalent generates the report

The analysis runs in the background. Poll GET /api/v1/analyses/'{'id'}' using the returned id — wait at least 10 seconds between requests while status is queued or processing (see Retry-After response header). Call DELETE on the same path to cancel if the recruiter leaves the profile.

Display the report in the candidate profile

Render the report JSON in your own UI (see Report object reference), or open the full hosted report via the signed link in metadata.pdf_download_url — the hosted view also offers the PDF export.

Performance & Latency

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

Action

Typical Response Time

Existing report found

< 1 second

New report generation

30–60 seconds

Report reuse logic

Reports are uniquely identified by platform + company + candidate.

Cache is scoped per recruiter: your API key identifies the partner integration, and client.id identifies the recruiter (user) within your platform. Different client.id values do not share cache, even under the same API key.

Same client company + same candidate → existing report returned instantly, no charge

Different client company + same candidate → new report generated and billed separately

Same client company + different candidate → new report generated and billed

Cache key fields

candidate.idYour external candidate ID

candidate.first_name + candidate.last_nameCandidate name (normalized)

candidate.companyCurrent company (normalized)

candidate.locationLocation (normalized)

candidate.roleRole or job title (normalized)

Not part of the cache key

candidate.cvOptional CV text — used only on fresh runs. Changing the CV alone does not bust cache.

languageRequested report language. Use force_refresh: true when you need a report in a different language.

Cached reports are reused for up to 6 months. Completed analyses older than that are not returned from cache.

Force refresh

Set force_refresh: true on POST /api/v1/analyses to skip the cache lookup and run the full analysis pipeline — enrichment, live signals, and LLM report generation.

Omit force_refresh or set it to false to allow cache reuse (default).

When to set force_refresh: true

The recruiter explicitly requests updated or refreshed intelligence

Only the CV text changed while profile fields stayed the same

You need a report in a different language than a prior cached run

You want live signals and enrichment re-run regardless of cache

Fresh analysis request

{
  "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"
  },
  "force_refresh": true
}

Authentication

Approval required: API keys are issued only to approved partner platforms. Include your key on every request; never expose it in client-side code or public repositories.

HTTP headers

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

Create analysis

Optional body fields: candidate.cv (plain-text CV, used only on fresh runs) and force_refresh (boolean, default false — see Force refresh).

POST/api/v1/analyses

{
  "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…"
  },
  "force_refresh": false
}

force_refresh (optional, default false) skips report reuse and always generates a fresh report — the new report is billed. Omit it unless the recruiter explicitly requests a refresh.

202 Accepted

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

202 Accepted

{
  "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.

GET/api/v1/analyses/'{'id'}'

{
  "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

quick_signalPreliminary identity signal (Green, Orange, or Red) with a short reason — available once enrichment begins.

signalsLive web signals discovered during enrichment. The array grows as external searches complete.

stageCurrent pipeline stage: identity → enrichment → report → done.

reportFull Candidate Intelligence report — populated only when status is completed.

metadataReport metadata — populated only when status is completed. Includes the signed hosted-report link (pdf_download_url) and the cached / cached_at reuse flags.

Status values

queuedAccepted and waiting to start.

processingIn progress — poll for quick_signal, signals, and stage updates.

completedReport ready — report and metadata are populated.

failedAnalysis failed — error is populated.

canceledAnalysis was canceled via DELETE /api/v1/analyses/'{'id'}' or reached a terminal cancel state.

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.

DELETE/api/v1/analyses/'{'id'}'

// 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.

200 OK

{
  "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. The report below is abridged — see the Report object reference for the full field list.

Fresh report (metadata.cached: false)

JSON200 OK

{
  "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",
      "sourceUrl": "https://example.com/…",
      "reliability": "High"
    }
  ],
  "report": {
    "candidateName": "John Doe",
    "profileHeadline": "Software Engineer",
    "profileCompany": "Example Company",
    "profileLocation": "London, UK",
    "identity": {
      "status": "Confirmed",
      "confidence": "High",
      "confidenceReason": "…",
      "risk": { "level": "Low", "reason": "…" }
    },
    "sourcesCheckedCount": 24,
    "recommendation": {
      "decision": "Go with validation",
      "confidence": "Medium",
      "confidenceNote": "Identity verified · signals consistent",
      "reason": "…",
      "evidence": ["…"],
      "nextStepPills": [
        { "variant": "confirmed", "label": "Role and tenure verified" },
        { "variant": "validate", "label": "Validate team leadership scope" }
      ]
    },
    "summary": "…",
    "externalProfileSummary": "…",
    "externalProfileTags": [
      { "kind": "catalog", "id": "linkedin_verified" },
      { "kind": "catalog", "id": "signals_highly_consistent" },
      { "kind": "custom", "group": "source_presence", "label": "Open-source contributor" }
    ],
    "strengths": ["…"],
    "signals": {
      "verified": [
        {
          "statement": "…",
          "sourceType": "web",
          "sourceReference": "…",
          "reliability": "High"
        }
      ],
      "weak": [],
      "unverifiedClaims": [],
      "noSignificantExternalData": false
    },
    "highImpactFindings": [
      {
        "type": "Career",
        "title": "…",
        "summary": "…",
        "evidenceBadge": "validate",
        "confidence": "Medium",
        "polarity": "Concern"
      }
    ],
    "topDecisionDrivers": ["…"],
    "expectationGap": {
      "expectedSignals": ["…"],
      "missingOrWeaker": ["…"],
      "assessment": "…"
    },
    "impactAssessment": {
      "summary": "…",
      "riskLevel": "Low",
      "overallRiskLabel": "Low validation needed",
      "implications": ["…"]
    },
    "whatToValidate": ["…"],
    "nextStep": {
      "action": "…",
      "focusAreas": ["…"],
      "reasoning": "…"
    },
    "alertLevel": "Green",
    "externalDataConfidence": "Medium"
  },
  "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=…",
    "cached": false,
    "cached_at": null
  },
  "error": null
}

Cached report (metadata.cached: true)

JSON200 OK

{
  "id": "clx_new_analysis_id",
  "status": "completed",
  "candidate_id": "candidate_456",
  "stage": "done",
  "created_at": "2026-07-15T12:00:00.000Z",
  "updated_at": "2026-07-15T12:00:00.500Z",
  "quick_signal": { "…": "…" },
  "signals": [{ "…": "…" }],
  "report": { "…": "…" },
  "metadata": {
    "report_id": "clx_new_analysis_id",
    "candidate_id": "candidate_456",
    "language": "en",
    "generated_at": "2026-07-15T12:00:00.500Z",
    "pdf_download_url": "https://intelligence.tietalent.com/api/ats/reports/{id}/pdf?sig=…",
    "cached": true,
    "cached_at": "2026-07-15T12:00:00.500Z"
  },
  "error": null
}

The metadata object

metadata.pdf_download_url is a signed link that opens the full hosted TieTalent report (the same report design as the web app); the PDF export can be downloaded from that view. Treat the link as confidential — anyone holding it can open the report.

metadata.cached is true when an existing report was reused instead of generating a new one (see Report reuse logic); cached_at then carries the reuse timestamp, otherwise it is null.

Verdicts & compatibility

report.recommendation.decision is the headline verdict of the report. It is always one of the four values below.

recommendation.decision — possible values

"Proceed with confidence"
"Go with validation"
"Requires Validation (Signals flagged)"
"Requires Validation (Insufficient data)"

Map each verdict to one of three UI states:

Suggested mapping (JavaScript)

function toUiState(decision) {
  switch (decision) {
    case "Proceed with confidence":
      return "proceed";
    case "Go with validation":
      return "validation";
    case "Requires Validation (Signals flagged)":
    case "Requires Validation (Insufficient data)":
      return "requires_validation";
    default:
      return "requires_validation";
  }
}

Best practice: switch on the full string with a safe default of requires_validation so any unexpected value degrades gracefully instead of breaking your UI.

Report object reference

report is populated only when status is completed. Field names are camelCase. The structure reflects the current report design used across all TieTalent Intelligence surfaces (web app, extension, and the hosted report).

Forward compatibility: optional fields may be absent and new fields may be added over time. Ignore unknown fields and treat all optional fields as nullable.

Core fields (always present)

candidateNameCandidate name as resolved by the analysis.

identityIdentity resolution — status (Confirmed, Likely, Ambiguous, Unknown), confidence, confidenceReason, and risk (level, reason).

recommendationThe verdict — decision (see Verdicts & compatibility), confidence, reason, evidence[], confidenceNote (short evidence headline), and nextStepPills[] (evidence-state pills with variant and label).

summaryExecutive summary paragraph.

externalProfileSummaryNarrative summary of the candidate's external footprint.

strengthsKey strengths (array of strings).

signalsSignal snapshot — verified[], weak[], unverifiedClaims[], and noSignificantExternalData.

highImpactFindingsDecision-critical findings. Each has type, summary, and confidence, plus optional title, evidenceBadge, polarity, and sourceReference.

topDecisionDriversThe signals that most influenced the verdict (array of strings).

expectationGapExpected vs. found signals — expectedSignals[], missingOrWeaker[], and assessment.

impactAssessmentHiring impact — summary, riskLevel, and implications[], plus optional overallRiskLabel, bestSuited[], and considerCarefully[].

whatToValidateConcrete points to validate in interviews (array of strings).

nextStepSuggested next step — action, focusAreas[], and reasoning.

alertLevelOverall alert level — Green, Yellow, Orange, or Red.

externalDataConfidenceConfidence in the external data behind the report — High, Medium, or Low.

Optional fields

These fields may be absent. Treat them as nullable and ignore any field your UI does not use.

profileHeadline / profileCompany / profileLocationHeader lines for display — role/title, current company, and location.

sourcesCheckedCountNumber of external search results consulted for the report (set by the pipeline).

externalProfileTagsTags describing the candidate's external footprint — see Tags below.

bestFitContext / bestFitTagsBest-fit narrative and tags — see Tags below.

surprisingInsightsInsight cards (title, text, source, notOnCV?).

keyTakeawaysstandsOut[] and needsChecking[] lists of (label, detail) items.

claimsVsSignalsClaim-by-claim check — (claim, confirmed, assessment).

interviewQuestionsSuggested interview questions — (question, hint).

technicalIntelligenceTechnical footprint for technical roles — profileFound, signalStrength, observations[], repositories[], risks[], and impactAssessment.

sensitiveUnverifiedSignalsSensitive signals with an attribution status. Handle with care and never present as established fact.

Submit feedback on a report

POST /api/v1/analyses/'{'id'}'/feedback lets your recruiters rate a completed report — 1 to 5 stars, optional tags, and optional free text — so TieTalent can track report quality on your side of the integration.

The endpoint upserts on client.id plus the report id: submitting again for the same client and report overwrites the previous rating, tags and text — there is no revision history.

POST/api/v1/analyses/'{'id'}'/feedback

{
  "client": {
    "id": "client_company_123",
    "first_name": "Jane",
    "last_name": "Smith",
    "company": "Acme Recruiting"
  },
  "rating": 4,
  "feedback": "Helped me shortlist quickly, would have liked more sourcing links.",
  "tags": ["saved_me_time", "good_signal_quality"]
}

Request fields

clientRequired. Same client object as POST /api/v1/analyses — identifies which of your users is giving feedback.

ratingRequired. Integer from 1 to 5.

feedbackOptional. Free-text comment, up to 2000 characters.

tagsOptional. Up to 5 canonical tag ids from the catalog below — invalid values or an out-of-range rating return a 4xx with a clear message.

Feedback tag catalog

Tags are grouped by rating band and swap depending on the rating you send — render your own UI for these, but submit only the canonical ids so feedback stays analyzable across languages.

Canonical tag ids by rating band

// 1-2 stars
missing_info · something_was_wrong · signals_felt_weak
too_generic · hard_to_trust

// 3 stars
useful_but_missing_detail · right_idea_wrong_emphasis
some_signals_felt_off · wanted_more_sources

// 4-5 stars
saved_me_time · helped_me_decide · good_signal_quality
easy_to_read · trustworthy

200 OK

Returns the stored feedback, echoing back the current rating, tags and text on file for that client and report.

200 OK

{
  "report_id": "cmqp23kgg00067gk0rh6jol5o",
  "rating": 4,
  "feedback": "Helped me shortlist quickly, would have liked more sourcing links.",
  "tags": ["saved_me_time", "good_signal_quality"],
  "updated_at": "2026-07-21T12:00:00.000Z"
}

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.

No report exists

Report generating

Report is open

Report closed / exists

Privacy & security

Reports are decision-support tools only and must not be used as the sole basis for hiring decisions. Human review and independent assessment are always required.

Each partner integration is isolated by API key — you can only access analyses created with your credentials.

Use your client.id and candidate.id to map analyses to records in your ATS.

Optional CV text in the request is used for the analysis and is not stored as a separate document; the generated report (which may reflect CV content) is retained encrypted so it can be served back to your integration.

Data is stored in EU-region infrastructure with encryption at rest.

Candidate Intelligence provides recommendations and validation signals but does not make automated hiring decisions on behalf of users.

Data processing follows the principles of data minimization and purpose limitation.

⚖️ AI Compliance Notice

Candidate Intelligence is designed to support recruiter decision-making, not replace it. Hiring decisions remain the responsibility of the employer and should always include appropriate human review and oversight.

Partner Program

Start integrating Candidate Intelligence

Request access and we will activate your partner API credentials. Integration typically takes less than a day.

Request API Access Contact Partnerships