• Verwende das zurückgegebene expires_at als absolute Frist. Das Öffnen des Links oder Fortsetzen der Verifikation verlängert diese Frist nie.
• Verwende abgelaufene Launch- oder Callback-Tokens nie erneut. Kläre den vorherigen Versuch vor einer bewusst neuen Session; ein unklarer Ergebnisaustausch darf keinen automatischen Ersatz auslösen.
• Verihop never refreshes a Session automatically. The partner must create the replacement Session; compatible documents already verified and stored locally may still be reused.

• app: Anzeigename der Partner-App in Verihop (max. 80 Zeichen).
• header: kurzer Verifikationstitel für den Nutzer (max. 120 Zeichen).
• fields: Liste die benötigten Katalog-Tokens auf. Eine fehlende oder leere Liste fordert keine Felder an.
• allowedDocuments: Optionale Liste zulässiger Dokumenttypen: passport, idCard, driverLicense oder residencePermit. Lasse sie weg, um alle unterstützten Dokumenttypen zuzulassen; sende kein leeres Array.
• callback: Basis-Rücksprung-URL aus POST /v1/sessions. Verihop öffnet sie nach Abschluss und ergänzt session_id, result_token (Success Path) und optional callback_jwt; erforderlich und gegen deine Produktions-Allowlist validiert.

fields says which verified values you request. allowedDocuments says which document types may provide evidence.

{
  "fields": ["legalName", "over18"],
  "allowedDocuments": ["passport", "idCard"]
}

This means Passport OR ID Card is eligible. It does not require both. The user chooses the concrete document used by each relevant section in the Verihop app.

• passport, idCard, driverLicense, and residencePermit are cumulative document-type assertions (AND). A request such as ["legalName", "passport", "idCard"] requires Passport + ID Card.
• documentNumber, documentExpiry, documentCountry, and documentNationality are one detail bundle. With explicit required types, they apply to each compatible required contributor; without one, the holder chooses one eligible document for the whole bundle. Driving licences do not supply documentNationality.
• Personal facts are global and conflict-safe; committed evidence can establish them without requiring another document.
• A holder may have multiple documents of the same type, including two passports from the same issuing country. Document type is not a unique identifier; receipt-backed partner evidence is distinguished by receiptId.
• Impossible combinations are rejected at creation. Requiring Passport while allowing only ID card is invalid. A Driver's licence-only request for documentNationality is also invalid.

• Authorization: Partner-API-Key im Bearer-Format.
• Content-Type: nutze application/json für Request-Body-Parsing.
• Idempotency-Key: Für Wiederholungen der Erstellung empfohlen. Erzeuge für jeden neuen Versuch eine UUID und verwende sie nur mit identischem Anfrageinhalt erneut.

{
  "session_id": "sess_123",
  "expires_at": 1893456900,
  "launch_url": "https://www.verihop.com/verify.html?session_id=sess_123&token=h_example123456789",
  "app_clip_url": "https://appclip.apple.com/id?p=KycBox.VerifyBox.Clip&session_id=sess_123&token=h_example123456789",
  "qr_url": "https://www.verihop.com/verify.html?session_id=sess_123&token=h_example123456789",
  "status_url": "https://api.verihop.com/v1/sessions/sess_123"
}

• session_id: eindeutige Session-ID für Tracking und Ergebnisabruf.
• expires_at: Ablaufzeit der Session (Unix Epoch Seconds).
• launch_url: primäre URL für Web, Android, QR-Codes, E-Mail, SMS und allgemeine Handoffs.
• app_clip_url: direkte native App-Clip-URL für iOS-Partnerapps. Öffne sie exakt wie zurückgegeben und rekonstruiere sie nicht.
• qr_url: QR-sichere URL; aktuell identisch mit launch_url.
• status_url: Session-Status-Endpunkt für serverseitiges Polling.

