API de verificaciones reutilizadas

Los solicitantes que ya completaron una verificación aprobada, sea de persona física o de empresa (KYB), con otra organización de Certivant pueden compartirla con la suya. Usted crea un enlace, el solicitante demuestra que es suya y da su consentimiento, y usted canjea un token de compartición de un solo uso por una nueva verificación ya aprobada de su organización. Los datos y los archivos de documentos se copian a sus propios registros y almacenamiento.

Los endpoints están en /api/v1/kyc/reuse y usan una clave de API (Authorization: Bearer ck_live_…). Necesita la función del plan Verificaciones reutilizadas y tener activados Aceptar verificaciones reutilizadas (personas físicas) y/o Aceptar verificaciones de empresa reutilizadas (empresas) en Configuración → KYC; los dos interruptores se activan, envejecen y se tarifican por separado. Consulte Autenticación.

Flujo

sequenceDiagram
  participant You as Your system
  participant C as Certivant
  participant A as Applicant
  You->>C: POST /reuse/invitations
  C-->>You: inviteUrl
  You->>A: send inviteUrl
  A->>C: verification ID + emailed code
  A->>C: consent ("Share my verified identity with you")
  C-->>A: redirect to redirectUrl?certivant_share=krs_…
  A->>You: lands on your page with the token
  You->>C: POST /reuse/redeem { shareToken }
  C-->>You: new approved verification

Crear una invitación

POST /api/v1/kyc/reuse/invitations: ámbito kyc:write.

{
  "id": "clx…",
  "inviteUrl": "https://app.certivant.com/reuse/kri_…",
  "inviteExpiresAt": "2026-10-24T13:00:00.000Z",
  "shareTtlMinutes": 30
}

Seguir una invitación

GET /api/v1/kyc/reuse/invitations/:id: ámbito kyc:read. La respuesta incluye también type (INDIVIDUAL o BUSINESS). status puede ser invited, code_sent, verified, consented (hay un token pendiente), redeemed, expired o revoked. Cuando se canjea, requestId es la nueva verificación. El token de compartición nunca se devuelve aquí: le llega a través de la redirección del solicitante.

Canjear un token de compartición

POST /api/v1/kyc/reuse/redeem: ámbito kyc:write.

{ "shareToken": "krs_…" }

{
  "requestId": "clx…",
  "applicantId": "clx…",
  "status": "APPROVED",
  "type": "INDIVIDUAL",
  "externalRef": "crm-7",
  "reused": true,
  "verifiedAt": "2026-09-30T15:12:00.000Z",
  "sourceAgeDays": 24,
  "documentsCopied": 2,
  "chargedCents": 0
}

Reglas:

• Un token es de un solo uso, caduca al cumplirse su duración y funciona solo para la organización que creó el enlace. Cualquier otro llamador recibe 404 invalid_token.
• La llamada crea una verificación ya aprobada, con copias de los datos del solicitante, de los campos extraídos de los documentos y de los archivos de documentos (en su ubicación de almacenamiento). Si su organización no conserva documentos tras una decisión, no se copia ningún archivo.
• Para una compartición de empresa (type: "BUSINESS" en la respuesta), la nueva verificación es una solicitud BUSINESS que también incluye el registro de la empresa y el resultado del registro, los directores y los beneficiarios finales (sin los enlaces a las verificaciones UBO propias del origen), la identidad verificada del representante y su coincidencia con los directores, y el documento de autorización si existe. Léala con los endpoints KYB habituales (GET /v1/kyc/requests/:id/kyb).
• La nueva verificación registra la clave de API que la canjeó. Si esa clave está restringida a workflows, solo se ejecutan para ella esos workflows (consulte Restricción de workflows).
• Se disparan sus webhooks habituales: un evento kyc.request.approved con data.reason: "reused_verification".
• Si una copia falla, el token se devuelve (hasta que caduque) y no queda nada a medias.

Errores

Residencia

Ambas organizaciones deben tener la misma región de almacenamiento, la misma región de base de datos y la misma residencia del procesamiento de IA (una región no definida solo coincide con otra también no definida). En caso contrario, la compartición se rechaza con residency_mismatch: no se copia nada a través de un límite de región.

En un formulario público

Cuando su organización acepta verificaciones reutilizadas de un tipo, un formulario KYC público (persona física) o un formulario KYB (empresa) ofrece al inicio la opción «¿Ya verificado con Certivant?». El solicitante demuestra la titularidad (código enviado por correo) y da su consentimiento exactamente como se ha descrito; el formulario se rellena previamente con la verificación compartida (puede revisar y corregir todo; no se piden documentos), y el envío se archiva con la nueva verificación reutilizada ya aprobada. Los formularios combinados KYC + KYB, los enlaces de invitación (?kyc=) y los formularios que no son de verificación no ofrecen esta opción.

Los endpoints propios del formulario (públicos, sin clave de API) son, como referencia para cuando incruste un formulario usted mismo:

Un formulario protegido con una clave secreta debe enviarla en la cabecera X-Form-Key en cada llamada. Una compartición creada para un formulario solo puede canjearse mediante el envío de ese formulario, no con POST /reuse/redeem (404 invalid_token), y la nueva verificación se atribuye al formulario.

Facturación

Gratuita por defecto. Un precio de Verificación reutilizada (personas físicas) y un precio de Verificación de empresa reutilizada (empresas), en los Precios de facturación (o en una excepción por cliente), se cobran a la organización receptora una vez por cada compartición canjeada; la llamada es idempotente por compartición.

Auditoría

El registro de auditoría de la organización receptora registra reuse.invitation_created, reuse.consent_received y reuse.redeemed. La organización de origen registra reuse.consent_recorded y reuse.shared. La identidad de la organización de origen nunca se le muestra a usted.