KYC flow

Every BlendFi end user must complete identity verification before they can move money. This is a regulatory requirement — without an approved KYC, attempts to create a quote or transaction return 403 missing_capability for the user. BlendFi handles KYC through Sumsub; you don't talk to Sumsub directly.

How it fits together

Your app                BlendFi                   Sumsub
   │                       │                         │
   ├─ POST /v1/users ─────►│                         │
   │◄──── user created ────┤                         │
   │   (kyc: not_started)  │                         │
   │                       │                         │
   ├─ POST /v1/users/{id}/kyc ─►                     │
   │                       ├── create applicant ────►│
   │                       │◄──── applicant id ──────┤
   │                       ├── generate websdk link ►│
   │                       │◄──── signed url ────────┤
   │◄──── kyc submission ──┤                         │
   │   (kyc: pending,      │                         │
   │    websdk_url)        │                         │
   │                       │                         │
   ├─ redirect end user to websdk_url ───────────────►
   │                       │   (user submits docs)   │
   │                       │◄────── webhook ─────────┤
   │                       │  (review result)        │
   │◄── webhook to you ────┤                         │
   │  (kyc: approved)      │                         │

You only ever call BlendFi. BlendFi calls Sumsub on your behalf and reflects results back to you.

Five outcomes

The full path

curl -X POST $BLENDFI_BASE/v1/users \
  -H "Authorization: Bearer $BLENDFI_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "external_id": "your-user-001",
    "name": "Ada Lovelace",
    "cpf": "52998224725"
  }'

curl -X POST $BLENDFI_BASE/v1/users/01J.../kyc \
  -H "Authorization: Bearer $BLENDFI_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

{
  "user_id": "01J...",
  "status": "pending",
  "websdk_url": "https://websdk.sumsub.com/start/eyJ...",
  "websdk_url_expires_at": "2026-04-29T13:30:00Z"
}

{
  "type": "user.kyc.approved",
  "user_id": "01J...",
  "external_id": "your-user-001",
  "kyc_status": "approved",
  "approved_at": "2026-04-29T13:08:00Z",
  "expires_at": "2027-04-29T13:08:00Z"
}

curl $BLENDFI_BASE/v1/users/01J.../kyc \
  -H "Authorization: Bearer $BLENDFI_KEY"

{
  "user_id": "01J...",
  "status": "approved",
  "approved_at": "2026-04-29T13:08:00Z",
  "expires_at": "2027-04-29T13:08:00Z"
}

Driving KYC outcomes in sandbox

Sandbox uses a Sumsub mirror. To avoid waiting for real document review, use the test helper to force any outcome:

curl -X POST $BLENDFI_BASE/v1/test_helpers/users/01J.../kyc \
  -H "Authorization: Bearer $BLENDFI_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{"status": "approved"}'

Acceptable values: "approved", "rejected", "expired". The webhook fires exactly as it would in production, so your handler logic is exercised end-to-end.

Renewal and expiration

Approved KYCs are valid for 12 months by default. We watch the expiration and downshift the user to kyc_status: expired on the boundary day. You receive a user.kyc.expired webhook 7 days before the expiration so you can prompt the user to re-verify ahead of time.

A re-verification is a fresh POST /v1/users/{id}/kyc call — the user goes through the same WebSDK flow again. There's no separate "renewal" endpoint.

Rejections

A rejected outcome includes a rejection_reason:

{
  "user_id": "01J...",
  "status": "rejected",
  "rejected_at": "2026-04-29T13:08:00Z",
  "rejection_reason": "document_unreadable"
}

Common reasons:

A rejected user can re-submit (POST /v1/users/{id}/kyc again). The new submission supersedes the rejection; status returns to pending.

pep_match and sanctions_match are terminal in our flow — re-submission won't help. We handle these case-by-case with you.

What to read next

FAQ

Can the same end user re-submit if rejected? Yes — for most rejection reasons. Call POST /v1/users/{id}/kyc again to get a new WebSDK link; the user goes through the flow afresh. The two terminal cases are pep_match and sanctions_match — those require a human review on our side.

What happens if the user closes the WebSDK halfway through? Their kyc_status stays pending. The WebSDK keeps the partial state for ~24 hours; if they reopen the same link within that window, they pick up where they left off. After expiration, generate a new link.

Do I need to verify the webhook signature? Yes. Production webhooks from BlendFi carry an X-BlendFi-Signature header (HMAC-SHA-256 over the body, with a per-organization secret). Reject any webhook whose signature doesn't verify. We provide reference verification snippets in the webhooks reference.

Why does not_started exist as a state if I always start KYC right after creating the user? Some integrations create users early (e.g. waitlist signup) and only trigger KYC when the user takes a money-relevant action. The two-step shape supports that pattern. If you always start KYC immediately, just treat not_started as a transient state your UI never displays.

Can I see the rejected document images? No. Sumsub holds the documents; BlendFi only sees the verdict and the rejection reason. This is a privacy boundary by design.

The user passed KYC in another product I run — can I skip BlendFi's KYC for them? No. We re-verify per BlendFi organization, regardless of whether the same end user has been verified elsewhere. This is a regulatory constraint.