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.

1

Get an API key

Sign in to the dashboard and create a key. Free accounts include 50 screens/month.

2

Call POST /v1/screen

bash
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"
  }'
3

Read the verdict and risk

The response returns a top-level verdict, risk_level, and recommended_action.

json
{
  "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…"
}
4

Retrieve the Evidence Capsule

bash
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

namereq

Person or entity name to screen.

type

Filter to "person" or "entity". Improves precision.

country

ISO 3166-1 alpha-2 country hint. Reduces false positives on common names.

date_of_birth

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

bash
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.

json
{
  "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_severity

primary | secondary | pep | watchlist — the regulatory weight of the list.

source_freshness_hours

Hours since the matching source was last successfully synced.

decision_hash

Deterministic SHA-256 derived from input + match + source version.

evidence_capsule_url

URL to retrieve the full Evidence Capsule for audit review.

missing_fields

Fields absent from the query that would increase confidence.

match_type

EXACT | 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.

clear

No matches found, or matches were auto-cleared due to low confidence or PEP-only classification. Proceed.

possible_match

A match was found but key disambiguation fields (country, date of birth, entity type) are missing. Manual review is recommended.

confirmed_match

High-confidence match on a primary sanctions source with strong identity signals. Escalate to compliance immediately.

uncertain

The 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.

bash
curl https://api.verifex.dev/v1/evidence-capsules/cap_01hxz… \
  -H "Authorization: Bearer vfx_your_api_key"
evidence_capsule_id
verdict + risk_score + identity_confidence
source_type + source_severity + source_freshness_hours
original_input + normalised_query
match_rationale (penalty chain)
engine_version + list_version
decision_hash (SHA-256, deterministic)
recommended_action + human_review_required

Evidence 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.

POST/v1/screen

Screen a person or entity

Single-request sanctions and PEP screening with confidence, risk level, aliases, source attribution, and request ID.

POST/v1/screen/entity

Entity + UBO screening

Corporate sanctions screening plus ownership-chain context where GLEIF data is available.

POST/v1/screen/batch

Batch screening

Submit multiple names in one request. Plan-gated batch size limits.

GET/v1/entities/search

Canonical entity search

Search the normalized entity graph for transliterations, variants, and canonical IDs.

GET/v1/evidence-capsules/{id}

Retrieve Evidence Capsule

Get the full audit snapshot for a screening decision by its capsule ID.

GET/v1/health

Health 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

Example
javascript
import { 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

Example
javascript
from 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

Example
javascript
import (
    "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

Example
javascript
use 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

Example
bash
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"
  }'

JavaScript (fetch)

Example
javascript
const 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)

Example
javascript
import 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)

Example
javascript
package 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)

Example
javascript
use 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.