For AI agents: the documentation index is at /llms.txt and a Markdown version of this page is at /de/truthscan-ai-capture-api-documentation.md.
TruthScan Capture-API
Erstellen Sie einen Capture-Link für das Telefon, erhalten Sie ein signiertes Foto und lesen Sie das Ergebnis mit Ihrem API-Schlüssel.
Authentifizierung
Erstellen Sie einen geheimen Schlüssel in Ihrem Konto.
Senden Sie ihn bei jedem Aufruf als Header x-api-key oder als Authorization: Bearer. Der Schlüssel muss zu einer Organisation mit API-Zugang gehören. Der Link auf dem Telefon verwendet diesen Schlüssel nicht.
Ersetzen Sie YOUR_API_KEY durch Ihren geheimen Schlüssel.
Sitzung erstellen
Liefert einen Capture-Link. inviteeEmail ist erforderlich. expiresInSeconds ist standardmäßig 15 Minuten und höchstens 7 Tage. maxCaptures ist standardmäßig 20 und höchstens 20. webhookUrl ist optional. Gesetzt muss sie https sein und auf eine öffentliche Adresse zeigen. webhookSecret steht nur in dieser Antwort. instructions ist optional: eine Begrüßung und Anforderungen, jeweils erforderlich oder nicht. Das Telefon listet sie auf. Ein Tipp öffnet die Kamera für dieses Foto. Eine erforderliche Anforderung braucht ein eingereichtes Foto. Eine optionale kann übersprungen werden. instructions.success ist optional und erscheint nach Fertig. Gespeicherte Foto-Schritte liegen unter /api/capture/templates und nutzen denselben API-Schlüssel. Diese Anfrage nimmt keine template id; senden Sie die Schritte in instructions.
POST /api/capture/session/createSetzen Sie sendEmail auf true, damit TruthScan den Link per E-Mail sendet. Dann sind subject und message erforderlich. Setzen Sie {link} in die Nachricht, wo die Capture-URL erscheinen soll. emailSent ist nur true, wenn diese E-Mail gesendet wurde. Sonst senden Sie captureLink selbst.
Speichern Sie webhookSecret. Er ist der HMAC-Schlüssel für capture.completed.
Beispielanfrage
curl -X POST https://truthscan.com/api/capture/session/create \
-H 'Content-Type: application/json' \
-H 'x-api-key: YOUR_API_KEY' \
-d '{
"inviteeEmail": "person@example.com",
"expiresInSeconds": 900,
"maxCaptures": 1,
"webhookUrl": "https://example.com/hooks/capture"
}'Beispielantwort
{
"sessionId": "11111111-1111-4111-8111-111111111111",
"captureToken": "…",
"captureUrl": "/capture/11111111-1111-4111-8111-111111111111?token=…",
"captureLink": "https://truthscan.com/capture/11111111-1111-4111-8111-111111111111?token=…",
"expiresAt": "2026-10-07T16:00:00.000Z",
"expiresInSeconds": 900,
"maxCaptures": 1,
"challenge": "other_side",
"webhookSecret": "…",
"emailSent": false
}Ergebnisse lesen
Fragen Sie die Sitzung ab, bis capturesUsed steigt, oder warten Sie auf den Webhook. Download-URLs laufen nach einer Stunde ab.
Sitzungsstatus
Ablauf, verbrauchte Aufnahmen und die registrierte Webhook-URL.
GET /api/capture/sessions/{sessionId}Beispielanfrage
curl https://truthscan.com/api/capture/sessions/SESSION_ID \
-H 'x-api-key: YOUR_API_KEY'Beispielantwort
{
"sessionId": "11111111-1111-4111-8111-111111111111",
"expiresAt": "2026-10-07T16:00:00.000Z",
"maxCaptures": 1,
"capturesUsed": 1,
"inviteeEmail": "person@example.com",
"webhookUrl": "https://example.com/hooks/capture",
"createdAt": "2026-10-07T15:45:00.000Z"
}Fotos auflisten
Fotos einer Sitzung, neueste zuerst. Query page und limit (höchstens 50). Jeder Eintrag ist eine Zusammenfassung plus downloadUrl. Der Listenstandort enthält nur Breitengrad, Längengrad und Höhe. Holen Sie das Asset für Genauigkeit, Richtung und Geschwindigkeit.
GET /api/capture/sessions/{sessionId}/assetsBeispielanfrage
curl 'https://truthscan.com/api/capture/sessions/SESSION_ID/assets?page=1&limit=20' \
-H 'x-api-key: YOUR_API_KEY'Beispielantwort
{
"assets": [
{
"id": "22222222-2222-4222-8222-222222222222",
"verificationState": "trusted",
"trustTier": "standard",
"decision": "passed",
"decisionFlags": [],
"risk": { "score": 0.95, "flags": ["geolocation_low_accuracy"] },
"capturedAtUtc": "2026-10-07T15:50:00.000Z",
"submittedAtUtc": "2026-10-07T15:50:01.200Z",
"signedAtUtc": "2026-10-07T15:50:03.000Z",
"captureToSubmitMs": 1200,
"geolocation": {
"latitude": 37.7749,
"longitude": -122.4194,
"altitude": 15,
"altitudeAccuracyMeters": null,
"accuracyMeters": null,
"headingDegrees": null,
"speedMetersPerSecond": null
},
"deviceModel": "iPhone",
"devicePlatform": "iOS",
"inviteeEmail": "person@example.com",
"thumbnailUrl": "https://…",
"downloadUrl": "https://…"
}
],
"pagination": {
"page": 1,
"totalPages": 1,
"total": 1,
"hasPreviousPage": false,
"hasNextPage": false
}
}Ein Foto lesen
Derselbe Datensatz wie die Capture-Detailseite, plus assetUrl für das signierte JPEG. Das Beispiel zeigt die Felder, nach denen Sie verzweigen. device enthält außerdem Bildschirm, Kameraliste, GPU und Eingabe. sensors.geolocation wiederholt das Standortobjekt.
GET /api/capture/assets/{assetId}Beispielanfrage
curl https://truthscan.com/api/capture/assets/ASSET_ID \
-H 'x-api-key: YOUR_API_KEY'Beispielantwort
{
"id": "22222222-2222-4222-8222-222222222222",
"sessionId": "11111111-1111-4111-8111-111111111111",
"verificationState": "trusted",
"trustTier": "standard",
"decision": "review",
"decisionFlags": [{ "code": "device_clock_skew", "class": "contextual" }, { "code": "gps_ip_distance_yellow", "class": "informational" }],
"duplicateOf": null,
"reviewReason": null,
"imageAnalysis": {
"status": "ready",
"verdict": "real",
"labelConfidence": 98.4,
"agreement": "strong",
"screenRecapture": false,
"qualityWarnings": [],
"indicators": [],
"description": "A person holding a driver's license in a doorway.",
"imageTags": ["person", "license", "doorway", "indoor", "document"],
"requestedPhoto": "Front of the driver's license",
"requestCompliance": "pass",
"detectorVersion": null
},
"risk": { "score": 0.95, "flags": ["geolocation_low_accuracy"] },
"inviteeEmail": "person@example.com",
"mimeType": "image/jpeg",
"assetUrl": "https://…",
"thumbnailUrl": null,
"capturedAtUtc": "2026-10-07T15:50:00.000Z",
"submittedAtUtc": "2026-10-07T15:50:01.200Z",
"serverReceivedAtUtc": "2026-10-07T15:50:02.000Z",
"signedAtUtc": "2026-10-07T15:50:03.000Z",
"createdAtUtc": "2026-10-07T15:50:03.100Z",
"captureToSubmitMs": 1200,
"timing": {
"capturedAtUtc": "2026-10-07T15:50:00.000Z",
"submittedAtUtc": "2026-10-07T15:50:01.200Z",
"serverReceivedAtUtc": "2026-10-07T15:50:02.000Z",
"signedAtUtc": "2026-10-07T15:50:03.000Z",
"captureToSubmitMs": 1200
},
"geolocation": {
"latitude": 37.7749,
"longitude": -122.4194,
"altitude": 15,
"altitudeAccuracyMeters": 10,
"accuracyMeters": 12,
"headingDegrees": null,
"speedMetersPerSecond": null
},
"deviceModel": "iPhone",
"devicePlatform": "iOS",
"device": {
"browserName": "Mobile Safari",
"platform": "iOS",
"timezone": "America/Los_Angeles",
"screenWidth": 390,
"screenHeight": 844,
"camera": { "width": 1920, "height": 1080, "facingMode": "environment" },
"connection": { "effectiveType": "4g", "downlinkMbps": 10, "rttMs": 50 },
"network": {
"publicIp": "203.0.113.10",
"publicIpv4": "203.0.113.10",
"ipSource": "cloudflare_visitor",
"browserReportedIpv4": "203.0.113.10",
"ipObservations": [
{ "address": "203.0.113.10", "source": "cloudflare_visitor", "trusted": true },
{ "address": "203.0.113.10", "source": "browser_stun", "trusted": false }
],
"privacy": { "status": "not_detected", "reasons": [] },
"country": "US",
"city": "San Francisco"
}
},
"sensors": {
"gyroVariance": 0.02,
"accelVariance": 0.11,
"motionSampleCount": 24,
"gyroSampleCount": 12,
"accelSampleCount": 12,
"permissionDenied": {
"camera": false,
"geolocation": false,
"motion": false
}
}
}Ergebnisfelder
Entscheiden Sie anhand von decision. verificationState sagt nur, ob die Signatur gültig ist. assetUrl und downloadUrl laufen nach einer Stunde ab.
| Feld | Bedeutung |
|---|---|
| verificationState | Nur die Signatur: trusted, valid_untrusted, invalid oder none. trusted bedeutet, dass TruthScan die Datei signiert hat. |
| decision | passed, review, unable_to_verify oder rejected |
| decisionFlags | Grund der Entscheidung. hard lehnt ab, contextual verlangt Prüfung, unavailable bedeutet eine nicht ausführbare Prüfung und informational dokumentiert Belege ohne Ergebnisänderung. GPS/IP ist unter 50 km grün, von 50–150 km gelb und darüber rot. Gelb und Rot werden als Warnung angezeigt, verlangen für sich allein aber keine Prüfung. Eine nicht katalogisierte Plattform-GPU-Kombination verlangt ebenfalls Prüfung. Unschärfe, Dunkelheit oder geringe Bildqualität verlangt Prüfung. Eine Telefonsuhr, die beim Senden zum Signieren mehr als 5 Minuten von der Serverzeit abweicht, verlangt Prüfung. |
| imageAnalysis | Hinweisende Belege des Bilddetektors. description beschreibt in ein oder zwei Sätzen, was auf dem Foto zu sehen ist, oder ist null, wenn dieser Schritt nicht fertig wird. imageTags enthält bis zu fünf kurze Tags zum selben Foto und ist leer, wenn dieser Schritt nicht fertig wird. requestedPhoto ist der Fotoschritt, für den dieses Bild aufgenommen wurde, oder null, wenn der Link keine Schritte hatte. requestCompliance ist pass, fail oder review für diesen Schritt, oder null, wenn es keinen Schritt gab oder die Prüfung nicht fertig wurde. fail oder review setzt decision auf review, außer decision ist bereits rejected. screenRecapture true verlangt Prüfung und eine Live-Neuaufnahme. verdict und labelConfidence ändern decision im Beobachtungsmodus nicht; die Konfidenz ist eine Modellkonfidenz, keine Betrugswahrscheinlichkeit. |
| trustTier | standard oder high. Kein Echtheitsurteil. |
| risk.score | Sensorvollständigkeit von 0 bis 1. Kein Echtheitswert. |
| risk.flags | camera_permission_denied, geolocation_permission_denied, geolocation_missing, geolocation_low_accuracy, motion_permission_denied, motion_samples_missing, gyro_missing, zero_gyro_variance, accel_missing |
| geolocation | latitude, longitude, altitude, altitudeAccuracyMeters, accuracyMeters, headingDegrees, speedMetersPerSecond |
| device | Browser, Plattform, User-Agent, Zeitzone, Bildschirm, Kamera, Verbindung und Netzwerk. network enthält die ausgewählte öffentliche IP, ihre Quelle, alle validierten Server-, Header- und Browser-IP-Beobachtungen, ASN-Betreiber, groben Standort und die VPN-/Proxy-Bewertung. Ein Datenschutzsignal ist ein Prüfhinweis, kein Beweis. |
| sensors | Gesamt-, Gyroskop- und Beschleunigungssensor-Messzahlen; gyroVariance; accelVariance und permissionDenied für Kamera, Standort und Bewegung |
| timing | Zeiten für Auslöser, Absenden, Serverempfang und Signatur, plus captureToSubmitMs |
Webhook
Nach einer vertrauenswürdigen Aufnahme sendet TruthScan POST capture.completed an webhookUrl. Weiterleitungen werden nicht gefolgt. Der Body enthält keinen genauen Standort. Holen Sie das Asset für den vollständigen Datensatz.
Lesen Sie X-TruthScan-Signature. Das Format ist t=<Unix-Sekunden>,v1=<hex>. Berechnen Sie HMAC-SHA256 über t + "." + den Rohkörper mit webhookSecret und lehnen Sie Zeitstempel ab, die mehr als fünf Minuten abweichen.
Beispiel-Body
{
"id": "…",
"type": "capture.completed",
"data": {
"sessionId": "11111111-1111-4111-8111-111111111111",
"assetId": "22222222-2222-4222-8222-222222222222",
"verificationState": "trusted",
"trustTier": "standard",
"decision": "review",
"flags": ["device_clock_skew", "gps_ip_distance_yellow"],
"imageAnalysis": {
"status": "ready",
"verdict": "real",
"labelConfidence": 98.4,
"agreement": "strong",
"screenRecapture": false,
"qualityWarnings": [],
"indicators": [],
"description": "A person holding a driver's license in a doorway.",
"imageTags": ["person", "license", "doorway", "indoor", "document"],
"requestedPhoto": "Front of the driver's license",
"requestCompliance": "pass",
"detectorVersion": null
},
"capturedAtUtc": "2026-10-07T15:50:00.000Z"
}
}Ratenlimits
Limits gelten über alle Instanzen. Eine 429 enthält Retry-After in Sekunden.
Limits
Jeder Aufruf zählt als eine Anfrage gegen die IP und gegen die Organisation.
| Pfad | Bucket | Limit |
|---|---|---|
| Erstellen und lesen | IP | 600 / Minute |
| Erstellen und lesen | Organisation | 2.000 / Minute |
| Telefon-Capture | IP | 60 / Minute |
| Telefon-Capture | Organisation | 2.000 / Minute |
Erstellen und lesen umfasst POST /api/capture/session/create und die drei GET-Ergebnisrouten. Telefon-Capture umfasst Nonce, upload-url und Signatur. Das Telefon sendet Ihren API-Schlüssel nicht. Organisationen in der kostenlosen Testphase liegen darunter: 120 Erstellen-und-lesen-Anfragen pro Minute pro IP und 300 pro Organisation, sowie 60 Telefon-Anfragen pro Minute pro IP und 300 pro Organisation. Einladungs-E-Mails sind auf 30 pro Stunde und 150 pro Tag begrenzt. Dieses Limit antwortet mit 429 und dem Code INVITE_EMAIL_LIMIT.
Gedrosselte Antwort
Warten Sie Retry-After und senden Sie die Anfrage erneut.
HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json
{
"error": "Rate limit exceeded",
"code": "RATE_LIMIT_EXCEEDED",
"retryAfter": 12
}Was zu lesen ist
- Retry-After: Sekunden bis das Fenster zurückgesetzt wird
- retryAfter: derselbe Wert im JSON-Body
Empfehlungen
- Fragen Sie den Sitzungsstatus ab, statt Assets in einer engen Schleife zu listen.
- Nutzen Sie den Webhook, wenn Sie HTTPS-Callbacks empfangen können.
Fehler
Fehlgeschlagene Aufrufe liefern JSON mit error und code.
401 und 403 bedeuten, dass der Schlüssel nicht verwendbar ist. 404 bedeutet, dass Sitzung oder Asset nicht in Ihrer Organisation liegt.
| Code | Bedeutung |
|---|---|
| MISSING_API_KEY | Kein x-api-key und kein Bearer-Token |
| INVALID_API_KEY | Schlüssel unbekannt, inaktiv oder ohne Organisation |
| ORG_NO_API_ACCESS | API-Zugang der Organisation ist aus |
| INVITEE_EMAIL_REQUIRED | inviteeEmail fehlte |
| INVITEE_EMAIL_INVALID | inviteeEmail ist keine gültige Adresse |
| INVITE_MESSAGE_REQUIRED | sendEmail ist true und message fehlt oder ist zu lang |
| INVITE_SUBJECT_REQUIRED | sendEmail ist true und subject fehlt |
| WEBHOOK_URL_REJECTED | webhookUrl ist kein öffentliches https |
| SESSION_NOT_FOUND | Keine Sitzung mit dieser id in Ihrer Organisation |
| ASSET_NOT_FOUND | Kein Asset mit dieser id in Ihrer Organisation |
| RATE_LIMIT_EXCEEDED | Zu viele Anfragen im aktuellen Fenster |
| INVITE_EMAIL_LIMIT | Limit für Einladungs-E-Mails in der kostenlosen Testphase. Der Body enthält limit, window (hour oder day) und retryAfter |
Häufige Fragen
Wie die Capture-API in Ihr Backend passt.



