API Reference

Programmatically run sanctions screening, cross-border risk triage, and usage/ops workflows via the external v1 API. Use your API key in the Authorization header. See Authentication for key management and server-only secrets.

Quickstart Authentication Endpoint Catalog OpenAPI v1 JSON API Explorer Full Docs (Dashboard)

Overview

Base URL

https://your-domain.com

Version

Content-Type

application/json

External API coverage

The public customer-facing surface currently includes 29 paths under /api/v1. This page documents core workflows in depth. For every path and method, use the Endpoint Catalog plus Objects & Models or the machine-readable OpenAPI v1 spec. Full operational docs are available in Dashboard Docs.

Required headers

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
Idempotency-Key: <uuid>          # recommended for POST for safe retries

Idempotency: Send a unique Idempotency-Key on POST requests. We will coalesce exact duplicates within a window and return the same result.

POST /api/v1/screen

Screen one or more names. Returns potential matches with confidence, human-readable reasons, and structured evidence (aliases, identifiers, addresses, source links).

Request body

POST /api/v1/screen
{
  "names": string[],                 // required unless "policyQuery" is used
  "entityTypes": string[] | null,    // optional: ["individual","entity","vessel","aircraft","wallet"]
  "sources": string[] | null,        // optional subset of source keys (see /api/v1/datasets). default: all enabled
  "profileKey": string | null,       // optional: "sme_trader_default" | "freight_forwarder_default" | "psp_default"
  "segment": string | null,          // optional: "sme_trader" | "freight_forwarder" | "psp"
  "trigger": string | null,          // optional: "onboarding" | "payment" | "shipment" | "periodic_rescreen" | "event_rescreen"
  "policyQuery": {                   // optional policy-only filter; if provided with empty "names", zero units consumed
    "countries": string[] | null,    // e.g. ["US","EU","UK","CH","CA","AU"]
    "programCodes": string[] | null, // e.g. ["SDGT","SDN","UKR","BELARUS"]
    "keywords": string[] | null      // free-text program/list keywords
  },
  "options": {                       // optional knobs (sensible defaults)
    "maxMatchesPerName": number,     // default 10
    "threshold": number,             // 0..1; default calibrated internal
    "returnRaw": boolean             // include full raw source entry in each match.evidence.raw
  }
}

Supported `entityTypes`

individual
entity
vessel
aircraft
wallet (for blockchain screening, if enabled)

Response

200 OK
{
  "results": [
    {
      "input": "Ali Hassan",
      "isSanctioned": true | false,
      "matches": [
        {
          "source": "EU Sanctions list",
          "sourceKey": "eu",
          "dataset": "EU (FSF)",
          "entityType": "individual",
          "matchedName": "Ali Hassan",
          "matchScore": 0.93,        // 0..1 (1.00 = exact)
          "level": "🟢 Very high confidence",
          "reason": "Exact name match + DOB match + alias overlap",
          "detailsList": [
            { "label": "Date of birth", "value": "1971-05-20" },
            { "label": "Citizenship", "value": "IR" }
          ],
          "evidence": {
            "primaryName": "Ali Hassan",
            "aliases": ["Hassan Ali", "Ali al-Hassan"],
            "identifiers": { "Passport": ["IR12345"] },
            "addresses": ["Tehran, Iran"],
            "nationality": "IR",
            "programs": ["EU-IR"],
            "dates": {
              "Date of birth": "1971-05-20",
              "Date listed": "2012-11-10"
            },
            "sourceUrls": ["https://.../eu_sanctions/entry/123"]
          },
          "raw": { /* optional, if options.returnRaw=true */ }
        }
      ]
    }
  ],
  "policyMatches": [
    /* if policyQuery provided without names */
  ],
  "scannedSources": ["ofac_sdn","eu","uk","un","ch","au","ca"],
  "unavailableSources": [],
  "meta": {
    "tookMs": 124,
    "tenantId": "org_abc",
    "planKey": "pro",
    "policyProfileRequest": {
      "profileKey": "freight_forwarder_default",
      "segment": "freight_forwarder",
      "trigger": "shipment"
    }
  }
}

Examples

cURL Node (fetch)Python (requests)

curl -X POST https://your-domain.com/api/v1/screen \
  -H "Authorization: Bearer $MATCHAUDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "names": ["Vladimir Putin"], "entityTypes": ["individual"], "profileKey": "sme_trader_default", "trigger": "onboarding" }'

