KYC Onboarding

Know Your Customer (KYC) onboarding is the process of verifying a new customer’s identity before granting them access to your product. Financial institutions, fintechs, crypto exchanges, and lending platforms are required by regulation to verify customer identities — but any platform handling sensitive data or transactions benefits from KYC.

What Verifa handles

A KYC onboarding workflow in Verifa typically includes these checks:

Steps 3–5 run automatically on every session — Verifa inserts them into your workflow behind the scenes. You’ll see them listed under “Runs automatically on every session” on your workflow detail page.

For enhanced compliance, you can also add these optional checks to your workflow:

• aml_screening — Screens against 6,000+ global watchlists including PEP databases and adverse media (Professional plan and above)
• duplicate_detection — Catches repeat applicants using the same device, face, document, or contact details
• email_risk_enhanced / phone_risk_enhanced — Validates contact info for fraud signals

Quick implementation

1. Create a session

Include an external_ref — this is your internal user ID and is used to automatically create an identity record when the session completes.

$
curl -X POST https://api.withverifa.com/api/v1/sessions \
>
  -H "X-API-Key: vk_live_your_key_here" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "external_ref": "user_abc123",
>
    "country": "US",
>
    "workflow_id": "wf_kyc_standard"
>
  }'

2. User completes verification

Send the user to capture_url. They will:

1. Give consent for identity verification
2. Select their document type (passport, driver’s license, or national ID)
3. Photograph the front (and back, if applicable) of their ID
4. Take a selfie for biometric matching
5. Fill in any required user information fields (if configured in your workflow)

3. Handle the result

Listen for the session.approved or session.declined webhook, then fetch the full result:

$
curl https://api.withverifa.com/api/v1/results/session_abc123 \
>
  -H "X-API-Key: vk_live_your_key_here"

1
{
2
  "session_id": "session_abc123",
3
  "external_ref": "user_abc123",
4
  "status": "approved",
5
  "result": {
6
    "face_match_passed": true,
7
    "face_match_score": 0.94,
8
    "age_check_passed": true,
9
    "extracted_age": 28,
10
    "extracted_data": {
11
      "first_name": "Jane",
12
      "last_name": "Doe",
13
      "date_of_birth": "1997-06-15",
14
      "address": "123 Main St, San Francisco, CA 94102",
15
      "document_type": "drivers_license",
16
      "document_number": "D1234567",
17
      "document_expiration_date": "2028-06-15"
18
    }
19
  },
20
  "processing_mode": "workflow",
21
  "created_at": "2026-01-15T12:05:00Z"
22
}

4. Identity is created automatically

When a session completes, Verifa automatically creates (or updates) an identity record linked to the external_ref you provided. This identity stores the verified data and serves as the anchor for:

• Future re-verification sessions
• Continuous AML monitoring (if enabled)
• Duplicate detection across sessions

You can retrieve the identity at any time:

$
curl https://api.withverifa.com/api/v1/identities?external_ref=user_abc123 \
>
  -H "X-API-Key: vk_live_your_key_here"

Recommended workflow

For standard KYC onboarding, build a workflow with these steps:

Capture → Document Scan → Face Match → Auto-Approve

Watchlist screening, risk assessment, and identity cross-reference run automatically — you don’t need to add them.

For high-risk verticals (crypto, lending), add more checks:

Capture → Document Scan → Face Match → AML Screening
  → Duplicate Detection → Auto-Approve

See the Creating a Workflow tutorial for a step-by-step walkthrough of building a workflow in the dashboard.

Risk-based routing

Use conditional nodes to route high-risk sessions to manual review:

1
{
2
  "risk_gate": {
3
    "type": "conditional",
4
    "routes": [
5
      {
6
        "conditions": [
7
          { "field": "risk_assessment.risk_level", "op": "==", "value": "critical" }
8
        ],
9
        "target": "reject_terminal"
10
      },
11
      {
12
        "conditions": [
13
          { "field": "risk_assessment.risk_level", "op": "in", "value": ["high", "medium"] }
14
        ],
15
        "target": "review_terminal"
16
      },
17
      {
18
        "conditions": [],
19
        "target": "approve_terminal"
20
      }
21
    ]
22
  }
23
}

Handling edge cases

Document not accepted

If a user submits an unsupported document type, the document_ocr check fails with a requires_retry status. The capture flow automatically prompts them to try again (up to 4 retries).

Needs manual review

Sessions routed to needs_review appear in the Cases dashboard. Assign reviewers, add notes, and approve or reject with a full audit trail.

Re-verification

For periodic KYC refresh (common in financial services), create a new session with the same external_ref. Verifa automatically links it to the existing identity:

$
curl -X POST https://api.withverifa.com/api/v1/sessions \
>
  -H "X-API-Key: vk_live_your_key_here" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "external_ref": "user_abc123",
>
    "country": "US"
>
  }'

The new session’s results will update the existing identity record when it completes.

Compliance mapping

Related

• Tutorial: Creating a Workflow — Build a workflow step by step
• Quickstart — Create your first session in 5 minutes
• Sessions — Full session lifecycle and API
• Identities — How identity records work
• Screening & Reports — AML screening details
• Cases — Manual review workflow
• Workflows — Customize the verification pipeline