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
      • GETList checks
      • POSTCreate a check
      • POSTCreate multiple checks at once
      • GETGet check detail with hits
      • POSTDismiss AML hits
      • POSTRe-run check
      • POSTGDPR redact check PII
      • GETMonitoring history
      • POSTAdd tags
      • PUTSet tags (replace all)
      • DELRemove a tag
      • GETGenerate PDF report for a check
      • GETList checks for session
      • GETList checks for identity
      • GETList watchlists
      • GETGet a watchlist
      • GETList watchlist items
API ReferenceChecks

Create a check

POST
https://devapi.withverifa.com/api/v1/checks
POST
/api/v1/checks
$curl -X POST https://devapi.withverifa.com/api/v1/checks \
>     -H "X-API-Key: <apiKey>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "check_type": "sanction",
>  "external_ref": "string"
>}'
1{
2  "id": "schk_abc123",
3  "check_type": "sanction",
4  "status": "pending",
5  "has_match": true,
6  "hit_count": 1,
7  "provider": "string",
8  "session_id": "string",
9  "identity_id": "string",
10  "external_ref": "string",
11  "monitoring_enabled": true,
12  "is_sandbox": true,
13  "tags": [
14    "string"
15  ],
16  "batch_id": "string",
17  "pep_risk_tier": "tier_1",
18  "pep_recommended_action": "string",
19  "redacted_at": "2024-01-15T09:30:00Z",
20  "last_checked_at": "2024-01-15T09:30:00Z",
21  "created_at": "2024-01-15T09:30:00Z",
22  "expires_at": "2024-01-15T09:30:00Z",
23  "result": {},
24  "hits": [
25    {
26      "id": "string",
27      "created_at": "2024-01-15T09:30:00Z",
28      "matched_name": "string",
29      "name_similarity": 1.1,
30      "dob_match": true,
31      "combined_score": 1.1,
32      "hit_source": "string",
33      "hit_type": "string",
34      "provider_ref": "string",
35      "deceased": true,
36      "is_false_positive": true,
37      "pep_details": {
38        "sources": [
39          "string"
40        ],
41        "positions": [
42          {
43            "title": "string",
44            "country": "string",
45            "from": "string",
46            "to": "string"
47          }
48        ],
49        "associates": [
50          {
51            "name": "string",
52            "relationship": "string"
53          }
54        ],
55        "pep_class": "string"
56      },
57      "sanction_details": {
58        "sources": [
59          "string"
60        ],
61        "list_name": "string",
62        "program": "string",
63        "listed_on": "string"
64      },
65      "adverse_media_details": {
66        "sources": [
67          {
68            "name": "string",
69            "url": "string",
70            "date": "string"
71          }
72        ]
73      }
74    }
75  ]
76}
Creates an on-demand screening check or risk report against the specified check type. **AML checks** (`sanction`, `pep`, `adverse_media`, `warning`) screen a person against global watchlists including OFAC/SDN, EU/UN/UK sanctions, and PEP databases. Requires `name_first` and `name_last`; optionally include `birthdate` for higher-accuracy matching. PEP checks return a `pep_risk_tier` (critical/high/medium/low) and `pep_recommended_action`. **Risk checks** (`email_risk`, `phone_risk`, `ip_risk`) run basic fraud signal analysis using internal providers. **Enhanced checks** (`email_risk_enhanced`, `phone_risk_enhanced`, `address_validation`, `ssn_verification`) use premium third-party providers for deeper analysis. These require the corresponding feature to be enabled on your plan. Use `POST /checks/full` to run multiple check types in a single request.
Was this page helpful?
Previous

Create multiple checks at once

Next
Built with

Creates an on-demand screening check or risk report against the specified check type.

AML checks (sanction, pep, adverse_media, warning) screen a person against global watchlists including OFAC/SDN, EU/UN/UK sanctions, and PEP databases. Requires name_first and name_last; optionally include birthdate for higher-accuracy matching. PEP checks return a pep_risk_tier (critical/high/medium/low) and pep_recommended_action.

Risk checks (email_risk, phone_risk, ip_risk) run basic fraud signal analysis using internal providers.

