Role Fit API-Integration

Ideal für

Integrationsablauf

Unterschiede zu Candidate Intelligence

Role Fit teilt Authentifizierung, das client-Objekt, language, eu_compliant, Credits, Ratenlimits, Webhooks und Feedback mit Candidate Intelligence. Die Unterschiede:

• Jede Person wird mit einem job verglichen. Senden Sie eine Stelle für die ganze Anfrage oder eine Stelle pro Person.
• Kein report_type: Role Fit liefert auf allen Kanälen denselben Bericht.
• Batches mit bis zu 50 Personen funktionieren direkt, ohne mode-Feld. Jeder Role-Fit-Aufruf läuft im Hintergrund.
• Idempotency-Key wird beim Erstellen unterstützt.
• Der Bericht ist in snake_case und beschreibt, wie weit die Belege der Person die Anforderungen der Stelle abdecken.
• Ein Lauf kostet 2 Credits pro Person; ein wiederverwendeter Bericht kostet nichts.

Authentifizierung

X-API-Key: ats_your_api_key_here
Content-Type: application/json
Idempotency-Key: 7b1c9e0a-5d2f-4c8e-9a61-0f3b2d8c4e17   (optional, recommended)

Role Fit erstellen

Erstellt pro Person einen asynchronen Role Fit. Die Antwort kommt sofort; der Bericht ist nach etwa einer Minute fertig.

{
  "language": "en",
  "eu_compliant": null,
  "force_refresh": false,
  "client": {
    "id": "client-42",
    "first_name": "Anna",
    "last_name": "Meier",
    "company": "Acme Recruiting"
  },
  "job": {
    "id": "job-481",
    "title": "Senior Backend Engineer",
    "description": "We are hiring a Senior Backend Engineer to own our payments platform: settlement, reconciliation and payouts. 5+ years of Go and PostgreSQL, Kafka in production, payments experience."
  },
  "candidate": {
    "id": "cand-1001",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "cv": "Ada Lovelace. Senior Backend Engineer, Globex AG (2019 to present): built the card settlement service in Go and PostgreSQL...",
    "company": "Globex AG",
    "role": "Senior Backend Engineer",
    "location": "Zurich, Switzerland"
  }
}

Anfragefelder

Felder der obersten Ebene

job

Jede Stelle braucht description oder url. Werden beide gesendet, gilt description.

candidate

id, first_name und last_name sind Pflicht. Alles andere ist optional; cv zählt am meisten.

Batches und Stelle pro Kandidat

Senden Sie candidates statt candidate, um bis zu 50 Personen in einer Anfrage zu vergleichen. Der job der obersten Ebene gilt für alle; eine Person mit eigenem job nutzt stattdessen diesen. So lassen sich alle Bewerbungen einer Stelle, gemischte Stellen und eine Person gegen mehrere Stellen prüfen (Person mit anderer Stelle wiederholen).

{
  "language": "en",
  "client": {
    "id": "client-42",
    "first_name": "Anna",
    "last_name": "Meier",
    "company": "Acme Recruiting"
  },
  "job": {
    "id": "job-481",
    "title": "Senior Backend Engineer",
    "description": "We are hiring a Senior Backend Engineer to own our payments platform..."
  },
  "candidates": [
    {
      "id": "cand-1001",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "cv": "Ada Lovelace. Senior Backend Engineer, Globex AG..."
    },
    {
      "id": "cand-1002",
      "first_name": "Alan",
      "last_name": "Turing",
      "cv": "Alan Turing. Staff Engineer, Hut 8...",
      "job": {
        "id": "job-502",
        "url": "https://careers.acme.example/jobs/502"
      }
    }
  ]
}

Regeln für Batches

• Die ganze Anfrage wird geprüft, bevor etwas startet. Fehlt einer Person die Stelle oder ist eine Stellenseite nicht lesbar, schlägt die Anfrage mit einem Verweis auf jedes Problem fehl; nichts wird angelegt oder berechnet.
• Credits für jeden neuen Lauf werden vorab reserviert. Reicht Ihr Guthaben nicht für den ganzen Batch, liefert die Anfrage 402 und nichts wird angelegt.
• Jede Person verbraucht eine Einheit Ihres Ratenlimits pro Minute.
• Läufe werden pro Workspace in kleinen Gruppen verarbeitet. Einträge warten als queued, bis sie starten.
• Die items der Antwort haben dieselbe Reihenfolge wie candidates.

