• app: Partner app display name shown inside Verihop (max 80 chars).
• header: Short verification title shown to the user (max 120 chars).
• fields: Requested field tokens; if omitted/empty, fallback is legalName and over18.
• 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.

• Authorization: Partner API key in bearer format.
• Content-Type: Use application/json for request body parsing.
• Idempotency-Key: Retry key for create-session dedupe; send UUID v4/v7 and reuse only for same payload retries.

{
  "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: 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, 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,
  "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

The result contains only the requested supported fields approved by the user. Document-kind requirements such as passport and idCard do not automatically 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:// callback endpoint on your backend. After Verihop completes, your server receives session_id and result_token, then fetches GET /v1/sessions/{id}/result server-to-server.

No. That token is for Verihop app consumption. Partners should treat it as opaque transport data and use launch_url to launch Verihop.

Callback query parameters are transport metadata only. Verified personal data is intentionally not sent in callback URLs. Your backend must exchange the one-time result_token to fetch the result payload securely. If enabled, callback_jwt can be verified via JWKS for callback authenticity.

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.

Create a new session when a session expires or the user abandons the flow. result_token is short-lived and single-use; if consumed or expired, restart with a new POST /v1/sessions.

Provide a fallback page behind your QR flow that can explain how to install/open Verihop and then continue. After install, create a new session and show a fresh QR (do not reuse stale sessions).

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.