Get the app. Get verified. That's it.

• 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,
  "jwt": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ...",
  "deep_link": "verifybox://share?session=eyJ..."
}

• session_id: Unique session identifier for tracking and result retrieval.
• expires_at: Session expiry (Unix epoch seconds).
• jwt: Signed session token consumed by Verihop app via deep_link; partner clients normally do not validate this token directly.
• deep_link: URL to open Verihop directly (use this as QR content for desktop-start flows).

• 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, document, passport, residencePermit, bankAccount, residence, business

legalName, dateOfBirth, over18, over21, documentType, documentNumber, documentExpiry, documentCountry, documentNationality, documentResidence, bankHolder, bankIdentifier, bankIdentifierLabel, bankInstitution, bankCountry, bankCurrency, bankAccountName, bankAccountType, residenceAddress, residencePostalCode, residenceCity, residenceCountry, nationality, residence

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

Best UX is direct launch: encode verifybox://share?session=... in the QR. A landing web page with a big "Open Verihop" button can be used as a fallback for devices that do not open app links directly.

Yes. Verihop uses the same launch URL on both platforms: verifybox://share?session=<jwt>. Android opens it with an ACTION_VIEW intent, and iOS opens it with the registered Verihop URL scheme. Your callback shape is also the same: Verihop appends session_id, success-path result_token, and optional callback_jwt.

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 deep_link 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.