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.

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.

explain

When 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

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

Live Playground

No API key required — uses public sandbox

Audit & 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_confidence

Final confidence (0–100) after temperature scaling (T=0.20).

feature_contributions

Per-field breakdown — name, DOB, country, type, identifier — with percentage contribution and comparison level.

threshold_reasoning

Decision band: AUTO_CLEAR, REVIEW, ESCALATE, or BLOCK — with human-readable rationale.

evidence_summary

Human-readable per-field evidence descriptions.

calibration

Raw vs. calibrated confidence and the temperature factor used.

Example response with explain

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

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. PEP-only hits return MATCH (not CLEAR) for enhanced due diligence review.

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.

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.

bash
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

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

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.

POST/v1/adverse-media/screen

Adverse 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

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.

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.

401invalid_api_key

The API key you provided is invalid. Keys look like vfx_sk_live_... — check your dashboard.

https://docs.verifex.dev/authentication
402quota_exceeded

You've used all your screens this month. Upgrade to get more.

https://docs.verifex.dev/plans
429rate_limit_exceeded

You've hit the rate limit. Slow down or upgrade your plan for higher limits.

https://docs.verifex.dev/rate-limits
400validation_error

name is required — provide the name of the person or entity to screen.

https://docs.verifex.dev/api/screen
403account_disabled

Your account has been disabled. Contact support for assistance.

https://docs.verifex.dev/support
500internal_error

An unexpected error occurred. Include the request_id when contacting support.

https://docs.verifex.dev/support

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