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 Salesforce Docs OpenAPI v1 JSON API Explorer Operations Docs

Overview

Base URL

https://your-domain.com

Version

Content-Type

application/json

External API coverage

The public customer-facing surface includes customer-facing 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 Operations Docs.

Required headers

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

Settings are a required implementation step

Important: Before sending production screening requests, review and confirm your screening settings through GET /api/v1/settings. Sanctions screening quality depends on the active source selection. If the wrong sanctions lists are selected, the result will be wrong for your intended workflow.

MatchAudit provides a global default source set automatically for new API users. If that default is suitable for your workflow, you may keep it. If you need a different jurisdiction or source selection, update it first through PUT /api/v1/settings before screening in production.

Source selection precedence is:

sources[] in the screening request for a one-off override
saved API settings from /api/v1/settings
the global default source set when no custom settings exist

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. You can send country, location, IP, or structured address context in the same request. A clear name screen can still return a blocked or review outcome when the country signal is actionable under the selected jurisdiction.

Request body

POST /api/v1/screen
{
  "name": string,                    // optional alias for a single-name request
  "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). If omitted, saved settings or the global baseline apply
  "country": string | null,          // optional country context, e.g. "Syria"
  "location": string | null,         // optional city/region/country string, e.g. "Damascus, Syria"
  "ip": string | null,               // optional IP context for country resolution
  "jurisdiction": string | null,     // optional: "GLOBAL" | "US" | "EU" | "UK"; falls back to saved settings when present
  "currency": string | null,         // optional transaction currency for country-risk evaluation
  "sector": string | null,           // optional sector for sectoral sanctions checks
  "structured": {                    // optional structured context (mirrors dashboard structured intake)
    "fullName": string | null,
    "firstName": string | null,
    "lastName": string | null,
    "dob": string | null,
    "ids": [{ "type": string | null, "value": string }],
    "address": {
      "street": string | null,
      "city": string | null,
      "region": string | null,
      "country": string | null
    }
  },
  "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": "Northshore Trading GmbH",
      "name": "Northshore Trading GmbH",
      "isSanctioned": false,         // direct name-screen hit only
      "directNameHit": false,
      "countryRiskHit": true,        // true when country risk drives BLOCK or REVIEW
      "actionableHit": true,         // direct hit or country-driven hit
      "decision": {
        "status": "BLOCK",           // CLEAR | REVIEW | BLOCK
        "label": "Do not proceed",
        "headline": "Sanctions concerns identified. Do not proceed.",
        "focus": "Country risk block with clean name screening",
        "reason": "The submitted subject name did not return direct list matches, but the case still requires a sanctions decision because the provided country information carries independent risk.",
        "recommendedNextSteps": [
          "Do not proceed with the case.",
          "Escalate the case to sanctions or compliance, confirm the country input, and check whether any license, exemption, or legal override process applies."
        ]
      },
      "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",
    "sourceSelection": {
      "mode": "settings",            // request | settings | global_baseline
      "appliedSources": ["un", "eu", "ofac", "uk", "seco"],
      "settingsStore": "user_settings"
    },
    "policyProfileRequest": {
      "profileKey": "freight_forwarder_default",
      "segment": "freight_forwarder",
      "trigger": "shipment"
    },
    "countryRisk": {
      "provided": true,
      "evaluated": true,
      "recommendation": "BLOCK",
      "riskLevel": "HIGH",
      "resolvedCountryName": "Syrian Arab Republic",
      "resolvedCountryIso2": "SY",
      "jurisdiction": "US",
      "reasons": [
        "Jurisdiction profile (US) lists SY as blocked."
      ]
    }
  }
}

Important: results[].isSanctioned still reflects direct name-list matches. For country-driven restrictions, inspect results[].actionableHit, results[].decision.status, and meta.countryRisk.

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": ["Northshore Trading GmbH"],
    "entityTypes": ["entity"],
    "country": "Syria",
    "jurisdiction": "US",
    "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: ["entity"],
      country: "Syria",
      jurisdiction: "US",
      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": ["Northshore Trading GmbH"],
    "entityTypes": ["entity"],
    "country": "Syria",
    "jurisdiction": "US",
    "profileKey": "sme_trader_default",
    "trigger": "onboarding"
  },
  timeout=30
)
print(resp.json())

