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

**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](https://docs.methodfi.com/guides/identity-verification/maximizing-success.md).

**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, 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`.

**6. Complete identity verification**

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

**7. Entity is verified**

Entity is now matched + verified. Proceed to [Connect](https://docs.methodfi.com/guides/connect/overview.md), [Payments](https://docs.methodfi.com/guides/payments/overview.md), 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

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

```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 "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)

```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 "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
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.