• Usa el expires_at devuelto como plazo absoluto. Abrir el enlace o continuar la verificación nunca amplía este plazo.
• Nunca reutilices tokens de lanzamiento o callback caducados. Resuelve el intento anterior antes de iniciar expresamente otra Session; un canje incierto no debe generar una sustitución automática.
• 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: nombre visible de la app partner dentro de Verihop (máx. 80 caracteres).
• header: título corto de verificación mostrado al usuario (máx. 120 caracteres).
• fields: Indica los tokens del catálogo que necesitas. Una lista omitida o vacía no solicita campos.
• allowedDocuments: Lista opcional de tipos admitidos: passport, idCard, driverLicense o residencePermit. Omítela para aceptar cualquier tipo de documento admitido; no envíes un array vacío.
• callback: URL base de retorno enviada en POST /v1/sessions. Verihop la abre al terminar y añade session_id, result_token (success path) y opcionalmente callback_jwt; requerida y validada contra tu allowlist de producción.

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: API key partner en formato bearer.
• Content-Type: usa application/json para parsear el request body.
• Idempotency-Key: Recomendada para reintentar la creación. Genera un UUID por intento nuevo y reutilízalo solo con el mismo cuerpo de solicitud.

{
  "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: identificador único para tracking y obtención del resultado.
• expires_at: expiración de sesión (Unix epoch seconds).
• launch_url: URL principal para web, Android, QR, emails, SMS y handoff general.
• app_clip_url: URL nativa directa del App Clip para apps partner de iOS. Ábrela exactamente como se devuelve; no la reconstruyas.
• qr_url: URL segura para QR; actualmente equivalente a launch_url.
• status_url: endpoint de estado de sesión para polling server-side.

• 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
}

Respuesta Test ilustrativa para la solicitud anterior: el usuario eligió un documento de identidad. Los valores personales están redactados; los identificadores y las fechas son ejemplos.

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

Los resultados de solo documentos omiten 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.

• Este endpoint entrega el resultado privado aprobado una sola vez. Cada receiptId remite a la evidencia histórica de verificación de ese documento.
• Completa la verificación → recibe el callback → obtén el resultado y los ID de los recibos.
• 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.
• El acceso al resultado privado termina en el primer plazo almacenado de la sesión o del token de resultado. En ese límite exacto o después, la respuesta es 410 result_token_expired; la lectura y verificación de recibos siguen siendo independientes.
• 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"
    }
  ]
}

• Los Document Receipts se preparan automáticamente al completarse la verificación. Usa los valores receiptId devueltos por GET /v1/sessions/{id}/result para obtenerlos.
• 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.

Decodificar una JWS compacta no verifica la firma. Verifica en tu backend con el endpoint JWKS de Verihop configurado. Exige alg=RS256, typ=verihop-document-receipt+jwt, un kid conocido para recibos, el issuer configurado y la audience de tu configuración de confianza. No tomes una URL de claves, una audience esperada o una decisión de confianza del token sin verificar. Las claves de callback y Document Receipt tienen finalidades separadas.

• 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 contiene los datos personales solicitados: legalName, dateOfBirth, over18 y over21. Los atributos documentales solicitados aparecen en documents[].details. Los requisitos de tipo como passport e idCard exigen esos documentos; no añaden un booleano a result ni todos sus atributos.

Sí. Tu backend crea una sesión mediante POST /v1/sessions y muestra la qr_url devuelta dentro de un QR en la página de escritorio. El usuario escanea ese QR con el teléfono y Verihop abre la mejor experiencia disponible.

La mejor experiencia es el inicio directo: codifica la qr_url devuelta. Es el mismo traspaso HTTPS universal que launch_url y admite rutas de app, experiencia ligera y fallback web.

Usa launch_url en Android y para el handoff web general. Una app partner de iOS que quiera mostrar la tarjeta nativa del App Clip debe abrir la app_clip_url devuelta. La forma del callback no cambia: Verihop añade session_id, en caso de éxito result_token y opcionalmente callback_jwt.

Crea la sesión en tu backend y envía la app_clip_url devuelta a tu app iOS. Abre esa URL con SwiftUI Link o UIApplication.open en iOS 17 o posterior. No analices launch_url, no copies su token ni fijes en código el bundle ID del App Clip de Verihop. Si la app completa de Verihop está instalada, iOS la abre conservando la misma sesión.

Si usas un callback personalizado como ridenow://verified, la app Android partner debe declarar un intent filter para ese scheme y host. Si usas un callback https:// para flujos iniciados desde desktop o web, trátalo como un endpoint de backend salvo que tu app Android sea dueña de ese dominio con App Links verificados.

Usa una URL de retorno https:// en tu backend. Verihop la abre en el teléfono con session_id y, en caso de éxito, result_token en la query. Es el retorno del usuario, no un webhook entre servidores. Tu backend valida la sesión almacenada y obtiene GET /v1/sessions/{id}/result. La página de escritorio puede consultar a tu backend si terminó.

No. La creación devuelve campos de orquestación y URL opacas de lanzamiento, no un JWT ni datos privados de identidad. Abre la URL devuelta sin modificarla.

Un retorno correcto incluye session_id y result_token, además de callback_jwt si está habilitado. Algunos flujos añaden metadatos de estado u origen. No son resultados personales ni una prueba de verificación. Valida la sesión, verifica cualquier JWT de callback recibido y obtén el resultado aprobado en tu backend.

Sí, en el backend del partner cuando esté presente. Verifica firma y claims con Verihop JWKS en GET /.well-known/jwks.json. Valida issuer, audience y expiry, y asegúrate de que los claims JWT coincidan con los valores del callback.

No. Mantén las API keys en servidor y obtén resultados solo desde tu backend. El frontend/web client solo debe manejar UI y pasar estado a la sesión de backend.

Primero reconcilia un canje consumido, caducado o incierto. Nunca reintentes automáticamente result GET ni crees otra Session. Solo una nueva acción expresa inicia otro intento.

Abre la launch_url o qr_url devuelta; la página alojada guía al usuario hacia la app, el App Clip o la instalación admitida. En Android puede volver tras instalar y tocar Open Verihop mientras la sesión siga vigente. No crees una sesión nueva solo por necesitar la instalación. Tras caducar, el usuario inicia expresamente otro intento.

POST /v1/sessions soporta Idempotency-Key para llamadas create-session seguras ante retries: la misma key con la misma payload reproduce la respuesta original, mientras que la misma key con una payload distinta devuelve 409 idempotency_key_conflict. El abuso se mitiga además con autenticación por API key, política de callback allowlist, validación de campos permitidos, rate limits/cuota por cliente, TTL corto de sesión y result_token de un solo uso.