• 401 missing_bearer_token, 401 invalid_api_key
• 403 customer_inactive
• 400 missing_callback_url, invalid_callback_url, callback_host_not_allowed
• 400 field_not_allowed, invalid_field_token, invalid_allowed_documents
• 409 idempotency_key_conflict, idempotency_key_in_progress, idempotency_key_expired
• 413 request_too_large
• 429 rate_limit_exceeded, daily_quota_exceeded

{
  "session_id": "sess_123",
  "status": "issued",
  "issued_at": 1893456000,
  "expires_at": 1893456900,
  "last_status": null,
  "last_status_at": null,
  "opened_at": null,
  "result_available": false,
  "result_token_expires_at": null
}

Beispiel einer Testantwort auf die Anfrage oben: Der Nutzer wählte einen Personalausweis. Persönliche Werte sind redigiert; IDs und Zeitangaben sind Beispiele.

{
  "session_id": "sess_123",
  "status": "success",
  "result": {
    "legalName": "XXXTEST_USERXXX",
    "over18": "XXXTEST_USERXXX"
  },
  "personalDetailsDocument": {
    "type": "idCard",
    "issuingCountry": "ESP",
    "receiptId": "dr_AAAAAAAAAAAAAAAAAAAAAAAA"
  },
  "documents": [
    {
      "type": "idCard",
      "issuingCountry": "ESP",
      "receiptId": "dr_AAAAAAAAAAAAAAAAAAAAAAAA",
      "details": {
        "documentNumber": "XXXTEST_USERXXX",
        "documentExpiry": "XXXTEST_USERXXX"
      }
    }
  ]
}

result contains requested Personal Details only. personalDetailsDocument identifies the verified document selected by the user as their Personal Details source. The same document also appears in documents[]; that duplication is deliberate and is not an additional verification.

Reine Dokumentergebnisse enthalten kein personalDetailsDocument.

documents[] contains every unique document that supported the Session: the Personal Details source, generic Document Details source, and each exact required-document source. Every entry contains type, issuingCountry, receiptId, and details. When no document details were requested, details is {}. Internal field attribution is never exposed.

• Dieser Endpunkt liefert das freigegebene private Ergebnis einmal. Jede receiptId verweist auf den historischen Verifikationsnachweis dieses Dokuments.
• Verifikation abschließen → Callback empfangen → Ergebnis und Receipt-IDs abrufen.
• For a multi-document result, retrieve each documents[].receiptId independently with GET /v1/document-receipts/{receipt_id}. There is no combined receipt endpoint or combined JWS.
• Retrieving a Document Receipt is repeatable, but it does not recover or replay this private result payload.
• Der Zugriff auf das private Ergebnis endet mit der früheren gespeicherten Session- oder Ergebnis-Token-Frist. An oder nach dieser exakten Grenze lautet die Antwort 410 result_token_expired; Receipt-Abruf und -Verifikation bleiben unabhängig.
• One unique supporting document produces one Document Receipt; two unique supporting documents produce two.
• When a saved verification is reused, the receipt preserves the original verified_at; reuse is not represented as a new document verification.

Test mode

Test mode preserves this exact structure and redacts only actual Personal Details and document-detail values with XXXTEST_USERXXX. It does not redact type, issuingCountry, receiptId, or structural keys.

• 401 missing_bearer_token, invalid_api_key, missing_result_token
• 403 customer_inactive, api_key_environment_mismatch, invalid_result_token
• 410 result_token_expired
• 409 result_token_used
• 404 result_not_available, session_not_found
• 503 document_receipt_unavailable

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "example-key-id",
      "alg": "RS256",
      "use": "sig",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

• Document Receipts werden nach Abschluss der Verifikation automatisch vorbereitet. Verwende die receiptId-Werte aus GET /v1/sessions/{id}/result, um sie abzurufen.
• The partner-facing identifier is the opaque dr_.... Internal receipt identifiers and data-model terminology are not part of the public contract.
• Reuse of the same underlying verification for the same partner returns the same Document Receipt. Different partners receive different Document Receipts. A genuinely fresh verification creates a new receipt lineage.

