API ReferenceChecks

Create a check

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`) 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
Your external reference for the subject. Used to link checks to an identity.
name_firststringOptional
Subject's first name. Required for AML check types.
name_laststringOptional
Subject's last name. Required for AML check types.
birthdatestringOptional

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

country_codestringOptional

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

emailstringOptionalformat: "email"

Required for email_risk and email_risk_enhanced checks.

phonestringOptional

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

ip_addressstringOptionalformat: "ipv4"

Required for ip_risk checks. IPv4 or IPv6.

addressobjectOptional

Required for address_validation checks.

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 watchlists via ComplyAdvantage - **Risk**: `email_risk`, `phone_risk`, `ip_risk` — lightweight risk scoring - **Enhanced**: `email_risk_enhanced`, `phone_risk_enhanced`, `address_validation` — 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

The screening provider used (e.g., comply_advantage, ipqs, telesign, smarty).

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