export async function screen(names) {
  const res = await fetch("https://your-domain.com/api/v1/screen", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.MATCHAUDIT_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID()
    },
    body: JSON.stringify({
      names,
      entityTypes: ["individual"],
      profileKey: "sme_trader_default",
      trigger: "onboarding"
    })
  });
  if (!res.ok) throw new Error(`Screen failed: ${res.status}`);
  return res.json();
}

import os, uuid, requests
resp = requests.post(
  "https://your-domain.com/api/v1/screen",
  headers={
    "Authorization": f"Bearer {os.getenv('MATCHAUDIT_API_KEY')}",
    "Content-Type": "application/json",
    "Idempotency-Key": str(uuid.uuid4())
  },
  json={
    "names": ["Vladimir Putin"],
    "entityTypes": ["individual"],
    "profileKey": "sme_trader_default",
    "trigger": "onboarding"
  },
  timeout=30
)
print(resp.json())

Field glossary

Field	Type	Description
results[].matches[].matchScore	number (0..1)	Normalized similarity score; 1.00 is exact.
results[].matches[].level	string	Calibrated confidence band (emoji + label).
results[].matches[].reason	string	Human-readable justification for the hit.
results[].matches[].detailsList	array	Flattened key facts shown in the UI (DOB, citizenship, etc.).
results[].matches[].evidence	object	Structured evidence (aliases, identifiers, programs, dates, URLs).
meta.policyProfileRequest	object	Echo of profile/segment/trigger request hints passed to the API.
scannedSources	string[]	Which datasets were actually scanned for this request.
unavailableSources	string[]	Datasets temporarily unavailable during the request.
meta.tookMs	number	Processing time in milliseconds.

Source keys

Source keys are dynamic and reflect the datasets enabled for your tenant. Fetch the current list from GET /api/v1/datasets and pass any subset in sources. If omitted, we scan all enabled datasets for your tenant/plan.

POST /api/v1/cross-border-risk

Run Cross-Border jurisdiction risk triage by country, IP, or location. Returns sanctions, AML, governance assessments, plus a final recommendation (BLOCK / CAUTION / ALLOW).

Request body

POST /api/v1/cross-border-risk
{
  "country": "Germany",          // optional; provide one of country, ip, location
  "ip": "8.8.8.8",               // optional
  "location": "Munich, Germany", // optional
  "jurisdiction": "GLOBAL",      // optional: GLOBAL | US | EU | UK
  "currency": "EUR",             // optional ISO-4217 (3 letters)
  "sector": "Banking"            // optional free text
}

Response

200 OK
{
  "input": { ... },
  "jurisdiction": "GLOBAL",
  "resolved": {
    "country_name": "Germany",
    "country_iso2": "DE",
    "confidence": "HIGH",
    "resolution_method": "LOCATION",
    "region": "Bavaria",
    "city": "Munich",
    "geo_source": "maxmind_city",
    "precision_warning": ""
  },
  "assessments": {
    "sanctions": { "recommendation": "ALLOW", "risk_level": "LOW", "reasons": [] },
    "aml":       { "recommendation": "ALLOW", "risk_level": "LOW", "reasons": [] },
    "governance":{ "recommendation": "CAUTION", "risk_level": "MEDIUM", "reasons": [] }
  },
  "final": {
    "recommendation": "CAUTION",
    "risk_level": "MEDIUM",
    "reasons": ["..."]
  },
  "risk": { ... },
  "meta": {
    "tookMs": 112,
    "tenantId": "org_abc",
    "planKey": "pro"
  }
}

Examples

cURL Node (fetch)Python (requests)

curl -X POST https://your-domain.com/api/v1/cross-border-risk \
  -H "Authorization: Bearer $MATCHAUDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "location": "Donetsk People\'s Republic", "jurisdiction": "GLOBAL", "currency": "USD", "sector": "Defense" }'

export async function getCrossBorderRisk(payload) {
  const res = await fetch("https://your-domain.com/api/v1/cross-border-risk", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.MATCHAUDIT_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  });
  if (!res.ok) throw new Error(`Cross-border risk failed: ${res.status}`);
  return res.json();
}

import os, requests
resp = requests.post(
  "https://your-domain.com/api/v1/cross-border-risk",
  headers={
    "Authorization": f"Bearer {os.getenv('MATCHAUDIT_API_KEY')}",
    "Content-Type": "application/json"
  },
  json={
    "ip": "8.8.8.8",
    "jurisdiction": "EU",
    "currency": "EUR",
    "sector": "Energy"
  },
  timeout=30
)
print(resp.json())