Field glossary

Field	Type	Description
results[].isSanctioned	boolean	Direct name-screen hit only. Country-only restrictions do not flip this field by themselves.
results[].actionableHit	boolean	True when the request produced a direct hit or a country-driven BLOCK/REVIEW signal.
results[].decision.status	"CLEAR" \| "REVIEW" \| "BLOCK"	Final screening outcome for the submitted name plus any country-risk context.
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.countryRisk	object	Country-risk evaluation summary for the request, including recommendation, resolved country, and reasons.
meta.sourceSelection	object	Shows whether the route used request sources, saved settings, or the global baseline.
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 according to your saved settings, or the global default source set if you have not saved custom settings yet.

For implementation and audit purposes, treat settings review as a mandatory first step even though a global default is provided automatically.

POST /api/v1/integrations/salesforce/screen

Screen one Salesforce Contact, Account, Lead, or similar record through MatchAudit and return a structured compliance answer designed for CRM workflows. This connector is built for lean teams: one record in, one screening outcome out, plus an audit reference and evidence links you can store back on the Salesforce record.

What it is for: Use this endpoint when the decision point already lives in Salesforce and you want compliance inside that workflow without building a heavyweight AppExchange or middleware framework.

Request body

POST /api/v1/integrations/salesforce/screen
{
  "recordType": "contact",                 // recommended: contact | account | lead | opportunity
  "recordId": "0038b00002AbCdE",           // optional Salesforce record id
  "recordUrl": "https://your-org.lightning.force.com/...",
  "requestId": "sf-flow-2026-03-27-001",   // recommended idempotent reference from Flow or middleware
  "subjectType": "individual",             // optional override: individual | entity
  "fullName": "Aleksandr Sergei Petrov",   // required for person-like records
  "firstName": "Aleksandr",                // optional
  "lastName": "Petrov",                    // optional
  "companyName": "PetroLogix Trading Ltd", // required for account/entity flows
  "country": "Cyprus",                     // strongly recommended
  "dateOfBirth": "1982-03-12",             // optional
  "nationality": ["Russia", "Cyprus"],     // optional
  "gender": "Male",                        // optional
  "placeOfBirth": "Moscow, Russia",        // optional
  "identifiers": [                         // optional
    { "type": "passport", "value": "724587392" }
  ],
  "aliases": ["Alexander Petrov"],         // optional
  "mailingStreet": "14 Limassol Marina",   // optional
  "mailingCity": "Limassol",               // optional
  "mailingCountry": "Cyprus",              // optional
  "sources": ["un", "eu", "ofac"]          // optional one-off source override
}

Response

200 OK
{
  "ok": true,
  "integration": {
    "key": "salesforce",
    "label": "Salesforce",
    "recordType": "contact",
    "recordId": "0038b00002AbCdE",
    "recordUrl": "https://your-org.lightning.force.com/..."
  },
  "subject": {
    "primaryName": "Aleksandr Sergei Petrov",
    "companyName": "PetroLogix Trading Ltd",
    "subjectType": "individual",
    "country": "Cyprus",
    "location": "Cyprus"
  },
  "screening": {
    "screeningStatus": "REVIEW",           // CLEAR | REVIEW | BLOCK
    "outcomeLabel": "Review required",
    "riskLevel": "MEDIUM",                 // LOW | MEDIUM | HIGH
    "actionableHit": true,
    "directNameHit": true,
    "countryRiskHit": false,
    "summary": "Aleksandr Sergei Petrov returned possible sanctions concerns that need analyst review.",
    "recommendedNextSteps": ["Pause the workflow until the reviewer confirms the result."],
    "matchSummary": {
      "directMatchCount": 1,
      "topMatch": {
        "source": "OFAC SDN",
        "sourceKey": "ofac",
        "matchedName": "Aleksandr Sergei Petrov",
        "score": 0.97,
        "confidence": "High",
        "matchType": "Exact full-name match",
        "matchedOn": "official record",
        "matchedFields": ["full name", "passport"],
        "reason": "Exact name match with corroborating identifier.",
        "programs": ["SDN"]
      },
      "additionalMatches": [],
      "countryRisk": null
    },
    "sourceSelection": {
      "mode": "settings",
      "appliedSources": ["un", "eu", "ofac", "uk", "seco"],
      "settingsStore": "user_settings"
    },
    "scannedSources": ["un", "eu", "ofac", "uk", "seco"],
    "unavailableSources": [],
    "auditReferenceId": "84321",
    "evidence": {
      "pdfUrl": "https://your-domain.com/api/v1/export?type=pdf&auditId=84321",
      "jsonUrl": "https://your-domain.com/api/v1/export?type=json&auditId=84321"
    },
    "timestamp": "2026-03-27T14:18:00.000Z"
  }
}