Idempotente Wiederholungen

Senden Sie einen Idempotency-Key-Header (eine eindeutige Zeichenfolge mit höchstens 255 Zeichen, z. B. eine UUID), um ein Erstellen nach einem Timeout oder Netzwerkfehler sicher zu wiederholen.

• Eine Wiederholung mit demselben Schlüssel und demselben Inhalt liefert die ursprüngliche Antwort mit dem Header Idempotent-Replayed: true. Es wird kein neuer Lauf angelegt und nichts erneut berechnet.
• Derselbe Schlüssel mit anderem Inhalt liefert 422 idempotency-key-reused.
• Eine Wiederholung, während die erste Anfrage noch läuft, liefert 409 idempotency-key-in-progress mit Retry-After.
• Schlüssel werden 24 Stunden gespeichert. Antworten mit 429 oder 5xx werden nicht gespeichert; diese können Sie mit demselben Schlüssel wiederholen.

Antwort beim Erstellen

Ein erfolgreiches Erstellen liefert 202 Accepted. Eine einzelne Person liefert ein Objekt und einen Location-Header; ein Batch liefert items mit einem Objekt pro Person. Jedes Objekt hat eigene credits; credits und plan der obersten Ebene beschreiben die ganze Anfrage.

Antwort-Header

HTTP/1.1 202 Accepted
Location: https://intelligence.tietalent.com/api/v1/role-fits/cmv9r1f2a0000xk0k8m3c2q71
Retry-After: 10
RateLimit-Limit: 300
RateLimit-Remaining: 299
RateLimit-Reset: 60

Eine Person

{
  "id": "cmv9r1f2a0000xk0k8m3c2q71",
  "status": "queued",
  "candidate_id": "cand-1001",
  "job_id": "job-481",
  "created_at": "2026-11-03T10:00:00.000Z",
  "credits": {
    "balance": 412,
    "plan_credits": 400,
    "rollover_credits": 12,
    "charged": 2,
    "cached": false
  },
  "plan": {
    "code": "growth",
    "cycle": "monthly",
    "credits_per_cycle": 5000,
    "requests_per_minute": 300,
    "period_ends_at": "2026-11-30T23:59:59.000Z"
  }
}

Batch (die zweite Person hat einen vorhandenen Bericht wiederverwendet)

{
  "items": [
    {
      "id": "cmv9r1f2a0000xk0k8m3c2q71",
      "status": "queued",
      "candidate_id": "cand-1001",
      "job_id": "job-481",
      "created_at": "2026-11-03T10:00:00.000Z",
      "credits": { "balance": 412, "plan_credits": 400, "rollover_credits": 12, "charged": 2, "cached": false },
      "plan": { "code": "growth", "cycle": "monthly", "credits_per_cycle": 5000, "requests_per_minute": 300, "period_ends_at": "2026-11-30T23:59:59.000Z" }
    },
    {
      "id": "cmv9r1f2b0001xk0k4n7d9p02",
      "status": "completed",
      "candidate_id": "cand-1002",
      "job_id": "job-502",
      "created_at": "2026-11-03T10:00:00.000Z",
      "credits": { "balance": 412, "plan_credits": 400, "rollover_credits": 12, "charged": 0, "cached": true },
      "plan": { "code": "growth", "cycle": "monthly", "credits_per_cycle": 5000, "requests_per_minute": 300, "period_ends_at": "2026-11-30T23:59:59.000Z" }
    }
  ],
  "credits": {
    "balance": 412,
    "plan_credits": 400,
    "rollover_credits": 12,
    "charged": 2,
    "cached": false
  },
  "plan": {
    "code": "growth",
    "cycle": "monthly",
    "credits_per_cycle": 5000,
    "requests_per_minute": 300,
    "period_ends_at": "2026-11-30T23:59:59.000Z"
  }
}