Cross-Border Risk errors

400 bad_request

Provide one of country, ip, or location; body must be valid JSON

401 unauthorized

Invalid or missing API key

429 rate_limited

Request rate exceeds key plan limits

500 server_error

Risk evaluation failed unexpectedly

Limits & rate-limiting

Per-request names

Plan-based (see Pricing)

Burst limits

Plan-based

RPS

Plan-based (burst-friendly)

Limits are plan-configured: Your effective caps come from your tenant plan and may change. Always reference Pricing or your contract for current limits.

On 429 rate_limited or 503 unavailable, retry with exponential backoff.
Use Idempotency-Key on POSTs to make retries safe.

GET /api/v1/usage/summary

Returns current-month usage for a tenant (organization). Supports either a server-only bearer secret (API_AUTH_SECRET) or a regular API key. With API keys, tenant scope is enforced to the key's own tenant.

Query parameters

Param	Type	Required	Description
tenantId	string (uuid)	Yes	Tenant/organization ID to fetch usage for.
planKey	string	No	Plan key override (free, pro, business, enterprise). Defaults to tenant plan.

You can also pass X-Tenant-Id and X-Plan-Key headers instead of query params.

Request

GET /api/v1/usage/summary?tenantId=<uuid>&planKey=pro
Authorization: Bearer <API_AUTH_SECRET>

Response

200 OK
{
  "planKey": "pro",
  "included": 3000,
  "used": 123,
  "remaining": 2877,
  "periodStartIso": "2025-10-01T00:00:00.000Z",
  "periodEndIso":   "2025-11-01T00:00:00.000Z"
}

Errors

400 bad_request

Body must be valid JSON

400 no_names

Provide at least one name (unless policy-only)

400 too_many_names

Exceeded per-request cap for your plan

401 unauthorized

Invalid/missing API key

403 forbidden

Key not allowed for endpoint/tenant

429 rate_limited

Too many requests/second; retry with backoff

429 limit_exceeded

Monthly allowance reached (tenant-wide)

500 engine_failed

Screening engine not available

503 unavailable

Temporary outage; retry with backoff

Tip: Keep API keys out of browser code. If you must call from the client, proxy via your server and enforce per-tenant quotas.

API Reference

Quickstart Authentication Endpoint Catalog OpenAPI v1 JSON API Explorer Full Docs (Dashboard)

Overview

Base URL

https://your-domain.com

Version

Content-Type

application/json

External API coverage

Required headers

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
Idempotency-Key: <uuid>          # recommended for POST for safe retries

Idempotency: Send a unique Idempotency-Key on POST requests. We will coalesce exact duplicates within a window and return the same result.

POST /api/v1/screen

Screen one or more names. Returns potential matches with confidence, human-readable reasons, and structured evidence (aliases, identifiers, addresses, source links).

Request body

POST /api/v1/screen
{
  "names": string[],                 // required unless "policyQuery" is used
  "entityTypes": string[] | null,    // optional: ["individual","entity","vessel","aircraft","wallet"]
  "sources": string[] | null,        // optional subset of source keys (see /api/v1/datasets). default: all enabled
  "profileKey": string | null,       // optional: "sme_trader_default" | "freight_forwarder_default" | "psp_default"
  "segment": string | null,          // optional: "sme_trader" | "freight_forwarder" | "psp"
  "trigger": string | null,          // optional: "onboarding" | "payment" | "shipment" | "periodic_rescreen" | "event_rescreen"
  "policyQuery": {                   // optional policy-only filter; if provided with empty "names", zero units consumed
    "countries": string[] | null,    // e.g. ["US","EU","UK","CH","CA","AU"]
    "programCodes": string[] | null, // e.g. ["SDGT","SDN","UKR","BELARUS"]
    "keywords": string[] | null      // free-text program/list keywords
  },
  "options": {                       // optional knobs (sensible defaults)
    "maxMatchesPerName": number,     // default 10
    "threshold": number,             // 0..1; default calibrated internal
    "returnRaw": boolean             // include full raw source entry in each match.evidence.raw
  }
}

Supported `entityTypes`

individual
entity
vessel
aircraft
wallet (for blockchain screening, if enabled)

Response

