Core Concepts

Lists

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

TypeValue schemaMatch method
namefirst_name, last_name, date_of_birthFuzzy name + exact DOB
emailemail (optional: match_domain_only)Exact or domain-only
phonephoneNormalized exact (last 10 digits)
ip_addressipExact match
government_idid_number, id_classNormalized exact
countrycountry_codeExact match
geolocationlatitude, longitude, radius_metersGeo-radius
browser_fingerprintfingerprint_hashExact hash match
device_fingerprintfingerprint_hashExact hash match
faceembedding, image_urlCosine similarity
fieldfield_key, field_valueExact match on key:value pair
stringvalueExact match

Match modes

Each list operates in one of three modes:

ModeBehavior
blockAutomatically fail the check_against_list check when a match is found.
flagRecord the match but don’t fail the check. The match appears in the review queue.
allowMark the match as trusted. Can be used to bypass certain checks.

Creating a list

$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"
>  }'
1{
2  "id": "list_abc123",
3  "name": "Known Fraudsters",
4  "list_type": "name",
5  "match_mode": "block",
6  "item_count": 0,
7  "is_active": true,
8  "created_at": "2026-02-01T12:00:00Z"
9}

Adding items

Single item

$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:

$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

$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 typeRequired columns
namefirst_name, last_name, date_of_birth
emailemail
phonephone
ip_addressip
government_idid_number, id_class
countrycountry_code
geolocationlatitude, longitude, radius_meters

Maximum 1,000 rows per CSV import.

CSV export

$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:

$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:

$curl https://api.withverifa.com/api/v1/sessions/session_abc123/list-matches \
>  -H "X-API-Key: vk_live_your_key_here"
1{
2  "data": [
3    {
4      "id": "lmatch_abc123",
5      "list_id": "list_abc123",
6      "list_type": "name",
7      "match_type": "fuzzy",
8      "match_score": 0.95,
9      "is_false_positive": false
10    }
11  ]
12}

Mark as false positive

$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

$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

$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:

$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:

TypeNormalization
NamesLowercased, trimmed
EmailsLowercased, trimmed
PhonesStripped to last 10 digits (removes country codes)
Government IDsUppercased, whitespace and dashes stripped
CountriesUppercased to ISO 3166-1 alpha-2

Using lists in workflows

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

1{
2  "type": "policy",
3  "policy": "check_against_list",
4  "config": {
5    "list_ids": ["list_abc123", "list_def456"]
6  },
7  "on_pass": "next_step",
8  "on_fail": "review_terminal"
9}

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