For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
  • Getting Started
    • Introduction
    • How Verifa Works
    • Quickstart
    • Choosing an Integration Method
  • Use Cases
    • KYC Onboarding
    • Age Verification
    • AML Compliance
    • Fraud Prevention
    • Marketplace Trust & Safety
  • Core Concepts
    • Overview
    • Sessions
    • Verifications & Checks
    • Workflows
    • Identities
    • Cases
    • Screening & Reports
    • Lists
  • Integration Guides
    • Overview
    • JavaScript SDK
    • Web Capture Flow
    • API-Only Integration
    • Mobile SDK
    • Webhooks Guide
    • MCP Server
    • Migrating from Persona
  • API Details
    • Overview
    • Authentication
    • Pagination
    • Rate Limiting
    • Versioning
    • Errors
    • Webhooks
    • Idempotency
    • Key Inflection
    • Data Access
    • Data Retention
  • Tutorials
    • Creating Your First Verification Session
    • Creating a Workflow
    • Receiving Webhooks & Validating Signatures
    • Handling Webhook Events
    • Custom Document Types & AI Extraction
  • Best Practices
    • Testing
    • Preventing Duplicates
    • Fraud Signals
    • Changelog
  • API Reference
On this page
  • List types
  • Match modes
  • Creating a list
  • Adding items
  • Single item
  • Bulk import
  • CSV import
  • CSV export
  • Checking against lists
  • Match results
  • Mark as false positive
  • List management
  • Update a list
  • Archive a list
  • View workflow usage
  • Data encryption
  • Normalization
  • Using lists in workflows
  • Related
Core Concepts

Lists

Was this page helpful?
Previous

Integration Guides

Next
Built with

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.

Related

  • Verifications & Checks — The check_against_list policy
  • Screening & Reports — Built-in watchlist screening
  • Workflows — Configure list checks in your pipeline