credits.balance ist Ihr Restguthaben; charged ist, was dieser Lauf reserviert oder berechnet hat; credits.cached ist true, wenn ein Bericht kostenlos wiederverwendet wurde. plan beschreibt Ihren aktuellen Plan. Beide Objekte sind Zusatzfelder und können ignoriert werden.

Role Fit abrufen

Rufen Sie GET /api/v1/role-fits/{id} auf, um den Fortschritt zu prüfen und den Bericht zu lesen. Solange der Lauf queued oder processing ist, enthält die Antwort einen Retry-After-Header.

Werte von status

Während der Lauf läuft

{
  "id": "cmv9r1f2a0000xk0k8m3c2q71",
  "status": "processing",
  "candidate_id": "cand-1001",
  "job_id": "job-481",
  "created_at": "2026-11-03T10:00:00.000Z",
  "updated_at": "2026-11-03T10:00:14.000Z",
  "completed_at": null,
  "report": null,
  "metadata": null,
  "error": null,
  "credits": {
    "balance": 412,
    "plan_credits": 400,
    "rollover_credits": 12,
    "charged": 2,
    "cached": false
  },
  "plan": {
    "code": "growth",
    "cycle": "monthly",
    "credits_per_cycle": 5000,
    "requests_per_minute": 300,
    "period_ends_at": "2026-11-30T23:59:59.000Z"
  }
}

Lauf abgeschlossen (Standard-Bericht)

{
  "id": "cmv9r1f2a0000xk0k8m3c2q71",
  "status": "completed",
  "candidate_id": "cand-1001",
  "job_id": "job-481",
  "created_at": "2026-11-03T10:00:00.000Z",
  "updated_at": "2026-11-03T10:00:52.000Z",
  "completed_at": "2026-11-03T10:00:52.000Z",
  "report": {
    "candidate_name": "Ada Lovelace",
    "target_role": "Senior Backend Engineer",
    "match": { "score": 81, "level": "good_fit" },
    "recommendation": {
      "decision": "Go with validation",
      "reasoning": "Five years of payments backend work in Go covers the core requirements; Kafka in production is not shown in the CV."
    },
    "summary": "Strong overlap on Go, PostgreSQL and the payments domain. Kafka experience and team leadership could not be verified.",
    "alignment": {
      "strong_matches": ["5 years building payment services in Go and PostgreSQL"],
      "partial_matches": ["Event streaming with RabbitMQ; the role uses Kafka"],
      "gaps": ["No team leadership shown; the role leads three engineers"]
    },
    "seniority": {
      "candidate_level": "Senior",
      "role_level": "Senior",
      "gap_analysis": "Scope and ownership match the senior level the role asks for."
    },
    "experience": {
      "relevant": ["PCI-DSS compliant service design"],
      "not_shown_in_cv": ["Kafka in production"],
      "transferable": ["RabbitMQ event-driven design"]
    },
    "points_to_validate": ["Depth of on-call ownership for the settlement service"],
    "additional_strengths": ["Led a card-tokenisation migration that reduced PCI scope"],
    "open_questions": ["Notice period and current team size"],
    "external_validation": {
      "verified_insights": [],
      "no_data_flags": ["No public code repository found"],
      "impact_on_fit": "No external data changes the picture from the CV."
    },
    "interview_focus": ["Walk us through how you scaled the settlement service."]
  },
  "metadata": {
    "language": "en",
    "eu_compliant": false,
    "cv_provided": true,
    "job_source": "description",
    "generated_at": "2026-11-03T10:00:52.000Z",
    "cached": false,
    "cached_at": null,
    "pdf_download_url": "https://intelligence.tietalent.com/api/ats/reports/cmv9r1f2a0000xk0k8m3c2q71/pdf?t=atsl_...",
    "pdf_download_url_expires_at": "2026-11-04T10:00:52.000Z"
  },
  "error": null,
  "credits": {
    "balance": 412,
    "plan_credits": 400,
    "rollover_credits": 12,
    "charged": 2,
    "cached": false
  },
  "plan": {
    "code": "growth",
    "cycle": "monthly",
    "credits_per_cycle": 5000,
    "requests_per_minute": 300,
    "period_ends_at": "2026-11-30T23:59:59.000Z"
  }
}

