Developer Documentation
Build screening workflows with reviewable audit evidence.
Verifex lets developers screen sanctions, PEP, 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
96.6% F1 · 100% recall
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.
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"
}'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 or PEP-only classification. Proceed.
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.
Endpoints
Core API endpoints
Four 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.
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.
REST 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: 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.