Developer Documentation
Build screening workflows with reviewable audit evidence.
Verifex lets developers screen sanctions, PEP, adverse media, and entity-risk data while preserving match reasoning, list context, timestamps, and Evidence Capsules for every decision.
Base URL
https://api.verifex.dev
Auth
Bearer token (vfx_…)
Format
JSON over HTTPS
Benchmark
99.68% F1 · 99.36% recall (v3, 500-case)
Quickstart
Your first screening in four steps
Authenticate with a Bearer token, POST a name and type, read the structured verdict, and retrieve the Evidence Capsule.
Get an API key
Sign in to the dashboard and create a key. Free accounts include 50 screens/month.
Call POST /v1/screen
curl -X POST https://api.verifex.dev/v1/screen \
-H "Authorization: Bearer vfx_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Alejandro García López",
"type": "person",
"country": "MX",
"mode": "broad"
}'Read the verdict and risk
The response returns a top-level verdict, risk_level, and recommended_action.
{
"verdict": "possible_match",
"risk_level": "medium",
"risk_score": 62,
"recommended_action": "review_if_policy_requires",
"human_review_required": true,
"total_matches": 1,
"request_id": "scr_01hxz…",
"screened_at": "2026-05-09T12:00:00.000Z",
"evidence_capsule_id": "cap_01hxz…",
"evidence_capsule_url": "/v1/evidence-capsules/cap_01hxz…"
}Retrieve the Evidence Capsule
curl https://api.verifex.dev/v1/evidence-capsules/cap_01hxz… \
-H "Authorization: Bearer vfx_your_api_key"Authentication
Bearer tokens
Every endpoint except /v1/health requires a Bearer token in the Authorization header.
Authorization: Bearer vfx_…Tokens are generated in the dashboard and scoped to your account plan. Free accounts are rate-limited to 10 requests/minute and 50 screens/month.
Core endpoint
POST /v1/screen
Screen a single name against the configured sanctions, PEP, and watchlist sources available to your plan.
Request body
namereqPerson or entity name to screen.
typeFilter to "person" or "entity". Improves precision.
countryISO 3166-1 alpha-2 country hint. Reduces false positives on common names.
date_of_birthYYYY-MM-DD or YYYY. Increases confidence on person matches.
mode"exact" for strict direct-name matching, "broad" for fuzzy and phonetic.
threshold"strict", "balanced", or "broad" confidence profile.
explainWhen true, returns v3 feature-engineering explainability data for each match: calibrated confidence, per-field contributions, threshold reasoning, and evidence summary. Adds ~0.05ms per match.
Example request
curl -X POST https://api.verifex.dev/v1/screen \
-H "Authorization: Bearer vfx_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Alejandro García López",
"type": "person",
"country": "MX",
"mode": "broad"
}'Live Playground
No API key required — uses public sandboxAudit & transparency
Explainability (explain=true)
Add explain: true to any screening request to receive a v3_explainability object on every match. Designed for compliance auditors, risk analysts, and ML engineers who need to understand why a match was produced.
What you get
calibrated_confidenceFinal confidence (0–100) after temperature scaling (T=0.20).
feature_contributionsPer-field breakdown — name, DOB, country, type, identifier — with percentage contribution and comparison level.
threshold_reasoningDecision band: AUTO_CLEAR, REVIEW, ESCALATE, or BLOCK — with human-readable rationale.
evidence_summaryHuman-readable per-field evidence descriptions.
calibrationRaw vs. calibrated confidence and the temperature factor used.
Example response with explain
{
"matches": [{
"id": "ofac-sdn-15547",
"name": "Rosneft Oil Company",
"confidence": 98,
"risk_level": "critical",
"v3_explainability": {
"human_readable": "OFAC SDN entry with 94.5% calibrated confidence. Primary name exhibits strong similarity.",
"calibrated_confidence": 94.5,
"feature_contributions": [
{ "field": "name", "level": "exact_full", "contribution_percent": 74.2 },
{ "field": "date_of_birth", "level": "exact", "contribution_percent": 13.2 }
],
"threshold_reasoning": {
"decision": "BLOCK",
"explanation": "Confidence 94.5% exceeds the 90% BLOCK threshold."
},
"modifiers": [],
"calibration": {
"temperature": 0.2,
"raw_confidence": 97.2,
"calibrated_confidence": 94.5
},
"evidence_summary": {
"name": "High similarity between query and listed name.",
"date_of_birth": "Full DOB match.",
"country": "Matches listed nationality.",
"entity_type": "Entity types align.",
"identifier": "No identifier comparison performed."
}
}
}]
}Response
Reading the result
Every match carries identity confidence, source classification, and a link to the Evidence Capsule.
{
"query": {
"name": "Alejandro García López",
"type": "person",
"country": "MX",
"mode": "broad"
},
"verdict": "possible_match",
"risk_level": "medium",
"risk_score": 62,
"risk_tier": "review",
"recommended_action": "review_if_policy_requires",
"human_review_required": true,
"total_matches": 1,
"request_id": "scr_01hxz…",
"screened_at": "2026-05-09T12:00:00.000Z",
"missing_fields": ["date_of_birth"],
"evidence_capsule_id": "cap_01hxz…",
"evidence_capsule_url": "/v1/evidence-capsules/cap_01hxz…",
"matches": [{
"id": "match_01hxz…",
"name": "GARCIA LOPEZ, Alejandro",
"source": "OFAC",
"source_type": "sanctions",
"source_severity": "primary",
"confidence": 87,
"match_type": "FUZZY",
"risk_level": "high",
"programs": ["SDGT"],
"aliases": ["GARCIA, A."],
"decision_hash": "sha256:a3f8…c91b",
"evidence_capsule_url": "/v1/evidence-capsules/cap_01hxz…"
}]
}source_severityprimary | secondary | pep | watchlist — the regulatory weight of the list.
source_freshness_hoursHours since the matching source was last successfully synced.
decision_hashDeterministic SHA-256 derived from input + match + source version.
evidence_capsule_urlURL to retrieve the full Evidence Capsule for audit review.
missing_fieldsFields absent from the query that would increase confidence.
match_typeEXACT | FUZZY | PHONETIC — which matching stage produced the hit.
Verdicts
Understanding screening verdicts
The Trust Layer derives verdict, risk_score, and recommended_action from identity confidence, source severity, and evidence sufficiency as separate signals.
clearNo matches found, or matches were auto-cleared due to low confidence. PEP-only hits return MATCH (not CLEAR) for enhanced due diligence review.
possible_matchA match was found but key disambiguation fields (country, date of birth, entity type) are missing. Manual review is recommended.
confirmed_matchHigh-confidence match on a primary sanctions source with strong identity signals. Escalate to compliance immediately.
uncertainThe screening engine could not reach a confident conclusion. Review is recommended.
Important: possible_match is not a confirmed match
A possible_match means the system found a name similarity but lacks sufficient disambiguation data (such as country, date of birth, or entity type) to confirm identity. Always apply your own policy before taking action. Verifex provides screening evidence and decision support — it does not provide legal advice or final compliance determinations.
PEP vs sanctions
A source_severity: "pep" result comes from a Politically Exposed Person list. PEP hits require enhanced due diligence under most AML frameworks — but they are not sanctions block obligations. Verifex separates source_severity from confidence so compliance teams can apply the right policy for each source type.
Evidence Capsule
Retrievable audit evidence for every decision
An Evidence Capsule is a structured JSON snapshot of a screening decision — the original input, normalized query, match rationale, source metadata, engine version, and decision hash.
curl https://api.verifex.dev/v1/evidence-capsules/cap_01hxz… \
-H "Authorization: Bearer vfx_your_api_key"evidence_capsule_idverdict + risk_score + identity_confidencesource_type + source_severity + source_freshness_hoursoriginal_input + normalised_querymatch_rationale (penalty chain)engine_version + list_versiondecision_hash (SHA-256, deterministic)recommended_action + human_review_requiredEvidence Capsules support audit review and regulatory inquiry. They are not legal advice, regulatory approval, or final compliance determinations.
Adverse Media
Screen individuals and companies against real-time news
POST /v1/adverse-media/screen fetches recent news articles from GDELT DOC 2.0, classifies them with Claude Haiku 4.5 into 7 risk categories, and returns per-article confidence scores with human-readable reasoning.
curl -X POST https://api.verifex.dev/v1/adverse-media/screen \
-H "Authorization: Bearer vfx_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"entity": "Acme Corporation",
"entityType": "COMPANY",
"context": {
"country": "US",
"industry": "pharmaceuticals"
}
}'Response
{
"overallRisk": "MEDIUM",
"riskScore": 42,
"articlesFlagged": 3,
"articlesReviewed": 20,
"cached": false,
"llmCost": 0.009,
"quota": {
"used": 12,
"limit": 50,
"remaining": 38
},
"results": [
{
"title": "Acme Corp fined $2M for compliance violations",
"url": "https://example.com/article/123",
"publishedDate": "2026-05-15T10:30:00Z",
"source": "Reuters",
"riskCategory": "HIGH",
"confidence": 0.91,
"reasoning": "Article describes a regulatory fine directly tied to the entity. High relevance, strong entity match.",
"entityMatchConfidence": 0.95
}
]
}Plan access
Growth+ (50/mo), Pro (200/mo), Enterprise (unlimited)
Cache
Redis 24h (GDELT) + 7d (LLM). Zero quota on cache hits.
LLM fallback
Returns CLEAR + llmFailed: true on failure. Zero quota.
Free and Starter plans receive a 403 response. Growth, Pro, and Enterprise plans are quota-enforced. Overages are billed at $0.15/check (Growth) and $0.10/check (Pro). Enterprise is unlimited.
Endpoints
Core API endpoints
Five endpoints cover the main screening workflows. All use the same authentication and return the same Trust Layer fields.
/v1/screenScreen a person or entity
Single-request sanctions and PEP screening with confidence, risk level, aliases, source attribution, and request ID.
/v1/screen/entityEntity + UBO screening
Corporate sanctions screening plus ownership-chain context where GLEIF data is available.
/v1/screen/batchBatch screening
Submit multiple names in one request. Plan-gated batch size limits.
/v1/entities/searchCanonical entity search
Search the normalized entity graph for transliterations, variants, and canonical IDs.
/v1/evidence-capsules/{id}Retrieve Evidence Capsule
Get the full audit snapshot for a screening decision by its capsule ID.
/v1/healthHealth check
Public health endpoint for service status and connectivity.
/v1/adverse-media/screenAdverse media screening
Screen individuals and companies against real-time news. GDELT fetch + Claude classification into 7 risk categories. Plan-gated.
SDKs
Official SDKs for common backend environments
Use the official SDKs for faster integration, or call the REST API directly from any backend. The API remains REST-first, and every SDK maps to the same documented request and response objects.
Node.js — npm install verifex
Exampleimport { Verifex } from "verifex";
const verifex = new Verifex({ apiKey: "vfx_your_api_key" });
const result = await verifex.screen({
name: "Alejandro García López",
type: "person",
country: "MX",
});
console.log(result.riskLevel, result.totalMatches);Python — pip install verifex
Examplefrom verifex import VerifexClient
client = VerifexClient("vfx_your_api_key")
result = client.screen(
"Alejandro García López",
type="person",
country="MX",
)
print(result.risk_level, result.total_matches)Go — go get github.com/Verifex-dev/verifex-go-sdk
Exampleimport (
"context"
verifex "github.com/Verifex-dev/verifex-go-sdk"
)
client := verifex.New("vfx_your_api_key")
result, err := client.Screen(context.Background(), verifex.ScreenRequest{
Name: "Alejandro García López",
Type: "person",
})
fmt.Println(result.RiskLevel, result.TotalMatches)Rust — cargo add verifex
Exampleuse verifex::{Verifex, ScreenRequest};
let client = Verifex::new("vfx_your_api_key");
let result = client
.screen(ScreenRequest {
name: "Alejandro García López".into(),
type_: Some("person".into()),
..Default::default()
})
.await?;
println!("{} — {} matches", result.risk_level, result.total_matches);Choose SDK or REST
Use the official SDKs for faster integration, or call the REST API directly from any backend. The API remains REST-first, and every SDK maps to the same documented request and response objects.
Errors
Stripe-style error responses
Every error includes a machine-readable code, a human-readable message, and a docs URL so you know exactly what to do next.
invalid_api_keyThe API key you provided is invalid. Keys look like vfx_sk_live_... — check your dashboard.
https://docs.verifex.dev/authenticationquota_exceededYou've used all your screens this month. Upgrade to get more.
https://docs.verifex.dev/plansrate_limit_exceededYou've hit the rate limit. Slow down or upgrade your plan for higher limits.
https://docs.verifex.dev/rate-limitsvalidation_errorname is required — provide the name of the person or entity to screen.
https://docs.verifex.dev/api/screenaccount_disabledYour account has been disabled. Contact support for assistance.
https://docs.verifex.dev/supportinternal_errorAn unexpected error occurred. Include the request_id when contacting support.
https://docs.verifex.dev/supportREST API
REST API quickstart
Standard HTTP examples for any backend that prefers direct REST calls.
curl
Examplecurl -X POST https://api.verifex.dev/v1/screen \
-H "Authorization: Bearer vfx_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Alejandro García López",
"type": "person",
"country": "MX"
}'JavaScript (fetch)
Exampleconst res = await fetch("https://api.verifex.dev/v1/screen", {
method: "POST",
headers: {
Authorization: "Bearer vfx_your_api_key",
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "Alejandro García López",
type: "person",
country: "MX",
}),
});
const data = await res.json();
console.log(data.verdict, data.risk_level);Python (requests)
Exampleimport requests
res = requests.post(
"https://api.verifex.dev/v1/screen",
headers={
"Authorization": "Bearer vfx_your_api_key",
"Content-Type": "application/json",
},
json={
"name": "Alejandro García López",
"type": "person",
"country": "MX",
},
)
data = res.json()
print(data["verdict"], data["risk_level"])Go (net/http)
Examplepackage main
import (
"bytes"
"encoding/json"
"net/http"
)
body, _ := json.Marshal(map[string]string{
"name": "Alejandro García López",
"type": "person",
"country": "MX",
})
req, _ := http.NewRequest("POST", "https://api.verifex.dev/v1/screen", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer vfx_your_api_key")
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
// resp.Status, decode JSON...Rust (reqwest)
Exampleuse reqwest::Client;
use serde_json::json;
let client = Client::new();
let res = client
.post("https://api.verifex.dev/v1/screen")
.header("Authorization", "Bearer vfx_your_api_key")
.json(&json!({
"name": "Alejandro García López",
"type": "person",
"country": "MX",
}))
.send()
.await?;
let data: serde_json::Value = res.json().await?;Trust & safety
Compliance disclaimer and limitations
Disclaimer: Verifex provides screening evidence and decision support. It does not provide legal advice, regulatory approval, or final compliance determinations. Screening results should be reviewed under your own compliance policy before any action is taken.
Coverage: Verifex screens across 54 configured screening sources with published source attribution and freshness tracking. Coverage depends on enabled sources and plan tier. No screening system can guarantee complete global coverage.
Benchmark: 500-case benchmark: 99.68% F1, 99.36% recall, 100% precision. Legacy v2: 122-case published benchmark: 96.6% f1, 100% recall, 93.4% precision. Results reflect performance on our published benchmark test set, not a guarantee across all production data.
Rate limits: Free accounts are intended for evaluation: 50 screens/month at 10 requests/minute. Usage and quota information is available after sign-in.