Enhanced checks (email_risk_enhanced, phone_risk_enhanced, address_validation, ssn_verification) use premium third-party providers for deeper analysis. These require the corresponding feature to be enabled on your plan.

Use POST /checks/full to run multiple check types in a single request.

Authentication

X-API-Keystring

Organization API key. Keys are prefixed with vk_live_ (production) or vk_sandbox_ (sandbox).

Headers

Verifa-VersiondateOptional

API version date string (e.g. 2026-02-01). If omitted, the version pinned to your API key is used.

Idempotency-KeystringOptional<=255 characters

Unique key for idempotent requests. Cached for 24 hours. Sending the same key with different parameters returns 422.

Request

This endpoint expects an object.
check_typeenumRequired

The type of check to run. AML types require name_first/name_last. Risk types require the relevant input field (email, phone, or ip_address). Enhanced types require plan-level feature enablement.

external_refstringRequired<=255 characters
Your external reference for the subject. Used to link checks to an identity.
name_firststringOptional<=200 characters
Subject's first name. Required for AML check types.
name_laststringOptional<=200 characters
Subject's last name. Required for AML check types.
birthdatedateOptional

Subject’s date of birth (ISO 8601). Improves AML match accuracy.

country_codestringOptional=2 characters

Two-letter country code (ISO 3166-1 alpha-2).

emailstringOptionalformat: "email"<=320 characters

Required for email_risk and email_risk_enhanced checks.

phonestringOptional<=32 characters

Required for phone_risk and phone_risk_enhanced checks. E.164 format.

ip_addressstringOptionalformat: "ipv4"<=45 characters

Required for ip_risk checks. IPv4 or IPv6.

addressobjectOptional

Required for address_validation checks.

ssnstringOptional

Social Security Number. Required for ssn_verification checks. Accepts dashed (123-45-6789) or undashed format. US only. Stored encrypted; never returned in responses.

enable_monitoringbooleanOptionalDefaults to false

Enable continuous monitoring (AML check types only, requires Professional+ plan).

Response

Check created.
idstring
check_typeenum

The type of check. Categories:

  • AML: sanction, pep, adverse_media, warning — screen against global sanctions, PEP, and adverse-media watchlists
  • Risk: email_risk, phone_risk, ip_risk — lightweight risk scoring
  • Enhanced: email_risk_enhanced, phone_risk_enhanced, address_validation, ssn_verification — deep provider-backed analysis
statusenum

Check status. pending = still processing, clear = no matches/low risk, hit = matches found or high risk, error = provider failure.

Allowed values:
has_matchboolean
Whether the check found any matches or flagged risk.
hit_countinteger

Number of screening hits found (AML checks) or 0/1 for risk checks.

providerstring or null

Sanitized provider category for the check (e.g., aml_screening, email_risk, phone_risk, address_verification). Raw vendor identifiers are scrubbed at the API boundary — the underlying vendor name is never exposed to API clients.

session_idstring or null
Associated session ID, if the check was triggered as part of a verification session.
identity_idstring or null
Associated identity ID, if the check is linked to a known identity.
external_refstring or null
Your external reference for the subject.
monitoring_enabledboolean

Whether ongoing monitoring is enabled for this check (AML only).

is_sandboxboolean

Whether this check was created in sandbox mode (uses test data).

tagslist of strings
Custom tags attached to this check.
batch_idstring or null
Batch ID if this check was created via the bulk endpoint.
pep_risk_tierenum

PEP risk classification tier. Only present for pep check type.

Allowed values:
pep_recommended_actionstring or null

Recommended action based on PEP risk tier. Only present for pep check type.

redacted_atdatetime or null

When check data was redacted (GDPR). Only present if redacted.

last_checked_atdatetime
created_atdatetime
expires_atdatetime
resultobject or null

Provider result data. Structure varies by check type:

  • AML: {match_count, highest_score, ...}
  • Risk: {risk_score, risk_level, deliverable, fraud_score, ...}
  • Enhanced: Provider-specific detailed analysis object
hitslist of objects

Screening hits (matches). Only included when fetching check detail.

Errors

401
Unauthorized Error
422
Unprocessable Entity Error