• Een sessie is vanaf het aanmaken 15 minuten geldig. Dit is één totale periode voor het openen van de link, documentcontroles, beoordeling en goedkeuring; die begint niet opnieuw na MRZ, NFC of selfie.
• Wanneer mobiele verificatie een beveiligingschallenge nodig heeft, is die maximaal 10 minuten geldig, maar nooit langer dan de sessie. iOS en Android gebruiken dezelfde door de backend uitgegeven vervaltijd en een veiligheidsmarge van 15 seconden.
• Maak een nieuwe sessie wanneer expires_at is verstreken. Hergebruik geen verlopen launch-URL, QR-code of callback-token.

• app: weergavenaam van de partnerapp binnen Verihop (max. 80 tekens).
• header: korte verificatietitel die de gebruiker ziet (max. 120 tekens).
• fields: gevraagde veldtokens; bij leeg/ontbrekend gebruikt Verihop legalName en over18.
• 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.

• Authorization: partner-API-key in bearer-formaat.
• Content-Type: gebruik application/json voor request body parsing.
• Idempotency-Key: retry-key voor create-session dedupe; stuur UUID v4/v7 en hergebruik alleen voor retries met dezelfde payload.

{
  "session_id": "sess_123",
  "expires_at": 1730000000,
  "launch_url": "https://www.verihop.com/verify.html?session_id=sess_123&token=h_abc123",
  "app_clip_url": "https://appclip.apple.com/id?p=KycBox.VerifyBox.Clip&session_id=sess_123&token=h_abc123",
  "qr_url": "https://www.verihop.com/verify.html?session_id=sess_123&token=h_abc123",
  "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, request_too_large
• 409 idempotency_key_conflict, idempotency_key_in_progress
• 429 rate_limit_exceeded, daily_quota_exceeded

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

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "kid_2025_01",
      "alg": "RS256",
      "use": "sig",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

{
  "session_id": "sess_123",
  "status": "success",
  "result": {
    "legalName": "Jane Doe",
    "over18": "yes"
  }
}

• 401 missing_bearer_token, invalid_api_key, missing_result_token
• 403 customer_mismatch, invalid_result_token
• 410 result_token_expired
• 409 result_token_used
• 404 result_not_available, session_not_found

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

Het resultaat bevat alleen de gevraagde ondersteunde velden die de gebruiker heeft goedgekeurd. Vereisten voor documentsoorten zoals passport en idCard bevatten niet automatisch elk documentattribuut.

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:// callback-endpoint op je backend. Nadat Verihop klaar is, ontvangt je server session_id en result_token, en haalt daarna GET /v1/sessions/{id}/result server-to-server op.

Nee. Die token is bedoeld voor Verihop. Partners behandelen deze als opaque transportdata en gebruiken launch_url om Verihop te starten.

Callback-queryparameters zijn alleen transportmetadata. Geverifieerde persoonsgegevens worden bewust niet in callback-URLs meegestuurd. Je backend moet de eenmalige result_token uitwisselen om de result payload veilig op te halen. Indien ingeschakeld kan callback_jwt via JWKS worden geverifieerd voor callback-authenticiteit.

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.

Maak een nieuwe sessie wanneer een sessie verloopt of de gebruiker de flow verlaat. result_token is kort geldig en eenmalig te gebruiken; is die gebruikt of verlopen, start dan opnieuw met een nieuwe POST /v1/sessions.

Voorzie een fallbackpagina achter je QR-flow die uitlegt hoe de gebruiker Verihop installeert of opent en daarna doorgaat. Maak na installatie een nieuwe sessie en toon een verse QR-code; hergebruik geen verlopen sessies.

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.