API de verificações reaproveitadas

Solicitantes que já concluíram uma verificação aprovada — de pessoa física ou de empresa (KYB) — com outra organização da Certivant podem compartilhá-la com a sua. Você cria um link, o solicitante comprova que a verificação é dele e dá o consentimento, e você resgata um token de compartilhamento de uso único em uma nova verificação já aprovada da sua organização. Os dados e os arquivos dos documentos são copiados para os seus próprios registros e armazenamento.

Os endpoints ficam em /api/v1/kyc/reuse e usam uma chave de API (Authorization: Bearer ck_live_…). Você precisa do recurso de plano Verificações reaproveitadas e de Aceitar verificações reaproveitadas (pessoas físicas) e/ou Aceitar verificações empresariais reaproveitadas (empresas) ativados em Configurações → KYC; os dois são ativados, limitados por idade e precificados separadamente. Consulte Autenticação.

Fluxo

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

Criar um convite

POST /api/v1/kyc/reuse/invitations — escopo kyc:write.

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

Acompanhar um convite

GET /api/v1/kyc/reuse/invitations/:id — escopo kyc:read. A resposta também traz type (INDIVIDUAL ou BUSINESS). status é invited, code_sent, verified, consented (um token está aguardando), redeemed, expired ou revoked. Quando resgatado, requestId é a nova verificação. O token de compartilhamento nunca é retornado aqui; ele chega até você pelo redirecionamento do solicitante.

Resgatar um token de compartilhamento

POST /api/v1/kyc/reuse/redeem — escopo 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
}

Regras:

• Um token é de uso único, expira após a sua validade e funciona somente para a organização que criou o link. Qualquer outro chamador recebe 404 invalid_token.
• A chamada cria uma verificação já aprovada, com cópias dos dados do solicitante, dos campos extraídos dos documentos e dos arquivos dos documentos (no seu local de armazenamento). Se a sua organização não mantém documentos após uma decisão, nenhum arquivo é copiado.
• Para um compartilhamento empresarial (type: "BUSINESS" na resposta), a nova verificação é uma solicitação BUSINESS que também traz o registro da empresa e o resultado da consulta ao registro, os diretores e beneficiários finais (sem os vínculos com as verificações UBO de origem), a identidade verificada do representante e a correspondência dele com os diretores, além do documento de autorização, se existir. Leia-a com os endpoints KYB habituais (GET /v1/kyc/requests/:id/kyb).
• A nova verificação registra a chave de API que a resgatou. Se essa chave for restrita a fluxos de trabalho, somente esses fluxos são executados para ela (veja Restrição de fluxo de trabalho).
• Seus webhooks habituais são disparados: um evento kyc.request.approved com data.reason: "reused_verification".
• Uma cópia que falhe devolve o token (até ele expirar) e não deixa nada para trás.

Erros

Residência de dados

Ambas as organizações devem ter a mesma região de armazenamento, a mesma região de banco de dados e a mesma residência de processamento de IA (uma região não definida só corresponde a outra também não definida). Caso contrário, o compartilhamento é recusado com residency_mismatch — nada é copiado através de uma fronteira de região.

Em um formulário público

Quando a sua organização aceita verificações reaproveitadas de um tipo, um formulário KYC público (pessoa física) ou formulário KYB (empresa) oferece "Já verificado com a Certivant?" no início. O solicitante comprova a titularidade (código enviado por e-mail) e dá o consentimento exatamente como acima; o formulário é preenchido previamente com a verificação compartilhada (ele revisa e pode corrigir tudo; nenhum documento é solicitado), e o envio é registrado na nova verificação reaproveitada, já aprovada. Formulários combinados de KYC + KYB, links de convite (?kyc=) e formulários que não são de verificação não oferecem essa opção.

Os endpoints do próprio formulário (públicos, sem chave de API) são, para referência quando você incorpora um formulário por conta própria:

Um formulário protegido por chave secreta deve enviá-la no cabeçalho X-Form-Key em cada chamada. Um compartilhamento criado para um formulário só pode ser resgatado pelo envio desse formulário — não por POST /reuse/redeem (404 invalid_token) — e a nova verificação é atribuída ao formulário.

Faturamento

Gratuito por padrão. Um preço de Verificação reaproveitada (pessoas físicas) e um preço de Verificação empresarial reaproveitada (empresas) em Preços de faturamento (ou em um valor específico por cliente) são cobrados da organização receptora uma vez por compartilhamento resgatado; a chamada é idempotente por compartilhamento.

Auditoria

O registro de auditoria da organização receptora registra reuse.invitation_created, reuse.consent_received e reuse.redeemed. A organização de origem registra reuse.consent_recorded e reuse.shared. A identidade da organização de origem nunca é exposta a você.