> ## Documentation Index
> Fetch the complete documentation index at: https://docs.methodfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Verification Flow

> Step-by-step verification sequence, state transitions, webhooks, and code walkthroughs.

## The Verification Flow

### Step-by-Step Sequence

<Steps>
  <Step title="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](/guides/identity-verification/maximizing-success).
  </Step>

  <Step title="Check available verification methods">
    Inspect `entity.verification.phone.methods` and `entity.verification.identity.methods` to see which verification methods are available for this Entity.
  </Step>

  <Step title="Create phone verification session">
    Choose a phone verification method (SMS, SNA, or BYO SMS) and create a verification session.
  </Step>

  <Step title="Complete phone verification">
    Complete the phone verification using the method-specific flow (submit SMS code, process SNA URLs, or report BYO result).
  </Step>

  <Step title="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.
  </Step>

  <Step title="Complete identity verification">
    Complete the identity verification using the method-specific flow (submit KBA answers or report BYO KYC result).
  </Step>

  <Step title="Entity is verified">
    Entity is now matched + verified. Proceed to [Connect](/guides/connect/overview), [Payments](/guides/payments/overview), or other products.
  </Step>
</Steps>

### 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)

```bash theme={null}
# 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)

```bash theme={null}
# 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)

```bash theme={null}
# 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
```