Examples

cURL Node (fetch)What Salesforce should store

curl -X POST https://your-domain.com/api/v1/integrations/salesforce/screen \
  -H "Authorization: Bearer $MATCHAUDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sf-contact-0038b00002AbCdE" \
  -d '{
    "recordType": "contact",
    "recordId": "0038b00002AbCdE",
    "fullName": "Aleksandr Sergei Petrov",
    "companyName": "PetroLogix Trading Ltd",
    "country": "Cyprus",
    "dateOfBirth": "1982-03-12"
  }'

export async function screenSalesforceRecord(payload) {
  const res = await fetch("https://your-domain.com/api/v1/integrations/salesforce/screen", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.MATCHAUDIT_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": payload.requestId || crypto.randomUUID()
    },
    body: JSON.stringify(payload)
  });
  if (!res.ok) throw new Error(`Salesforce screening failed: ${res.status}`);
  return res.json();
}

1. screening.screeningStatus
2. screening.riskLevel
3. screening.summary
4. screening.auditReferenceId
5. screening.evidence.pdfUrl
6. screening.evidence.jsonUrl

Connector notes

Use country, billingCountry, or mailingCountry whenever possible so the connector can evaluate country risk in the same request.
Accounts default to entity screening. Contacts and leads default to individual screening unless you override subjectType.
MatchAudit audit-logs every connector-triggered screening and returns the audit reference id for record-level evidence storage.
The same CRM connector service is designed to be reused later for HubSpot or other CRM connectors, so the contract is intentionally narrow and stable.

POST /api/v1/integrations/sap-gts/sync

Send SAP GTS exports into MatchAudit for screening, case creation, and review tracking. This endpoint is designed for customers who already work in SAP GTS and want a repeatable handoff from trade operations into compliance review without relying on manual uploads every time.

What it is for: Use this endpoint when SAP GTS or middleware can send rows on a schedule or after a workflow event. If your team is still validating the process manually, the dashboard SAP GTS upload flow offers the same review model without integration work.

For SAP-native implementations, set connectorType to sap_cpi and let the dashboard store the matching source system, deep links, and write-back configuration. MatchAudit now treats SAP CPI as the primary native connector path.

Request body

POST /api/v1/integrations/sap-gts/sync
{
  "externalRunId": "sap-job-2026-03-11-001",   // recommended for safe retries
  "sourceSystem": "sap-gts",                    // optional; defaults to sap-gts
  "fileName": "sap-export-2026-03-11.csv",     // optional
  "csvText": "Name,Country,Document No\n...",  // optional if rows is not sent
  "rows": [                                     // optional if csvText is sent
    {
      "Name": "Example GmbH",
      "Country": "DE",
      "Address": "Berlin, Germany",
      "Document No": "4711",
      "Transaction ID": "TX-10001",
      "SAP Result": "REVIEW",
      "Reason": "Potential sanctions hit",
      "Timestamp": "2026-03-11T10:00:00Z"
    }
  ],
  "includeRows": false,                         // optional; include normalized rows in response
  "requestMeta": {                              // optional middleware metadata
    "jobType": "nightly-export",
    "plant": "DE01"
  }
}

SAP CPI envelope example

POST /api/v1/integrations/sap-gts/sync
{
  "connectorType": "sap_cpi",
  "sourceSystem": "sap-cpi",
  "externalRunId": "cpi-run-2026-03-14-001",
  "cpi": {
    "records": [
      {
        "Name": "Example GmbH",
        "Country": "DE",
        "Document No": "4711",
        "Transaction ID": "TX-10001",
        "SAP Result": "REVIEW"
      }
    ]
  }
}

Response

