• Use the returned expires_at as the absolute deadline. Opening the link or continuing verification never extends this deadline.
• Never reuse expired launch or callback tokens. Resolve the previous attempt before deliberately starting a new Session; an uncertain result exchange must not trigger an automatic replacement.
• 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: Partner app display name shown inside Verihop (max 80 chars).
• header: Short verification title shown to the user (max 120 chars).
• fields: List the catalog tokens you need. An omitted or empty list requests no fields.
• allowedDocuments: Optional document-type allowlist using passport, idCard, driverLicense, or residencePermit. Omit it to accept any supported document type; do not send an empty array.
• callback: Base return URL sent in POST /v1/sessions. Verihop opens it after completion and appends session_id, result_token (success path), and optional callback_jwt; required and allowlist-validated in your production policy.

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 format.
• Content-Type: Use application/json for request body parsing.
• Idempotency-Key: Recommended for creation retries. Generate a UUID for each new attempt and reuse it only with the identical request body.

{
  "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: Unique session identifier for tracking and result retrieval.
• expires_at: Session expiry (Unix epoch seconds).
• launch_url: Primary URL for web, Android, QR codes, emails, SMS, and general handoff.
• app_clip_url: Direct native App Clip URL for iOS partner apps. Open it exactly as returned; do not reconstruct it.
• qr_url: QR-safe URL; currently equivalent to launch_url.
• status_url: Session status endpoint for 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
}

Illustrative Test response for the request above: the user chose an ID card. Personal values are redacted; IDs and timestamps are examples.

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

Document-only results omit 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.

• This endpoint delivers the approved private result once. Each receiptId points to that document’s historical verification evidence.
• Complete verification → receive the callback → fetch the result and receipt IDs.
• 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.
• Private result access ends at the earlier stored Session or result-token deadline. At or after that exact boundary, the response is 410 result_token_expired; receipt reads and verification stay independent.
• 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 are prepared automatically when verification completes. Use the receiptId values returned by GET /v1/sessions/{id}/result to retrieve them.
• 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.

Decoding a compact JWS is not signature verification. Verify on your backend with the configured Verihop JWKS endpoint. Require alg=RS256, typ=verihop-document-receipt+jwt, a recognized receipt-purpose kid, the configured issuer, and the audience derived from your trusted partner configuration. Do not take a key URL, expected audience, or trust decision from the unverified token. Callback and Document Receipt signing keys are separate purposes.

• 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 contains requested Personal Details: legalName, dateOfBirth, over18, and over21. Requested document attributes appear in documents[].details. Type requirements such as passport and idCard require those documents; they do not add a boolean field to result or include every document attribute.

Yes. Your backend creates a session using POST /v1/sessions, then renders the returned qr_url inside a QR shown on the desktop page. The user scans that QR with their phone and Verihop opens the best available experience.

Best UX is direct launch: encode the returned qr_url. It is the same universal HTTPS handoff as launch_url and supports app, lightweight, and web fallback paths.

Use launch_url on Android and for general web handoff. An iOS partner app that wants the native App Clip card should open the returned app_clip_url. Your callback shape remains the same: Verihop appends session_id, success-path result_token, and optional callback_jwt.

Create the session on your backend and send the returned app_clip_url to your iOS app. Open that URL with SwiftUI Link or UIApplication.open on iOS 17 or later. Do not parse launch_url, copy its token, or hard-code Verihop's App Clip bundle ID. If the full Verihop app is installed, iOS opens it instead while preserving the same session.

If you use a custom callback such as ridenow://verified, the Android partner app must declare an intent filter for that scheme and host. If you use an https:// callback for desktop or web-started flows, treat it as a backend endpoint unless your Android app owns that domain with verified App Links.

Use an https:// return endpoint on your backend. Verihop opens that URL on the phone with session_id and the success-path result_token in the query. This is a user return, not a server-to-server webhook. Your backend validates the stored session binding and fetches GET /v1/sessions/{id}/result. The desktop page can check your backend for completion.

No. Creation returns orchestration fields and opaque launch URLs, not a JWT or private identity values. Open the returned URL unchanged.

A successful return includes session_id and result_token, plus callback_jwt when enabled. Some app flows also include status or source metadata. These are not personal results or proof of verification. Validate the session binding, verify any supplied callback JWT, and fetch the approved result on your backend.

Yes, on partner backend when present. Verify signature and claims using Verihop JWKS at GET /.well-known/jwks.json. Validate issuer/audience/expiry and ensure JWT claims match callback query values.

No. Keep API keys server-side and fetch results from your backend only. The frontend/web client should only handle UI and pass state to your backend session.

Reconcile a consumed, expired or uncertain result exchange first. Never automatically retry result GET or create another Session. Only a deliberate new logical action starts a new attempt.

Open the returned launch_url or qr_url; the hosted handoff provides the supported app, App Clip, or installation guidance. On Android, the user can return after installation and tap Open Verihop while the session is still valid. Do not create a replacement merely because installation was needed. After expiry, let the user deliberately start a new attempt.

POST /v1/sessions supports Idempotency-Key for retry-safe create-session calls: same key + same payload replays the original response, while same key + different payload returns 409 idempotency_key_conflict. Misuse is further mitigated with API-key auth, callback allowlist policy, field allowlist checks, per-customer rate limits/quota, short session TTL, and one-time result_token.