> Erstellen Sie eine TruthScan-Capture-Sitzung, erhalten Sie einen Webhook zum signierten Foto und lesen Sie Ergebnisse mit Ihrem API-Schlüssel.

Source: https://truthscan.com/de/truthscan-ai-capture-api-documentation
Documentation index: https://truthscan.com/llms.txt
Plans and pricing: https://truthscan.com/pricing

For AI agents: the documentation index is at <https://truthscan.com/llms.txt> and a Markdown version of this page is at <https://truthscan.com/de/truthscan-ai-capture-api-documentation.md>.

Capture-API

[![ISO 27001](https://truthscan.com/_next/image?url=%2Fimages%2Fcertifications%2Fiso-27001.webp&w=256&q=75&dpl=dpl_2eizWT8MUuujb4NWFLnyVZj6rK4e)](https://trust.truthscan.com/?lang=en)

[![SOC 2 Zertifiziert](https://truthscan.com/_next/image?url=%2Fimages%2Fcertifications%2Fsoc2.webp&w=256&q=75&dpl=dpl_2eizWT8MUuujb4NWFLnyVZj6rK4e)](https://trust.truthscan.com/?lang=en)

[![DSGVO-konform](https://truthscan.com/_next/image?url=%2Fimages%2Fcertifications%2Fgdpr.webp&w=256&q=75&dpl=dpl_2eizWT8MUuujb4NWFLnyVZj6rK4e)](https://trust.truthscan.com/?lang=en)

[![GASA-Partner](https://truthscan.com/_next/image?url=%2Fimages%2Fcertifications%2Fgasa.png&w=256&q=75&dpl=dpl_2eizWT8MUuujb4NWFLnyVZj6rK4e)](https://gasa.org/knowledge-base/blog/global-anti-scam-alliance-partners-with-truthscan-to-integrate-deepfake-detection-on-scam.org)

# 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](https://truthscan.com/de/account).

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.

```bash
POST /api/capture/session/create
```

Setzen 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

```bash
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

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

```bash
GET /api/capture/sessions/{sessionId}
```

Beispielanfrage

```bash
curl https://truthscan.com/api/capture/sessions/SESSION_ID \
  -H 'x-api-key: YOUR_API_KEY'
```

Beispielantwort

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

```bash
GET /api/capture/sessions/{sessionId}/assets
```

Beispielanfrage

```bash
curl 'https://truthscan.com/api/capture/sessions/SESSION_ID/assets?page=1&limit=20' \
  -H 'x-api-key: YOUR_API_KEY'
```

Beispielantwort

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

```bash
GET /api/capture/assets/{assetId}
```

Beispielanfrage

```bash
curl https://truthscan.com/api/capture/assets/ASSET_ID \
  -H 'x-api-key: YOUR_API_KEY'
```

Beispielantwort

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

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

Nein. Das Telefon lädt das JPEG direkt in den Speicher, TruthScan signiert es. Sie erhalten Metadaten und eine Download-URL.

Registrieren Sie webhookUrl beim Erstellen der Sitzung, oder fragen Sie GET /api/capture/sessions/{sessionId} ab, bis capturesUsed steigt.

Sie muss https sein, darf keine Zugangsdaten enthalten und darf nur auf eine öffentliche Adresse zeigen. Private, Loopback- und Link-Local-Hosts werden abgelehnt.

### Lädt mein Server das Foto hoch?

### Woran erkenne ich, dass eine Aufnahme fertig ist?

### Kann ich jede Webhook-URL wählen?