200 OK
{
  "ok": true,
  "syncRun": {
    "id": "2f4c2a58-...",
    "status": "SUCCEEDED",
    "source_type": "api_sync",
    "source_system": "sap-gts",
    "external_run_id": "sap-job-2026-03-11-001",
    "input_row_count": 125,
    "processed_row_count": 125,
    "created_count": 80,
    "updated_count": 45,
    "error_count": 0,
    "warning_count": 2,
    "result_meta": {
      "durationMs": 2140,
      "qualitySummary": {
        "validRows": 125,
        "invalidRows": 0
      }
    }
  },
  "processedCount": 125,
  "mapping": { "name": "Name", "sap_result": "SAP Result" },
  "qualitySummary": { "validRows": 125, "invalidRows": 0 },
  "warnings": []
}

Examples

cURL Node (fetch)Python (requests)

curl -X POST https://your-domain.com/api/v1/integrations/sap-gts/sync \
  -H "Authorization: Bearer $MATCHAUDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalRunId": "sap-job-2026-03-11-001",
    "sourceSystem": "sap-gts",
    "rows": [
      {
        "Name": "Example GmbH",
        "Country": "DE",
        "Document No": "4711",
        "Transaction ID": "TX-10001",
        "SAP Result": "REVIEW"
      }
    ]
  }'

export async function syncSapGts(rows) {
  const res = await fetch("https://your-domain.com/api/v1/integrations/sap-gts/sync", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.MATCHAUDIT_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      externalRunId: crypto.randomUUID(),
      sourceSystem: "sap-gts",
      rows
    })
  });
  if (!res.ok) throw new Error(`SAP GTS sync failed: ${res.status}`);
  return res.json();
}

import os, uuid, requests
resp = requests.post(
  "https://your-domain.com/api/v1/integrations/sap-gts/sync",
  headers={
    "Authorization": f"Bearer {os.getenv('MATCHAUDIT_API_KEY')}",
    "Content-Type": "application/json"
  },
  json={
    "externalRunId": str(uuid.uuid4()),
    "sourceSystem": "sap-gts",
    "rows": [
      {
        "Name": "Example GmbH",
        "Country": "DE",
        "Document No": "4711",
        "Transaction ID": "TX-10001",
        "SAP Result": "REVIEW"
      }
    ]
  },
  timeout=30
)
print(resp.json())

Operational notes

Use externalRunId so middleware retries do not create duplicate sync runs.
The response includes mapping and quality summary information so you can detect bad exports before analysts start review.
Rows are normalized into the same review workflow used by the dashboard SAP GTS upload page.
Recent sync runs can be reviewed in the dashboard under Integrations > SAP GTS.
Scheduled sync and automatic write-back are configured in the dashboard SAP GTS automation panel, not in the request body of this endpoint.
Default mapping profiles are applied automatically per sourceSystem when you do not send a mapping object explicitly.

GET /api/v1/integrations/sap-gts

Read back reviewed SAP GTS decisions for middleware write-back into SAP, middleware queues, or downstream operational systems.

What it is for: Use this endpoint after analysts review SAP GTS cases in MatchAudit. The endpoint returns only cases with a finalized human review state and recorded review timestamp.

If you enable automatic write-back in Integrations > SAP GTS, MatchAudit can push the same reviewed decision payload to your middleware automatically. Keep this endpoint for reconciliation, polling, or fallback reads.

Draft saves stay inside MatchAudit and do not appear here. Only finalized decisions are eligible for public read-back and automatic write-back.

Query parameters

GET /api/v1/integrations/sap-gts?externalRunId=sap-job-2026-03-11-001&updatedSince=2026-03-11T00:00:00Z&limit=100

externalRunId   optional  filter to one SAP middleware run
transactionId   optional  filter to one SAP transaction id
documentNo      optional  filter to one SAP document reference
updatedSince    optional  ISO-8601 lower bound on human-reviewed decisions
limit           optional  default 100, max 500

Response

