> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withverifa.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withverifa.com/_mcp/server.

# Lists

> Custom allow, block, and flag lists for identity matching.

**Lists** are custom collections of data that Verifa matches against during
verification. Use lists to block known fraudsters, flag VIP customers, or allow
trusted identities to skip certain checks.

## List types

| Type                  | Value schema                               | Match method                      |
| --------------------- | ------------------------------------------ | --------------------------------- |
| `name`                | `first_name`, `last_name`, `date_of_birth` | Fuzzy name + exact DOB            |
| `email`               | `email` (optional: `match_domain_only`)    | Exact or domain-only              |
| `phone`               | `phone`                                    | Normalized exact (last 10 digits) |
| `ip_address`          | `ip`                                       | Exact match                       |
| `government_id`       | `id_number`, `id_class`                    | Normalized exact                  |
| `country`             | `country_code`                             | Exact match                       |
| `geolocation`         | `latitude`, `longitude`, `radius_meters`   | Geo-radius                        |
| `browser_fingerprint` | `fingerprint_hash`                         | Exact hash match                  |
| `device_fingerprint`  | `fingerprint_hash`                         | Exact hash match                  |
| `face`                | `embedding`, `image_url`                   | Cosine similarity                 |
| `field`               | `field_key`, `field_value`                 | Exact match on key:value pair     |
| `string`              | `value`                                    | Exact match                       |

## Match modes

Each list operates in one of three modes:

| Mode    | Behavior                                                                          |
| ------- | --------------------------------------------------------------------------------- |
| `block` | Automatically fail the `check_against_list` check when a match is found.          |
| `flag`  | Record the match but don't fail the check. The match appears in the review queue. |
| `allow` | Mark the match as trusted. Can be used to bypass certain checks.                  |

## Creating a list

```bash
curl -X POST https://api.withverifa.com/api/v1/lists \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Known Fraudsters",
    "list_type": "name",
    "match_mode": "block",
    "description": "Identities confirmed as fraudulent"
  }'
```

```json
{
  "id": "list_abc123",
  "name": "Known Fraudsters",
  "list_type": "name",
  "match_mode": "block",
  "item_count": 0,
  "is_active": true,
  "created_at": "2026-02-01T12:00:00Z"
}
```

## Adding items

### Single item

```bash
curl -X POST https://api.withverifa.com/api/v1/lists/list_abc123/items \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "value": {
      "first_name": "John",
      "last_name": "Smith",
      "date_of_birth": "1990-01-15"
    },
    "notes": "Confirmed fraud case #12345"
  }'
```

### Bulk import

Add up to 1,000 items at once:

```bash
curl -X POST https://api.withverifa.com/api/v1/lists/list_abc123/items/bulk \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "value": { "first_name": "John", "last_name": "Smith", "date_of_birth": "1990-01-15" } },
      { "value": { "first_name": "Jane", "last_name": "Doe", "date_of_birth": "1985-03-22" } }
    ]
  }'
```

### CSV import

```bash
curl -X POST https://api.withverifa.com/api/v1/lists/list_abc123/items/import-csv \
  -H "X-API-Key: vk_live_your_key_here" \
  -F "file=@blocklist.csv"
```

CSV columns depend on the list type:

| List type       | Required columns                           |
| --------------- | ------------------------------------------ |
| `name`          | `first_name`, `last_name`, `date_of_birth` |
| `email`         | `email`                                    |
| `phone`         | `phone`                                    |
| `ip_address`    | `ip`                                       |
| `government_id` | `id_number`, `id_class`                    |
| `country`       | `country_code`                             |
| `geolocation`   | `latitude`, `longitude`, `radius_meters`   |

Maximum 1,000 rows per CSV import.

### CSV export

```bash
curl https://api.withverifa.com/api/v1/lists/list_abc123/items/export-csv \
  -H "X-API-Key: vk_live_your_key_here" \
  -o blocklist.csv
```

## Checking against lists

Lists are checked during workflow execution via the `check_against_list` policy.
You can also check manually without persisting results:

```bash
curl -X POST https://api.withverifa.com/api/v1/lists/check \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_data": {
      "first_name": "John",
      "last_name": "Smith",
      "date_of_birth": "1990-01-15",
      "email": "john@example.com"
    },
    "list_ids": ["list_abc123"]
  }'
```

## Match results

When a list match occurs during verification, it's recorded as a match result:

```bash
curl https://api.withverifa.com/api/v1/sessions/session_abc123/list-matches \
  -H "X-API-Key: vk_live_your_key_here"
```

```json
{
  "data": [
    {
      "id": "lmatch_abc123",
      "list_id": "list_abc123",
      "list_type": "name",
      "match_type": "fuzzy",
      "match_score": 0.95,
      "is_false_positive": false
    }
  ]
}
```

### Mark as false positive

```bash
curl -X POST https://api.withverifa.com/api/v1/list-matches/lmatch_abc123/false-positive \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Different person — DOB does not match."
  }'
```

## List management

### Update a list

```bash
curl -X PATCH https://api.withverifa.com/api/v1/lists/list_abc123 \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated List Name",
    "match_mode": "flag"
  }'
```

### Archive a list

```bash
curl -X POST https://api.withverifa.com/api/v1/lists/list_abc123/archive \
  -H "X-API-Key: vk_live_your_key_here"
```

Archiving is blocked if the list is referenced by an active workflow. Remove it
from workflows first.

### View workflow usage

When retrieving a list, the response includes which workflows reference it:

```bash
curl https://api.withverifa.com/api/v1/lists/list_abc123 \
  -H "X-API-Key: vk_live_your_key_here"
```

## Data encryption

All list item data is encrypted at rest using AES-256-GCM encryption. Each
item's value is encrypted before storage and decrypted only when accessed
through the API.

Lookup columns use HMAC-SHA256 hashes for matching, so Verifa can find matches
without ever storing PII in plaintext. Name lists retain a normalized form for
fuzzy matching, but all other data (emails, phone numbers, government IDs, etc.)
is stored only as irreversible hashes and encrypted values.

This means:

* A database breach does not expose list contents.
* Searching for items requires the full, exact value as originally entered.
* CSV exports decrypt data on the fly and are served over HTTPS.

## Normalization

Verifa normalizes list item values for consistent matching:

| Type           | Normalization                                      |
| -------------- | -------------------------------------------------- |
| Names          | Lowercased, trimmed                                |
| Emails         | Lowercased, trimmed                                |
| Phones         | Stripped to last 10 digits (removes country codes) |
| Government IDs | Uppercased, whitespace and dashes stripped         |
| Countries      | Uppercased to ISO 3166-1 alpha-2                   |

## Using lists in workflows

Add the `check_against_list` policy to your workflow graph and reference
specific lists:

```json
{
  "type": "policy",
  "policy": "check_against_list",
  "config": {
    "list_ids": ["list_abc123", "list_def456"]
  },
  "on_pass": "next_step",
  "on_fail": "review_terminal"
}
```

If no `list_ids` are specified, all active lists for the organization are
checked.

## Related

* [Verifications & Checks](/core-concepts/verifications-checks) — The
  `check_against_list` policy
* [Screening & Reports](/core-concepts/screening-reports) — Built-in watchlist
  screening
* [Workflows](/core-concepts/workflows) — Configure list checks in your pipeline