Skip to main content

​
The Verification Flow

​
Step-by-Step Sequence

1

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.
2

Check available verification methods

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

Create phone verification session

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

Complete phone verification

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

Create identity verification session

Once phone is verified, create an identity verification session (KBA or BYO KYC). This will fail with MISSING_PHONE_VERIFICATION if phone verification is not complete, or MISSING_IDENTITY_MATCH if Method couldn’t match the Entity’s PII.
6

Complete identity verification

Complete the identity verification using the method-specific flow (submit KBA answers or report BYO KYC result).
7

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/answer, 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

​
SMS + KBA (most common API-driven path)

# 1. Create an Entity
curl -X POST https://production.methodfi.com/entities \
  -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 "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 "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sms",
    "sms": { "sms_code": "123456" }
  }'

# 4. Create KBA identity verification session (returns questions)
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity",
    "method": "kba",
    "kba": {}
  }'

# 5. Present questions to user, then submit answers
curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_yyy \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity",
    "method": "kba",
    "kba": {
      "answers": [
        { "question_id": "qtn_aaa", "answer_id": "ans_bbb" },
        { "question_id": "qtn_ccc", "answer_id": "ans_ddd" }
      ]
    }
  }'

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

​
SNA + KBA (best UX path)

# 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 "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 "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-5. Proceed with KBA 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 "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 "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity",
    "method": "byo_kyc",
    "byo_kyc": {}
  }'

# Entity is now verified