200 OK
{
  "ok": true,
  "decisions": [
    {
      "caseId": "0bc8...",
      "searchedName": "PJSC Alrosa",
      "transactionId": "TX-10001",
      "sapDocumentNo": "4711",
      "sourceSystem": "sap-gts",
      "externalRunId": "sap-job-2026-03-11-001",
      "syncRunId": "2f4c2a58-...",
      "sapResult": "REVIEW",
      "matchauditOutcome": "HIT",
      "matchauditTopSource": "eu",
      "matchauditTopScore": 0.89,
      "finalDecision": "ESCALATE",
      "caseStatus": "ESCALATED",
      "reviewerNotes": "Escalated to sanctions officer due to EU hit.",
      "decisionReviewedAt": "2026-03-11T10:18:00.000Z",
      "decisionReviewedBy": "user-id",
      "evidencePdfUrl": "https://your-domain.com/api/export?type=case_pdf&case_id=0bc8..."
    }
  ]
}

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 Salesforce Docs OpenAPI v1 JSON API Explorer Operations Docs

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

Settings are a required implementation step

Source selection precedence is:

sources[] in the screening request for a one-off override
saved API settings from /api/v1/settings
the global default source set when no custom settings exist

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

Request body

POST /api/v1/screen
{
  "name": string,                    // optional alias for a single-name request
  "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). If omitted, saved settings or the global baseline apply
  "country": string | null,          // optional country context, e.g. "Syria"
  "location": string | null,         // optional city/region/country string, e.g. "Damascus, Syria"
  "ip": string | null,               // optional IP context for country resolution
  "jurisdiction": string | null,     // optional: "GLOBAL" | "US" | "EU" | "UK"; falls back to saved settings when present
  "currency": string | null,         // optional transaction currency for country-risk evaluation
  "sector": string | null,           // optional sector for sectoral sanctions checks
  "structured": {                    // optional structured context (mirrors dashboard structured intake)
    "fullName": string | null,
    "firstName": string | null,
    "lastName": string | null,
    "dob": string | null,
    "ids": [{ "type": string | null, "value": string }],
    "address": {
      "street": string | null,
      "city": string | null,
      "region": string | null,
      "country": string | null
    }
  },
  "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": "Northshore Trading GmbH",
      "name": "Northshore Trading GmbH",
      "isSanctioned": false,         // direct name-screen hit only
      "directNameHit": false,
      "countryRiskHit": true,        // true when country risk drives BLOCK or REVIEW
      "actionableHit": true,         // direct hit or country-driven hit
      "decision": {
        "status": "BLOCK",           // CLEAR | REVIEW | BLOCK
        "label": "Do not proceed",
        "headline": "Sanctions concerns identified. Do not proceed.",
        "focus": "Country risk block with clean name screening",
        "reason": "The submitted subject name did not return direct list matches, but the case still requires a sanctions decision because the provided country information carries independent risk.",
        "recommendedNextSteps": [
          "Do not proceed with the case.",
          "Escalate the case to sanctions or compliance, confirm the country input, and check whether any license, exemption, or legal override process applies."
        ]
      },
      "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",
    "sourceSelection": {
      "mode": "settings",            // request | settings | global_baseline
      "appliedSources": ["un", "eu", "ofac", "uk", "seco"],
      "settingsStore": "user_settings"
    },
    "policyProfileRequest": {
      "profileKey": "freight_forwarder_default",
      "segment": "freight_forwarder",
      "trigger": "shipment"
    },
    "countryRisk": {
      "provided": true,
      "evaluated": true,
      "recommendation": "BLOCK",
      "riskLevel": "HIGH",
      "resolvedCountryName": "Syrian Arab Republic",
      "resolvedCountryIso2": "SY",
      "jurisdiction": "US",
      "reasons": [
        "Jurisdiction profile (US) lists SY as blocked."
      ]
    }
  }
}

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": ["Northshore Trading GmbH"],
    "entityTypes": ["entity"],
    "country": "Syria",
    "jurisdiction": "US",
    "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: ["entity"],
      country: "Syria",
      jurisdiction: "US",
      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": ["Northshore Trading GmbH"],
    "entityTypes": ["entity"],
    "country": "Syria",
    "jurisdiction": "US",
    "profileKey": "sme_trader_default",
    "trigger": "onboarding"
  },
  timeout=30
)
print(resp.json())

Field glossary

