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

# Address Extraction

> Automatically extract and validate address data from proof-of-address documents.

Address Extraction uses OCR and AI to automatically extract structured address fields from proof-of-address (PoA) documents, cross-reference the name against the identity document, and check document recency.

## Supported Documents

| Document Type      | Code                 | Notes                                            |
| ------------------ | -------------------- | ------------------------------------------------ |
| Utility bill       | `utility_bill`       | Electric, gas, water, internet, phone            |
| Bank statement     | `bank_statement`     | Checking, savings, credit card statements        |
| Tax document       | `tax_document`       | Tax returns, tax assessments                     |
| Government letter  | `government_letter`  | Official correspondence from government agencies |
| Insurance document | `insurance_document` | Home, health, or auto insurance statements       |
| Rental agreement   | `rental_agreement`   | Lease or tenancy agreements                      |

## How It Works

<Steps>
  <Step title="Upload PoA document">
    The user uploads a proof-of-address document through the hosted flow or via `POST /v1/sessions/{id}/address-proof`.
  </Step>

  <Step title="OCR extraction">
    AI extracts the full name, address components, document date, and issuer from the document.
  </Step>

  <Step title="Name cross-reference">
    The extracted name is compared against the name on the identity document to verify they belong to the same person.
  </Step>

  <Step title="Recency check">
    The document date is checked against the configured maximum age (default: 90 days).
  </Step>
</Steps>

## Extracted Fields

| Field            | Type   | Description                                  |
| ---------------- | ------ | -------------------------------------------- |
| `full_name`      | string | Full name as it appears on the document      |
| `address_line_1` | string | Primary street address                       |
| `address_line_2` | string | Apartment, suite, unit (if present)          |
| `city`           | string | City or town                                 |
| `state`          | string | State, province, or region                   |
| `postal_code`    | string | ZIP or postal code                           |
| `country`        | string | ISO 3166-1 alpha-2 country code              |
| `document_date`  | string | Date on the document (ISO 8601)              |
| `document_type`  | string | Detected document type                       |
| `issuer`         | string | Document issuer (e.g., utility company name) |

## Configuration

Set address verification requirements when creating a session:

```json theme={null}
{
  "profile": {
    "steps": ["document", "selfie", "address_proof"],
    "address_proof": {
      "max_age_days": 90,
      "name_match_threshold": 0.8,
      "accepted_types": ["utility_bill", "bank_statement", "tax_document"]
    }
  }
}
```

| Field                  | Type    | Default | Description                         |
| ---------------------- | ------- | ------- | ----------------------------------- |
| `max_age_days`         | integer | `90`    | Maximum document age in days        |
| `name_match_threshold` | number  | `0.8`   | Minimum name similarity score (0-1) |
| `accepted_types`       | array   | all     | Restrict accepted document types    |

## API Response

Address extraction data is included in the session detail response:

```json theme={null}
{
  "id": "ses_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "approved",
  "address_proof": {
    "status": "verified",
    "document_type": "utility_bill",
    "issuer": "British Gas",
    "document_date": "2026-02-15",
    "recency_check": {
      "passed": true,
      "max_age_days": 90,
      "document_age_days": 31
    },
    "name_match": {
      "passed": true,
      "extracted_name": "John A. Smith",
      "document_name": "John Alexander Smith",
      "similarity_score": 0.94
    },
    "extracted_address": {
      "address_line_1": "42 Baker Street",
      "address_line_2": "Flat 3",
      "city": "London",
      "state": "Greater London",
      "postal_code": "NW1 6XE",
      "country": "GB"
    },
    "extracted_at": "2026-03-18T10:00:00Z"
  }
}
```

## Response Fields

| Field                             | Type    | Description                                    |
| --------------------------------- | ------- | ---------------------------------------------- |
| `status`                          | string  | `verified`, `failed`, or `pending`             |
| `document_type`                   | string  | Detected PoA document type                     |
| `issuer`                          | string  | Document issuer name                           |
| `document_date`                   | string  | Date on the document                           |
| `recency_check.passed`            | boolean | Whether the document meets the age requirement |
| `recency_check.document_age_days` | integer | Document age in days                           |
| `name_match.passed`               | boolean | Whether the name matches the identity document |
| `name_match.similarity_score`     | number  | Name similarity score (0-1)                    |
| `extracted_address`               | object  | Structured address fields                      |

<Warning>
  Address extraction accuracy depends on document quality. Blurry, low-resolution, or partially cropped documents may produce incomplete results.
</Warning>

<Tip>
  Use the `name_match_threshold` setting to adjust sensitivity. A lower threshold (e.g., 0.7) is more forgiving of name variations like abbreviations and middle names.
</Tip>