The Verification Flow

Step-by-Step Sequence

Create Entity with PII

Create an Entity with at minimum a name and phone number. If you’re using the API-driven flow (not Opal), providing more PII (DOB, SSN, address) significantly improves match rates. Opal collects PII directly from the user during its flow, so upfront PII is less critical when using Opal. See Maximizing Success.

Check available verification methods

Inspect entity.verification.phone.methods and entity.verification.identity.methods to see which verification methods are available for this Entity.

Create phone verification session

Choose a phone verification method (SMS, SNA, or BYO SMS) and create a verification session.

Complete phone verification

Complete the phone verification using the method-specific flow (submit SMS code, process SNA URLs, or report BYO result).

Create identity verification session

Once phone is verified, teams authorized for BYO KYC can report the result of their own identity checks through an identity verification session. Opal handles identity verification within its embedded flow. Creating the session before phone verification is complete returns MISSING_PHONE_VERIFICATION. If Method cannot match the Entity’s PII, it returns MISSING_IDENTITY_MATCH.

Complete identity verification

Complete the Opal flow or create the BYO KYC session to record the result of your own identity checks.

Entity is verified

Entity is now matched + verified. Proceed to Connect, Payments, or other products.

State Diagram

[Entity created] → [Phone: unverified] → [Phone: verified] → [Identity: unverified] → [Identity: matched + verified] → [Products unlocked]

Each verification session goes through its own lifecycle:

pending → in_progress → verified (success)
                       → failed (expired, incorrect code, SNA failure)

Webhooks

Subscribe to verification session events to track progress:

entity_verification_session.create — Fired when a new verification session is created.
entity_verification_session.update — Fired when a session’s status changes (e.g., pending → verified, pending → failed).

These events allow you to build reactive flows — for example, unlocking the next step of your onboarding when phone verification completes.

Code Walkthroughs

The API examples below use BYO KYC. Your team must be authorized to use it and must verify the person through its own identity process before reporting a result.

SMS + BYO KYC

# 1. Create an Entity
curl -X POST https://production.methodfi.com/entities \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "individual": {
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "+15551234567",
      "dob": "1990-01-15"
    }
  }'

# 2. Create SMS phone verification session
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sms",
    "sms": {}
  }'

# 3. User receives SMS code, submit it
curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_xxx \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sms",
    "sms": { "sms_code": "123456" }
  }'

# 4. Report the result of your own identity verification
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity",
    "method": "byo_kyc",
    "byo_kyc": {}
  }'

# Entity is now verified — proceed to Connect or other products

SNA + BYO KYC

# 1. Create Entity (same as above)

# 2. Create SNA phone verification session
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sna",
    "sna": {}
  }'
# Response includes SNA URLs — open them via background request on the user's device

# 3. Update SNA session to check verification status
curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_xxx \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sna",
    "sna": {}
  }'
# If SNA fails, fall back to SMS (create a new session with method "sms")

# 4. Report BYO KYC identity verification (same as above)

BYO SMS + BYO KYC (existing infrastructure path)

# 1. Create Entity (same as above)

# 2. Report BYO SMS phone verification
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "byo_sms",
    "byo_sms": {
      "timestamp": "2026-04-10T12:00:00.000Z"
    }
  }'

# 3. Report BYO KYC identity verification
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity",
    "method": "byo_kyc",
    "byo_kyc": {}
  }'

# Entity is now verified

Getting Started

Entities

Identity Verification

Connect

Accounts

Updates

Payments

Additional Products

Use Cases: Commerce

Use Cases: Lending

Use Cases: PFM

The Verification Flow