Field	Type	Description
results[].isSanctioned	boolean	Direct name-screen hit only. Country-only restrictions do not flip this field by themselves.
results[].actionableHit	boolean	True when the request produced a direct hit or a country-driven BLOCK/REVIEW signal.
results[].decision.status	"CLEAR" \| "REVIEW" \| "BLOCK"	Final screening outcome for the submitted name plus any country-risk context.
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.countryRisk	object	Country-risk evaluation summary for the request, including recommendation, resolved country, and reasons.
meta.sourceSelection	object	Shows whether the route used request sources, saved settings, or the global baseline.
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

For implementation and audit purposes, treat settings review as a mandatory first step even though a global default is provided automatically.

POST /api/v1/integrations/salesforce/screen

Request body

POST /api/v1/integrations/salesforce/screen
{
  "recordType": "contact",                 // recommended: contact | account | lead | opportunity
  "recordId": "0038b00002AbCdE",           // optional Salesforce record id
  "recordUrl": "https://your-org.lightning.force.com/...",
  "requestId": "sf-flow-2026-03-27-001",   // recommended idempotent reference from Flow or middleware
  "subjectType": "individual",             // optional override: individual | entity
  "fullName": "Aleksandr Sergei Petrov",   // required for person-like records
  "firstName": "Aleksandr",                // optional
  "lastName": "Petrov",                    // optional
  "companyName": "PetroLogix Trading Ltd", // required for account/entity flows
  "country": "Cyprus",                     // strongly recommended
  "dateOfBirth": "1982-03-12",             // optional
  "nationality": ["Russia", "Cyprus"],     // optional
  "gender": "Male",                        // optional
  "placeOfBirth": "Moscow, Russia",        // optional
  "identifiers": [                         // optional
    { "type": "passport", "value": "724587392" }
  ],
  "aliases": ["Alexander Petrov"],         // optional
  "mailingStreet": "14 Limassol Marina",   // optional
  "mailingCity": "Limassol",               // optional
  "mailingCountry": "Cyprus",              // optional
  "sources": ["un", "eu", "ofac"]          // optional one-off source override
}

Response

200 OK
{
  "ok": true,
  "integration": {
    "key": "salesforce",
    "label": "Salesforce",
    "recordType": "contact",
    "recordId": "0038b00002AbCdE",
    "recordUrl": "https://your-org.lightning.force.com/..."
  },
  "subject": {
    "primaryName": "Aleksandr Sergei Petrov",
    "companyName": "PetroLogix Trading Ltd",
    "subjectType": "individual",
    "country": "Cyprus",
    "location": "Cyprus"
  },
  "screening": {
    "screeningStatus": "REVIEW",           // CLEAR | REVIEW | BLOCK
    "outcomeLabel": "Review required",
    "riskLevel": "MEDIUM",                 // LOW | MEDIUM | HIGH
    "actionableHit": true,
    "directNameHit": true,
    "countryRiskHit": false,
    "summary": "Aleksandr Sergei Petrov returned possible sanctions concerns that need analyst review.",
    "recommendedNextSteps": ["Pause the workflow until the reviewer confirms the result."],
    "matchSummary": {
      "directMatchCount": 1,
      "topMatch": {
        "source": "OFAC SDN",
        "sourceKey": "ofac",
        "matchedName": "Aleksandr Sergei Petrov",
        "score": 0.97,
        "confidence": "High",
        "matchType": "Exact full-name match",
        "matchedOn": "official record",
        "matchedFields": ["full name", "passport"],
        "reason": "Exact name match with corroborating identifier.",
        "programs": ["SDN"]
      },
      "additionalMatches": [],
      "countryRisk": null
    },
    "sourceSelection": {
      "mode": "settings",
      "appliedSources": ["un", "eu", "ofac", "uk", "seco"],
      "settingsStore": "user_settings"
    },
    "scannedSources": ["un", "eu", "ofac", "uk", "seco"],
    "unavailableSources": [],
    "auditReferenceId": "84321",
    "evidence": {
      "pdfUrl": "https://your-domain.com/api/v1/export?type=pdf&auditId=84321",
      "jsonUrl": "https://your-domain.com/api/v1/export?type=json&auditId=84321"
    },
    "timestamp": "2026-03-27T14:18:00.000Z"
  }
}

Examples

cURL Node (fetch)What Salesforce should store