{
  "receiptId": "dr_AAAAAAAAAAAAAAAAAAAAAAAA",
  "receiptVersion": 1,
  "issuedAt": "2026-09-11T12:00:00.000Z",
  "document": {
    "type": "idCard",
    "issuingCountry": "ESP"
  },
  "receipt": "eyJhbGciOiJSUzI1NiIsImtpZCI6InZocmNwdC1yczI1Ni0yMDI2MDkxMS0wMSIsInR5cCI6InZlcm...eyJyZWNlaXB0X3ZlcnNpb24iOjEsInZlcmlmaWNhdGlvbiI6ey4uLn19.signature-placeholder"
}

The abbreviated signature above is a display placeholder, not a cryptographically valid sample receipt. receipt contains the original compact signed JWS, not a URL. The response identifies the document by type and issuing country without identity PII.

• Use the owning partner account's Bearer API key. Knowing a dr_ identifier does not authorize access.
• A missing receipt and another partner's receipt both return the same non-enumerating 404 document_receipt_not_found.
• Repeated authorized retrieval returns the same stored JWS. It does not consume or re-sign the receipt and does not perform another document verification.
• A multi-document result has multiple independent receipt IDs. Call this endpoint once per ID; Verihop does not provide a combined receipt or multi-document JWS.
• Availability follows the approved receipt lifecycle and historical-key policy. It is not a promise of permanent storage.

The partner-facing methodology is verihop_v1, version 1. Verihop obtains document information from the supported document, runs its holder-verification flow, checks liveness, and matches the presented person against the document-holder evidence.

• Successful completion is presented as verification outcome verified, holder verification passed, and liveness passed.
• A successfully verified stored document can support later Sessions without a new face, selfie, or liveness step merely because it is reused.
• The methodology does not claim separate issuer or document cryptographic authentication.
• Historical evidence does not establish that a document is currently valid and does not bind or authenticate the complete Session result payload.
• A receipt is not a global person/document identifier or cross-partner identity lineage.

Das Dekodieren einer kompakten JWS prüft keine Signatur. Verifiziere im Backend mit dem konfigurierten Verihop-JWKS-Endpunkt. Verlange alg=RS256, typ=verihop-document-receipt+jwt, einen bekannten Receipt-Schlüssel mit kid, den konfigurierten Issuer und die Audience aus deiner vertrauenswürdigen Partnerkonfiguration. Übernimm keine Schlüssel-URL, erwartete Audience oder Vertrauensentscheidung aus dem ungeprüften Token. Callback- und Document Receipt-Schlüssel haben getrennte Zwecke.

• 400 invalid_document_receipt_id
• 401 missing_bearer_token, 401 invalid_api_key
• 403 customer_inactive, 403 api_key_environment_mismatch
• 404 document_receipt_not_found
• 409 document_receipt_revoked, 423 document_receipt_held, 410 document_receipt_erased
• 503 document_receipt_verification_unavailable, 503 document_receipt_unavailable

legalName, dateOfBirth, over18, over21, passport, idCard, driverLicense, residencePermit, documentNumber, documentExpiry, documentCountry, documentNationality

result enthält die angefragten persönlichen Angaben: legalName, dateOfBirth, over18 und over21. Angefragte Dokumentattribute stehen in documents[].details. Typanforderungen wie passport und idCard verlangen diese Dokumente; sie ergänzen weder einen booleschen Wert in result noch sämtliche Dokumentattribute.

Ja. Dein Backend erstellt eine Sitzung mit POST /v1/sessions und rendert die zurückgegebene qr_url als QR-Code auf der Desktopseite. Der Nutzer scannt den QR-Code mit dem Telefon und Verihop öffnet die bestmögliche Erfahrung.

Die beste UX ist ein direkter Start: Kodiere die zurückgegebene qr_url. Sie ist dieselbe universelle HTTPS-Übergabe wie launch_url und unterstützt App-, schlanke und Web-Fallbackpfade.

