Skip to navigation
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, 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.
idstringOptional
check_typeenumOptional

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
statusenumOptional

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

Allowed values:
has_matchbooleanOptional
Whether the check found any matches or flagged risk.
hit_countintegerOptional

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

providerstring or nullOptional

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 nullOptional
Associated session ID, if the check was triggered as part of a verification session.
identity_idstring or nullOptional
Associated identity ID, if the check is linked to a known identity.
external_refstring or nullOptional
Your external reference for the subject.
monitoring_enabledbooleanOptional

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

is_sandboxbooleanOptional

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

tagslist of stringsOptional
Custom tags attached to this check.
batch_idstring or nullOptional
Batch ID if this check was created via the bulk endpoint.
pep_risk_tierenumOptional

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

Allowed values:
redacted_atdatetime or nullOptional

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

last_checked_atdatetimeOptional
created_atdatetimeOptional
expires_atdatetimeOptional
resultobject or nullOptional

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 objectsOptional

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

Errors

401
Unauthorized Error
422
Unprocessable Entity Error