curl -X POST https://your-domain.com/api/v1/integrations/salesforce/screen \
  -H "Authorization: Bearer $MATCHAUDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sf-contact-0038b00002AbCdE" \
  -d '{
    "recordType": "contact",
    "recordId": "0038b00002AbCdE",
    "fullName": "Aleksandr Sergei Petrov",
    "companyName": "PetroLogix Trading Ltd",
    "country": "Cyprus",
    "dateOfBirth": "1982-03-12"
  }'

export async function screenSalesforceRecord(payload) {
  const res = await fetch("https://your-domain.com/api/v1/integrations/salesforce/screen", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.MATCHAUDIT_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": payload.requestId || crypto.randomUUID()
    },
    body: JSON.stringify(payload)
  });
  if (!res.ok) throw new Error(`Salesforce screening failed: ${res.status}`);
  return res.json();
}

1. screening.screeningStatus
2. screening.riskLevel
3. screening.summary
4. screening.auditReferenceId
5. screening.evidence.pdfUrl
6. screening.evidence.jsonUrl

Connector notes

Use country, billingCountry, or mailingCountry whenever possible so the connector can evaluate country risk in the same request.
Accounts default to entity screening. Contacts and leads default to individual screening unless you override subjectType.
MatchAudit audit-logs every connector-triggered screening and returns the audit reference id for record-level evidence storage.
The same CRM connector service is designed to be reused later for HubSpot or other CRM connectors, so the contract is intentionally narrow and stable.

POST /api/v1/integrations/sap-gts/sync

Request body

POST /api/v1/integrations/sap-gts/sync
{
  "externalRunId": "sap-job-2026-03-11-001",   // recommended for safe retries
  "sourceSystem": "sap-gts",                    // optional; defaults to sap-gts
  "fileName": "sap-export-2026-03-11.csv",     // optional
  "csvText": "Name,Country,Document No\n...",  // optional if rows is not sent
  "rows": [                                     // optional if csvText is sent
    {
      "Name": "Example GmbH",
      "Country": "DE",
      "Address": "Berlin, Germany",
      "Document No": "4711",
      "Transaction ID": "TX-10001",
      "SAP Result": "REVIEW",
      "Reason": "Potential sanctions hit",
      "Timestamp": "2026-03-11T10:00:00Z"
    }
  ],
  "includeRows": false,                         // optional; include normalized rows in response
  "requestMeta": {                              // optional middleware metadata
    "jobType": "nightly-export",
    "plant": "DE01"
  }
}

SAP CPI envelope example

POST /api/v1/integrations/sap-gts/sync
{
  "connectorType": "sap_cpi",
  "sourceSystem": "sap-cpi",
  "externalRunId": "cpi-run-2026-03-14-001",
  "cpi": {
    "records": [
      {
        "Name": "Example GmbH",
        "Country": "DE",
        "Document No": "4711",
        "Transaction ID": "TX-10001",
        "SAP Result": "REVIEW"
      }
    ]
  }
}

Response

200 OK
{
  "ok": true,
  "syncRun": {
    "id": "2f4c2a58-...",
    "status": "SUCCEEDED",
    "source_type": "api_sync",
    "source_system": "sap-gts",
    "external_run_id": "sap-job-2026-03-11-001",
    "input_row_count": 125,
    "processed_row_count": 125,
    "created_count": 80,
    "updated_count": 45,
    "error_count": 0,
    "warning_count": 2,
    "result_meta": {
      "durationMs": 2140,
      "qualitySummary": {
        "validRows": 125,
        "invalidRows": 0
      }
    }
  },
  "processedCount": 125,
  "mapping": { "name": "Name", "sap_result": "SAP Result" },
  "qualitySummary": { "validRows": 125, "invalidRows": 0 },
  "warnings": []
}

Examples

cURL Node (fetch)Python (requests)

curl -X POST https://your-domain.com/api/v1/integrations/sap-gts/sync \
  -H "Authorization: Bearer $MATCHAUDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalRunId": "sap-job-2026-03-11-001",
    "sourceSystem": "sap-gts",
    "rows": [
      {
        "Name": "Example GmbH",
        "Country": "DE",
        "Document No": "4711",
        "Transaction ID": "TX-10001",
        "SAP Result": "REVIEW"
      }
    ]
  }'