Verwende launch_url auf Android und für allgemeine Web-Handoffs. Eine iOS-Partnerapp, die die native App-Clip-Karte anzeigen möchte, öffnet die zurückgegebene app_clip_url. Die Callback-Struktur bleibt gleich: Verihop ergänzt session_id, im Erfolgsfall result_token und optional callback_jwt.

Erstelle die Session auf deinem Backend und sende die zurückgegebene app_clip_url an deine iOS-App. Öffne diese URL unter iOS 17 oder neuer mit SwiftUI Link oder UIApplication.open. Parse launch_url nicht, kopiere den Token nicht und hardcode die App-Clip-Bundle-ID von Verihop nicht. Ist die vollständige Verihop-App installiert, öffnet iOS stattdessen diese mit derselben Session.

Wenn du einen Custom Callback wie ridenow://verified nutzt, muss die Android-Partnerapp einen Intent Filter für dieses Scheme und diesen Host deklarieren. Wenn du für Desktop- oder Web-gestartete Flows einen https:// Callback nutzt, behandle ihn als Backend-Endpunkt, außer deine Android-App besitzt diese Domain über verifizierte App Links.

Verwende einen https://-Rückkehrendpunkt in deinem Backend. Verihop öffnet diese URL auf dem Smartphone mit session_id und bei Erfolg result_token in der Query. Dies ist die Rückkehr des Nutzers, kein Server-zu-Server-Webhook. Dein Backend prüft die gespeicherte Sitzungszuordnung und ruft GET /v1/sessions/{id}/result ab. Die Desktopseite kann den Abschluss bei deinem Backend abfragen.

Nein. Die Erstellung liefert Orchestrierungsfelder und undurchsichtige Launch-URLs, kein JWT und keine privaten Identitätsdaten. Öffne die zurückgegebene URL unverändert.

Eine erfolgreiche Rückkehr enthält session_id und result_token sowie gegebenenfalls callback_jwt. Manche App-Abläufe ergänzen Status- oder Quellenmetadaten. Dies sind weder persönliche Ergebnisse noch ein Verifikationsnachweis. Prüfe die Sitzungszuordnung und jedes mitgelieferte Callback-JWT und rufe das freigegebene Ergebnis im Backend ab.

Ja, auf dem Partnerbackend, wenn vorhanden. Verifiziere Signatur und Claims mit Verihop JWKS unter GET /.well-known/jwks.json. Prüfe Issuer, Audience und Expiry und stelle sicher, dass JWT-Claims zu den Callback-Querywerten passen.

Nein. API-Keys bleiben serverseitig und Ergebnisse werden nur über dein Backend abgerufen. Der Frontend/Web-Client sollte nur UI anzeigen und State an deine Backend-Session weitergeben.

Kläre zuerst einen verbrauchten, abgelaufenen oder unklaren Ergebnisaustausch. Wiederhole result GET nie automatisch und erstelle keine automatische Ersatz-Session. Nur eine bewusst neue Aktion startet einen neuen Versuch.

Öffne die zurückgegebene launch_url oder qr_url; die gehostete Seite führt zur unterstützten App, zum App Clip oder zur Installation. Unter Android kann der Nutzer nach der Installation zurückkehren und während der gültigen Sitzung auf Open Verihop tippen. Erstelle nicht allein wegen der Installation eine Ersatzsitzung. Nach Ablauf startet der Nutzer bewusst einen neuen Versuch.

POST /v1/sessions unterstützt Idempotency-Key für retry-sichere Create-Session-Aufrufe: gleicher Key plus gleiche Payload spielt die ursprüngliche Antwort erneut aus, während gleicher Key plus andere Payload 409 idempotency_key_conflict zurückgibt. Missbrauch wird zusätzlich durch API-Key-Auth, Callback-Allowlist, Field-Allowlist-Prüfungen, kundenspezifische Rate Limits/Quota, kurze Session-TTL und einmalige result_token begrenzt.