Lauf fehlgeschlagen

{
  "id": "cmv9r1f2a0000xk0k8m3c2q71",
  "status": "failed",
  "candidate_id": "cand-1001",
  "job_id": "job-481",
  "report": null,
  "metadata": null,
  "error": {
    "type": "https://intelligence.tietalent.com/errors/internal-error",
    "title": "Role fit failed",
    "status": 500,
    "detail": "The role fit could not be completed. No credits were charged."
  },
  ...
}

metadata.pdf_download_url öffnet den gehosteten Bericht, von dem das PDF heruntergeladen werden kann. Wer den Link hat, kann den Bericht öffnen, bis er 24 Stunden nach Ausstellung abläuft (pdf_download_url_expires_at). Speichern Sie den Link nicht: Speichern Sie die Role-Fit-id und rufen Sie GET auf, wenn eine Recruiterin den Bericht öffnet, um einen gültigen Link zu erhalten.

Antwortfelder

Alle Felder sind immer vorhanden. Listen können leer sein; report und metadata sind null, bis der Lauf abgeschlossen ist.

report

metadata

EU-konform oder Standard

Role Fit bewertet Personen für eine Stelle. Der EU AI Act stuft diese Nutzung als hochriskant ein und verlangt menschliche Aufsicht. Beide Modi dienen nur der Entscheidungsunterstützung: Die Recruiterin oder der Recruiter entscheidet. EU-konforme Berichte gehen weiter, damit das Ergebnis nie als Urteil über die Person erscheint:

"report": {
  "candidate_name": "Ada Lovelace",
  "target_role": "Senior Backend Engineer",
  "match": null,
  "recommendation": {
    "decision": "Go with validation",
    "reasoning": "The CV evidences the Go, PostgreSQL and payments requirements; Kafka in production is not evidenced."
  },
  ...
},
"metadata": {
  "eu_compliant": true,
  ...
}

Empfohlene Anzeigebezeichnungen für recommendation.decision bei EU-konformen Berichten:

// Suggested display labels for EU-compliant reports
const EU_LABELS = {
  "Proceed with confidence": "Requirements well evidenced",
  "Go with validation": "Some points to validate",
  "Requires Validation (Signals flagged)": "Conflicting evidence to review",
  "Requires Validation (Insufficient data)": "Not enough information",
};

Wiederverwendung von Berichten

Ein Bericht wird kostenlos wiederverwendet, wenn Ihr Workspace bereits einen für dieselben Eingaben hat.

• Abgeglichen werden CV-Text (ohne CV die Angaben zur Person), Stellentext, Konformitätsmodus und Sprache. Berichte werden sechs Monate lang wiederverwendet.
• Ein wiederverwendeter Lauf ist sofort beim Erstellen completed, mit credits.charged: 0 und metadata.cached: true.
• Jede Anfrage erhält trotzdem eine eigene id mit Ihrer candidate_id und job_id.
• force_refresh: true erstellt immer einen neuen Bericht.

Role Fit abbrechen

DELETE /api/v1/role-fits/{id} stoppt einen Lauf im Status queued oder processing und erstattet seine Credits. Die Antwort enthält den Role Fit mit status: canceled. Ein bereits abgeschlossener Lauf wird unverändert zurückgegeben.

200 OK: die Role-Fit-Ressource mit "status": "canceled"

Feedback

Senden Sie die Bewertung eines abgeschlossenen Berichts durch eine Recruiterin (1 bis 5, mit optionalem Text und Tags). Erneutes Senden für dieselbe client.id und denselben Role Fit aktualisiert das Feedback. Derselbe Vertrag wie beim Feedback von Candidate Intelligence.

{
  "client": {
    "id": "client-42",
    "first_name": "Anna",
    "last_name": "Meier",
    "company": "Acme Recruiting"
  },
  "rating": 4,
  "feedback": "Spot on for seniority.",
  "tags": []
}

{
  "role_fit_id": "cmv9r1f2a0000xk0k8m3c2q71",
  "rating": 4,
  "feedback": "Spot on for seniority.",
  "tags": [],
  "updated_at": "2026-11-03T10:05:00.000Z"
}