export async function syncSapGts(rows) {
  const res = await fetch("https://your-domain.com/api/v1/integrations/sap-gts/sync", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.MATCHAUDIT_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      externalRunId: crypto.randomUUID(),
      sourceSystem: "sap-gts",
      rows
    })
  });
  if (!res.ok) throw new Error(`SAP GTS sync failed: ${res.status}`);
  return res.json();
}

import os, uuid, requests
resp = requests.post(
  "https://your-domain.com/api/v1/integrations/sap-gts/sync",
  headers={
    "Authorization": f"Bearer {os.getenv('MATCHAUDIT_API_KEY')}",
    "Content-Type": "application/json"
  },
  json={
    "externalRunId": str(uuid.uuid4()),
    "sourceSystem": "sap-gts",
    "rows": [
      {
        "Name": "Example GmbH",
        "Country": "DE",
        "Document No": "4711",
        "Transaction ID": "TX-10001",
        "SAP Result": "REVIEW"
      }
    ]
  },
  timeout=30
)
print(resp.json())

Operational notes

Use externalRunId so middleware retries do not create duplicate sync runs.
The response includes mapping and quality summary information so you can detect bad exports before analysts start review.
Rows are normalized into the same review workflow used by the dashboard SAP GTS upload page.
Recent sync runs can be reviewed in the dashboard under Integrations > SAP GTS.
Scheduled sync and automatic write-back are configured in the dashboard SAP GTS automation panel, not in the request body of this endpoint.
Default mapping profiles are applied automatically per sourceSystem when you do not send a mapping object explicitly.

GET /api/v1/integrations/sap-gts

Read back reviewed SAP GTS decisions for middleware write-back into SAP, middleware queues, or downstream operational systems.

What it is for: Use this endpoint after analysts review SAP GTS cases in MatchAudit. The endpoint returns only cases with a finalized human review state and recorded review timestamp.

Draft saves stay inside MatchAudit and do not appear here. Only finalized decisions are eligible for public read-back and automatic write-back.

Query parameters

GET /api/v1/integrations/sap-gts?externalRunId=sap-job-2026-03-11-001&updatedSince=2026-03-11T00:00:00Z&limit=100

externalRunId   optional  filter to one SAP middleware run
transactionId   optional  filter to one SAP transaction id
documentNo      optional  filter to one SAP document reference
updatedSince    optional  ISO-8601 lower bound on human-reviewed decisions
limit           optional  default 100, max 500

Response

200 OK
{
  "ok": true,
  "decisions": [
    {
      "caseId": "0bc8...",
      "searchedName": "PJSC Alrosa",
      "transactionId": "TX-10001",
      "sapDocumentNo": "4711",
      "sourceSystem": "sap-gts",
      "externalRunId": "sap-job-2026-03-11-001",
      "syncRunId": "2f4c2a58-...",
      "sapResult": "REVIEW",
      "matchauditOutcome": "HIT",
      "matchauditTopSource": "eu",
      "matchauditTopScore": 0.89,
      "finalDecision": "ESCALATE",
      "caseStatus": "ESCALATED",
      "reviewerNotes": "Escalated to sanctions officer due to EU hit.",
      "decisionReviewedAt": "2026-03-11T10:18:00.000Z",
      "decisionReviewedBy": "user-id",
      "evidencePdfUrl": "https://your-domain.com/api/export?type=case_pdf&case_id=0bc8..."
    }
  ]
}

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

Settings are a required implementation step

POST /api/v1/screen

Request body

Supported entityTypes

Response

Examples

Field glossary

Source keys

POST /api/v1/integrations/salesforce/screen

Request body

Response

Examples

Connector notes

POST /api/v1/integrations/sap-gts/sync

Request body

SAP CPI envelope example

Response

Examples

Operational notes

GET /api/v1/integrations/sap-gts

Query parameters

Response

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

Settings are a required implementation step

POST /api/v1/screen

Request body

Supported entityTypes

Response

Examples

Field glossary

Source keys

POST /api/v1/integrations/salesforce/screen

Request body

Response

Examples

Connector notes

POST /api/v1/integrations/sap-gts/sync

Request body

SAP CPI envelope example

Response

Examples

Operational notes

GET /api/v1/integrations/sap-gts

Query parameters

Response

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`