• Gebruik de teruggegeven expires_at als absolute deadline. Het openen van de link of doorgaan met de verificatie verlengt deze termijn nooit.
• Hergebruik nooit verlopen launch- of callbacktokens. Rond de vorige poging af voordat je bewust een nieuwe sessie start; een onzekere resultaatuitwisseling mag niet automatisch een vervanging starten.
• 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: weergavenaam van de partnerapp binnen Verihop (max. 80 tekens).
• header: korte verificatietitel die de gebruiker ziet (max. 120 tekens).
• fields: Vermeld de gewenste catalogustokens. Een ontbrekende of lege lijst vraagt geen velden op.
• allowedDocuments: Optionele lijst met toegestane documenttypen: passport, idCard, driverLicense of residencePermit. Laat dit weg om elk ondersteund documenttype toe te staan; stuur geen lege array.
• callback: basis-retour-URL uit POST /v1/sessions. Verihop opent deze na afronding en voegt session_id, result_token (success path) en optioneel callback_jwt toe; verplicht en gevalideerd tegen je productie-allowlist.

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 in bearer-formaat.
• Content-Type: gebruik application/json voor request body parsing.
• Idempotency-Key: Aanbevolen bij herhaalde aanmaakverzoeken. Maak voor elke nieuwe poging een UUID en hergebruik die alleen met exact dezelfde requestbody.

{
  "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: unieke sessie-ID voor tracking en result retrieval.
• expires_at: vervaltijd van de sessie (Unix epoch seconds).
• launch_url: primaire URL voor web, Android, QR-codes, e-mail, SMS en algemene handoff.
• app_clip_url: directe native App Clip-URL voor iOS-partnerapps. Open deze exact zoals ontvangen; bouw de URL niet zelf opnieuw op.
• qr_url: QR-veilige URL; momenteel gelijk aan launch_url.
• status_url: sessiestatus-endpoint voor server-side 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
}

Voorbeeld van een Test-response op het bovenstaande verzoek: de gebruiker koos een ID-kaart. Persoonlijke waarden zijn geredigeerd; ID’s en tijdstippen zijn voorbeelden.

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

Resultaten met alleen documenten laten personalDetailsDocument weg.

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.

• Dit endpoint levert het goedgekeurde privéresultaat één keer. Elke receiptId verwijst naar het historische verificatiebewijs van dat document.
• Rond de verificatie af → ontvang de callback → haal het resultaat en de receipt-ID’s op.
• 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.
• Toegang tot het privéresultaat eindigt bij de vroegste opgeslagen deadline van de sessie of het resultaattoken. Op of na die exacte grens is het antwoord 410 result_token_expired; het lezen en verifiëren van receipts blijft onafhankelijk.
• 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 worden automatisch voorbereid zodra de verificatie is voltooid. Gebruik de receiptId-waarden uit GET /v1/sessions/{id}/result om ze op te halen.
• 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.

Een compacte JWS decoderen is geen handtekeningcontrole. Verifieer op je backend met het geconfigureerde Verihop-JWKS-endpoint. Vereis alg=RS256, typ=verihop-document-receipt+jwt, een bekende receipt-sleutel met kid, de geconfigureerde issuer en de audience uit je vertrouwde partnerconfiguratie. Neem geen sleutel-URL, verwachte audience of vertrouwensbeslissing over uit het ongeverifieerde token. Callback- en Document Receipt-sleutels hebben afzonderlijke doelen.

• 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 bevat de gevraagde persoonlijke gegevens: legalName, dateOfBirth, over18 en over21. Gevraagde documentgegevens staan in documents[].details. Typevereisten zoals passport en idCard vereisen die documenten; ze voegen geen boolean toe aan result en vragen niet alle documentgegevens op.

Ja. Je backend maakt een sessie met POST /v1/sessions en toont de teruggegeven qr_url als QR op de desktoppagina. De gebruiker scant die QR met de telefoon en Verihop opent de beste beschikbare ervaring.

De beste UX is direct launch: encodeer de teruggegeven qr_url. Dit is dezelfde universele HTTPS-handoff als launch_url en ondersteunt app, lichte ervaring en webfallback.

Gebruik launch_url op Android en voor algemene webhandoff. Een iOS-partnerapp die de native App Clip-kaart wil tonen, opent de teruggegeven app_clip_url. De callback-vorm blijft gelijk: Verihop voegt session_id, op het succespad result_token en optioneel callback_jwt toe.

Maak de sessie op je backend en stuur de teruggegeven app_clip_url naar je iOS-app. Open die URL met SwiftUI Link of UIApplication.open op iOS 17 of nieuwer. Parse launch_url niet, kopieer de token niet en hard-code de App Clip-bundle-ID van Verihop niet. Als de volledige Verihop-app is geïnstalleerd, opent iOS die met behoud van dezelfde sessie.

Gebruik je een custom callback zoals ridenow://verified, dan moet de Android partnerapp een intent filter declareren voor dat scheme en die host. Gebruik je een https:// callback voor desktop- of webgestarte flows, behandel die dan als backend-endpoint tenzij je Android app dat domein bezit met geverifieerde App Links.

Gebruik een https://-retourendpoint op je backend. Verihop opent die URL op de telefoon met session_id en bij succes result_token in de query. Dit is de terugkeer van de gebruiker, geen server-to-server-webhook. Je backend controleert de opgeslagen sessiekoppeling en haalt GET /v1/sessions/{id}/result op. De desktoppagina kan bij je backend de voltooiing controleren.

Nee. Aanmaken retourneert orkestratievelden en ondoorzichtige launch-URLs, geen JWT of privé-identiteitsgegevens. Open de teruggegeven URL ongewijzigd.

Een geslaagde terugkeer bevat session_id en result_token, plus callback_jwt indien ingeschakeld. Sommige appflows voegen status- of bronmetadata toe. Dit zijn geen persoonlijke resultaten of verificatiebewijzen. Controleer de sessiekoppeling, verifieer een meegegeven callback-JWT en haal het goedgekeurde resultaat op je backend op.

Ja, op de partnerbackend wanneer aanwezig. Verifieer signature en claims met Verihop JWKS via GET /.well-known/jwks.json. Valideer issuer, audience en expiry en zorg dat JWT-claims overeenkomen met de callback querywaarden.

Nee. Houd API-keys server-side en haal resultaten alleen via je backend op. De frontend/webclient hoort alleen UI te tonen en state door te geven aan je backend session.

Reconcilieer eerst een verbruikte, verlopen of onzekere resultaatuitwisseling. Herhaal result GET nooit automatisch en maak niet automatisch een andere sessie. Alleen een bewuste nieuwe actie start een nieuwe poging.

Open de teruggegeven launch_url of qr_url; de gehoste pagina begeleidt de gebruiker naar de ondersteunde app, App Clip of installatie. Op Android kan de gebruiker na installatie terugkeren en op Open Verihop tikken zolang de sessie geldig is. Maak niet alleen vanwege installatie een vervangende sessie. Laat de gebruiker na verval bewust een nieuwe poging starten.

POST /v1/sessions ondersteunt Idempotency-Key voor retry-veilige create-session calls: dezelfde key met dezelfde payload speelt de originele response opnieuw af, terwijl dezelfde key met een andere payload 409 idempotency_key_conflict teruggeeft. Misbruik wordt verder beperkt met API-key auth, callback-allowlistbeleid, field-allowlistchecks, rate limits/quota per klant, korte sessie-TTL en een eenmalige result_token.