Aufzählungen

Jede Aufzählung kann neue Werte erhalten. Behandeln Sie einen unbekannten Wert wie seinen vorsichtigsten Nachbarn, nicht als Fehler.

Fehler

Antworten ausserhalb von 2xx verwenden application/problem+json (RFC 9457). Werten Sie status und den letzten Teil von type aus. Validierungsfehler enthalten zusätzlich ein errors-Array mit einem JSON-Pointer auf jedes Problem.

Beispiel: eine Person ohne Stelle

{
  "type": "https://intelligence.tietalent.com/errors/invalid-body",
  "title": "Invalid request body",
  "status": 400,
  "detail": "Provide job, or a job on this candidate.",
  "errors": [
    { "pointer": "/candidates/1/job", "detail": "Provide job, or a job on this candidate." }
  ]
}

Beispiel: eine nicht lesbare Stellenseite

{
  "type": "https://intelligence.tietalent.com/errors/invalid-job",
  "title": "Invalid job",
  "status": 422,
  "detail": "A job page could not be read. Send the job description as text, or a public https link that does not need a login.",
  "errors": [
    { "pointer": "/candidates/1/job/url", "code": "job_unreadable" }
  ]
}

Ratenlimits und Versionierung

Ratenlimits

Ihr Plan legt fest, wie schnell Sie die API aufrufen dürfen, in Anfragen pro Minute: Free 10, Starter 60, Growth 300; Custom-Pläne werden mit Ihnen vereinbart. Ein Batch verbraucht eine Einheit pro Person, und alle TieTalent-APIs teilen dasselbe Kontingent. Antworten enthalten RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset; ein 429 enthält zusätzlich Retry-After in Sekunden. Credits sind getrennt: Sie messen, wie viel Sie verbrauchen, nicht wie schnell.

Retry-After: 42

Versionierung

Die Version steht im Pfad (/v1). Neue Antwortfelder und neue Aufzählungswerte können ohne Versionswechsel hinzukommen.

Webhooks

Statt abzufragen, erhalten Sie eine signierte Benachrichtigung, sobald ein Role Fit fertig ist. Die Zustellung erfolgt mindestens einmal: Deduplizieren Sie über die id des Ereignisses. GET /api/v1/role-fits/{id} bleibt die verbindliche Quelle.

Ereignistypen

Signaturprüfung

Jede Zustellung enthält einen X-CI-Signature-Header: t=<unix>,v1=<hmac-sha256> über "{t}.{raw_body}", signiert mit Ihrem whsec_...-Secret. Prüfen Sie die Signatur und verwerfen Sie Zeitstempel, die älter als fünf Minuten sind.

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

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

Der Inhalt ist nur ein Verweis: role_fit_id, candidate_id, job_id und result_url. Weder Berichtsinhalt noch Personendaten werden per Webhook übertragen; holen Sie den Bericht mit einem authentifizierten GET.

{
  "id": "evt_01JDABC",
  "type": "role_fit_ready",
  "created_at": "2026-11-03T10:00:52.000Z",
  "api_environment": "Production",
  "data": {
    "candidate_id": "cand-1001",
    "status": "completed",
    "result_url": "https://intelligence.tietalent.com/api/v1/role-fits/cmv9r1f2a0000xk0k8m3c2q71",
    "role_fit_id": "cmv9r1f2a0000xk0k8m3c2q71",
    "job_id": "job-481"
  }
}

{
  "id": "evt_01JDABD",
  "type": "role_fit_failed",
  "created_at": "2026-11-03T10:01:30.000Z",
  "api_environment": "Production",
  "data": {
    "candidate_id": "cand-1001",
    "status": "failed",
    "result_url": "https://intelligence.tietalent.com/api/v1/role-fits/cmv9r1f2a0000xk0k8m3c2q71",
    "role_fit_id": "cmv9r1f2a0000xk0k8m3c2q71",
    "job_id": "job-481",
    "error_code": "internal_error"
  }
}

Bekannte Grenzen

Sie offen zu nennen macht den Rest der Dokumentation verlässlich.