200 OK
{
  "results": [
    {
      "input": "Ali Hassan",
      "isSanctioned": true | false,
      "matches": [
        {
          "source": "EU Sanctions list",
          "sourceKey": "eu",
          "dataset": "EU (FSF)",
          "entityType": "individual",
          "matchedName": "Ali Hassan",
          "matchScore": 0.93,        // 0..1 (1.00 = exact)
          "level": "🟢 Very high confidence",
          "reason": "Exact name match + DOB match + alias overlap",
          "detailsList": [
            { "label": "Date of birth", "value": "1971-05-20" },
            { "label": "Citizenship", "value": "IR" }
          ],
          "evidence": {
            "primaryName": "Ali Hassan",
            "aliases": ["Hassan Ali", "Ali al-Hassan"],
            "identifiers": { "Passport": ["IR12345"] },
            "addresses": ["Tehran, Iran"],
            "nationality": "IR",
            "programs": ["EU-IR"],
            "dates": {
              "Date of birth": "1971-05-20",
              "Date listed": "2012-11-10"
            },
            "sourceUrls": ["https://.../eu_sanctions/entry/123"]
          },
          "raw": { /* optional, if options.returnRaw=true */ }
        }
      ]
    }
  ],
  "policyMatches": [
    /* if policyQuery provided without names */
  ],
  "scannedSources": ["ofac_sdn","eu","uk","un","ch","au","ca"],
  "unavailableSources": [],
  "meta": {
    "tookMs": 124,
    "tenantId": "org_abc",
    "planKey": "pro",
    "policyProfileRequest": {
      "profileKey": "freight_forwarder_default",
      "segment": "freight_forwarder",
      "trigger": "shipment"
    }
  }
}

Examples

cURL Node (fetch)Python (requests)

curl -X POST https://your-domain.com/api/v1/screen \
  -H "Authorization: Bearer $MATCHAUDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "names": ["Vladimir Putin"], "entityTypes": ["individual"], "profileKey": "sme_trader_default", "trigger": "onboarding" }'

export async function screen(names) {
  const res = await fetch("https://your-domain.com/api/v1/screen", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.MATCHAUDIT_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID()
    },
    body: JSON.stringify({
      names,
      entityTypes: ["individual"],
      profileKey: "sme_trader_default",
      trigger: "onboarding"
    })
  });
  if (!res.ok) throw new Error(`Screen failed: ${res.status}`);
  return res.json();
}

import os, uuid, requests
resp = requests.post(
  "https://your-domain.com/api/v1/screen",
  headers={
    "Authorization": f"Bearer {os.getenv('MATCHAUDIT_API_KEY')}",
    "Content-Type": "application/json",
    "Idempotency-Key": str(uuid.uuid4())
  },
  json={
    "names": ["Vladimir Putin"],
    "entityTypes": ["individual"],
    "profileKey": "sme_trader_default",
    "trigger": "onboarding"
  },
  timeout=30
)
print(resp.json())

Field glossary

Field	Type	Description
results[].matches[].matchScore	number (0..1)	Normalized similarity score; 1.00 is exact.
results[].matches[].level	string	Calibrated confidence band (emoji + label).
results[].matches[].reason	string	Human-readable justification for the hit.
results[].matches[].detailsList	array	Flattened key facts shown in the UI (DOB, citizenship, etc.).
results[].matches[].evidence	object	Structured evidence (aliases, identifiers, programs, dates, URLs).
meta.policyProfileRequest	object	Echo of profile/segment/trigger request hints passed to the API.
scannedSources	string[]	Which datasets were actually scanned for this request.
unavailableSources	string[]	Datasets temporarily unavailable during the request.
meta.tookMs	number	Processing time in milliseconds.

Source keys

POST /api/v1/cross-border-risk

Run Cross-Border jurisdiction risk triage by country, IP, or location. Returns sanctions, AML, governance assessments, plus a final recommendation (BLOCK / CAUTION / ALLOW).

Request body

POST /api/v1/cross-border-risk
{
  "country": "Germany",          // optional; provide one of country, ip, location
  "ip": "8.8.8.8",               // optional
  "location": "Munich, Germany", // optional
  "jurisdiction": "GLOBAL",      // optional: GLOBAL | US | EU | UK
  "currency": "EUR",             // optional ISO-4217 (3 letters)
  "sector": "Banking"            // optional free text
}

Response

