Reused verifications API

Applicants who already completed an approved verification — an individual one, or a business (KYB) one — with another Certivant organization can share it with yours. You create a link, the applicant proves it is theirs and consents, and you redeem a single-use share token into a new, already-approved verification of your organization. Data and document files are copied into your own records and storage.

Endpoints live under /api/v1/kyc/reuse and use an API key (Authorization: Bearer ck_live_…). You need the Reused Verifications plan feature and Accept reused verifications (individuals) and/or Accept reused business verifications (businesses) turned on in Settings → KYC; the two are switched, aged and priced separately. See Authentication.

Flow

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

Create an invitation

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

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

Follow an invitation

GET /api/v1/kyc/reuse/invitations/:id — scope kyc:read. The response also carries type (INDIVIDUAL or BUSINESS). status is invited, code_sent, verified, consented (a token is waiting), redeemed, expired or revoked. When redeemed, requestId is the new verification. The share token is never returned here; it reaches you through the applicant's redirect.

Redeem a share token

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

Rules:

• A token is single use, expires after its lifetime, and works only for the organization the link was created by. Any other caller gets 404 invalid_token.
• The call creates a verification already approved, with copies of the applicant data, the extracted document fields and the document files (in your storage location). If your organization keeps no documents after a decision, no files are copied.
• For a business share (type: "BUSINESS" in the response) the new verification is a BUSINESS request that also carries the company record and registry result, the directors and beneficial owners (without the links to the source's own UBO verifications), the representative's verified identity and their match to the directors, and the authorization document if one exists. Read it with the usual KYB endpoints (GET /v1/kyc/requests/:id/kyb).
• The new verification records the API key that redeemed it. If that key is restricted to workflows, only those workflows run for it (see Workflow restriction).
• Your usual webhooks fire: a kyc.request.approved event with data.reason: "reused_verification".
• A failed copy gives the token back (until it expires) and leaves nothing behind.

Errors

Residency

Both organizations must have the same storage region, database region and AI-processing residency (an unset region only matches another unset one). Otherwise the share is refused with residency_mismatch — nothing is copied across a region boundary.

On a public form

When your organization accepts reused verifications of a kind, a public KYC form (individual) or KYB form (business) offers "Already verified with Certivant?" at its start. The applicant proves ownership (emailed code) and consents exactly as above, the form is pre-filled from the shared verification (they review and can correct everything; no documents are asked for), and the submission is filed against the new, already-approved reused verification. Combined KYC + KYB forms, invitation links (?kyc=) and non-verification forms don't offer it.

The form's own endpoints (public, no API key) are, for reference when you embed a form yourself:

A form protected by a secret key must send it as the X-Form-Key header on each call. A share created for a form can only be redeemed by that form's submit — not with POST /reuse/redeem (404 invalid_token) — and the new verification is attributed to the form.

Billing

Free by default. A Reused verification price (individuals) and a Reused business verification price (businesses) in Billing Prices (or a per-customer override) are charged to the receiving organization once per redeemed share; the call is idempotent per share.

Audit

The receiving organization's audit log records reuse.invitation_created, reuse.consent_received and reuse.redeemed. The source organization records reuse.consent_recorded and reuse.shared. The source organization's identity is never exposed to you.