KYC flow

Every BlendFi end customer must complete the platform KYC before any money moves. It's a regulatory requirement: without kyc_status: approved, any quote or transaction returns kyc_required (422). BlendFi conducts the verification behind the endpoint; your integration only talks to the BlendFi API.

How it all fits together

Your app                BlendFi              Identity verification
   │                       │                              │
   ├── POST /v1/users ────►│                              │
   │◄── user created ──────┤                              │
   │   (kyc: not_started)  │                              │
   │                       │                              │
   ├── POST /v1/users/{id}/kyc ─►                         │
   │                       ├── start submission ─────────►│
   │                       │◄────── signed link ──────────┤
   │◄── submission created ┤                              │
   │   (kyc: pending,      │                              │
   │    websdk_url)        │                              │
   │                       │                              │
   ├── redirect end customer to websdk_url ───────────────►
   │                       │ (customer submits docs)      │
   │                       │◄──── result webhook ─────────┤
   │                       │                              │
   │◄── webhook user.kyc_approved ─┤                      │
   │   (kyc: approved)             │                      │
   │                       │                              │
   │                       ├── starts crypto KYC in background
   │                       │

You only call BlendFi. BlendFi runs the verification and reflects results back via webhook.

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://verify.blendfi.com.br/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"
}

Forcing KYC outcomes in sandbox

The sandbox uses a mirror of the verification. To avoid waiting for a 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"}'

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

Renewal and expiration

Approved KYCs are valid for 12 months by default. BlendFi monitors expiration and moves the user to kyc_status: expired on the cutoff day. You receive a user.kyc_expired webhook 7 days before expiration so you can prompt the customer to reverify in advance.

Reverification is a fresh POST /v1/users/{id}/kyc call. The end customer goes through the same flow. There is no separate "renewal" endpoint.

Rejections

A rejected result includes a rejection_reason:

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

Common reasons:

A rejected end customer can resubmit (POST /v1/users/{id}/kyc again). The new submission supersedes the rejection; status returns to pending.

pep_match and sanctions_match are terminal; resubmission does not resolve them. Handled case by case.

Next steps

FAQ

Can the end customer resubmit if rejected? Yes, for most reasons. Call POST /v1/users/{id}/kyc again to generate a new link; the customer goes through the flow again. Terminal cases: pep_match and sanctions_match, which require human review.

What happens if the end customer closes the verification mid-flow? kyc_status stays pending. The flow holds partial state for about 24 hours; reopening the same link within that window resumes where it left off. After expiration, generate a new link.

Do I need to verify the webhook signature? Yes. BlendFi webhooks carry the X-Blendfi-Signature header (HMAC-SHA-256 over {t}.{raw_body}, with a per-endpoint secret). Reject any delivery whose signature doesn't match. Details in Webhooks.

Why does not_started exist 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 end customer takes a money-relevant action. The two-step shape supports that pattern. If you always start it immediately, treat not_started as a transient state your UI never displays.

Can I see the rejected document images? No. The images stay with the verification provider. BlendFi receives only the verdict and the rejection reason. It's an intentional privacy boundary.

The end customer passed KYC in another product I operate, can I skip BlendFi's KYC? No. We reverify per BlendFi organization, regardless of whether the same end customer was verified elsewhere. Regulatory requirement.

Do I need any call for the crypto KYC? No. Crypto KYC is initiated automatically after platform KYC is approved. You only observe the result when an offramp operation fails with crypto_kyc_required, crypto_kyc_pending, or crypto_kyc_declined, which are edge situations.