200 OK
{
  "input": { ... },
  "jurisdiction": "GLOBAL",
  "resolved": {
    "country_name": "Germany",
    "country_iso2": "DE",
    "confidence": "HIGH",
    "resolution_method": "LOCATION",
    "region": "Bavaria",
    "city": "Munich",
    "geo_source": "maxmind_city",
    "precision_warning": ""
  },
  "assessments": {
    "sanctions": { "recommendation": "ALLOW", "risk_level": "LOW", "reasons": [] },
    "aml":       { "recommendation": "ALLOW", "risk_level": "LOW", "reasons": [] },
    "governance":{ "recommendation": "CAUTION", "risk_level": "MEDIUM", "reasons": [] }
  },
  "final": {
    "recommendation": "CAUTION",
    "risk_level": "MEDIUM",
    "reasons": ["..."]
  },
  "risk": { ... },
  "meta": {
    "tookMs": 112,
    "tenantId": "org_abc",
    "planKey": "pro"
  }
}

Examples

cURL Node (fetch)Python (requests)

curl -X POST https://your-domain.com/api/v1/cross-border-risk \
  -H "Authorization: Bearer $MATCHAUDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "location": "Donetsk People\'s Republic", "jurisdiction": "GLOBAL", "currency": "USD", "sector": "Defense" }'

export async function getCrossBorderRisk(payload) {
  const res = await fetch("https://your-domain.com/api/v1/cross-border-risk", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.MATCHAUDIT_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  });
  if (!res.ok) throw new Error(`Cross-border risk failed: ${res.status}`);
  return res.json();
}

import os, requests
resp = requests.post(
  "https://your-domain.com/api/v1/cross-border-risk",
  headers={
    "Authorization": f"Bearer {os.getenv('MATCHAUDIT_API_KEY')}",
    "Content-Type": "application/json"
  },
  json={
    "ip": "8.8.8.8",
    "jurisdiction": "EU",
    "currency": "EUR",
    "sector": "Energy"
  },
  timeout=30
)
print(resp.json())

Cross-Border Risk errors

400 bad_request

Provide one of country, ip, or location; body must be valid JSON

401 unauthorized

Invalid or missing API key

429 rate_limited

Request rate exceeds key plan limits

500 server_error

Risk evaluation failed unexpectedly

Limits & rate-limiting

Per-request names

Plan-based (see Pricing)

Burst limits

Plan-based

RPS

Plan-based (burst-friendly)

Limits are plan-configured: Your effective caps come from your tenant plan and may change. Always reference Pricing or your contract for current limits.

On 429 rate_limited or 503 unavailable, retry with exponential backoff.
Use Idempotency-Key on POSTs to make retries safe.

GET /api/v1/usage/summary

Query parameters

Param	Type	Required	Description
tenantId	string (uuid)	Yes	Tenant/organization ID to fetch usage for.
planKey	string	No	Plan key override (free, pro, business, enterprise). Defaults to tenant plan.

You can also pass X-Tenant-Id and X-Plan-Key headers instead of query params.

Request

GET /api/v1/usage/summary?tenantId=<uuid>&planKey=pro
Authorization: Bearer <API_AUTH_SECRET>

Response

200 OK
{
  "planKey": "pro",
  "included": 3000,
  "used": 123,
  "remaining": 2877,
  "periodStartIso": "2025-10-01T00:00:00.000Z",
  "periodEndIso":   "2025-11-01T00:00:00.000Z"
}

Errors

400 bad_request

Body must be valid JSON

400 no_names

Provide at least one name (unless policy-only)

400 too_many_names

Exceeded per-request cap for your plan

401 unauthorized

Invalid/missing API key

403 forbidden

Key not allowed for endpoint/tenant

429 rate_limited

Too many requests/second; retry with backoff

429 limit_exceeded

Monthly allowance reached (tenant-wide)

500 engine_failed

Screening engine not available

503 unavailable

Temporary outage; retry with backoff

Tip: Keep API keys out of browser code. If you must call from the client, proxy via your server and enforce per-tenant quotas.

API Reference

Overview

External API coverage

Required headers

POST /api/v1/screen

Request body

Supported entityTypes

Response

Examples

Field glossary

Source keys

POST /api/v1/cross-border-risk

Request body

Response

Examples

Cross-Border Risk errors

Limits & rate-limiting

GET /api/v1/usage/summary

Query parameters

Request

Response

Errors

API Reference

Overview

External API coverage

Required headers

POST /api/v1/screen

Request body

Supported entityTypes

Response

Examples

Field glossary

Source keys

POST /api/v1/cross-border-risk

Request body

Response

Examples

Cross-Border Risk errors

Limits & rate-limiting

GET /api/v1/usage/summary

Query parameters

Request

Response

Errors

Supported `entityTypes`

Supported `entityTypes`