5-minute Quickstart

Your first screening with the v1 API

Create an API key, run a screening request, and verify usage metering. No SDK required - just HTTP.

Get an API key
In your dashboard, go to Settings → API Keys and create a key. Copy it and store it as an environment variable - never embed in client-side code.
macOS / Linux
```
export MATCHAUDIT_API_KEY="sk_live_..."
```
Windows (PowerShell)
```
$env:MATCHAUDIT_API_KEY="sk_live_..."
```
Review screening settings first
Before sending screening requests, confirm which sanctions lists your API workflow should use. This is a required implementation step because screening quality depends on the active source selection.
MatchAudit applies a global default source set automatically for new API users. If that default is not appropriate, update it first through PUT /api/v1/settings.
Check current settings Update settings
```
curl -sS https://your-domain.com/api/v1/settings \
  -H "Authorization: Bearer $MATCHAUDIT_API_KEY" | jq
```
```
curl -sS -X PUT https://your-domain.com/api/v1/settings \
  -H "Authorization: Bearer $MATCHAUDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jurisdiction": "global",
    "sources": ["un", "eu", "ofac", "uk", "seco"]
  }' | jq
```
Important: If you do not configure custom settings, MatchAudit will still use the global default source set. In production, you should explicitly review and confirm those settings before relying on the API response.

Make your first request

Use POST /api/v1/screen with your API key in the Authorization header. The same request can include country, location, IP, or structured address context, so you can get a single screening answer that reflects both direct list hits and country-driven restrictions.

cURL Node (fetch)Python (requests)

curl -sS -X POST https://your-domain.com/api/v1/screen \
  -H "Authorization: Bearer $MATCHAUDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "names": ["Northshore Trading GmbH"],
    "entityTypes": ["entity"],
    "country": "Syria",
    "jurisdiction": "US"
  }' | jq

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"
  },
  body: JSON.stringify({
    names: ["Northshore Trading GmbH"],
    entityTypes: ["entity"],
    country: "Syria",
    jurisdiction: "US"
  })
});
console.log(await res.json());

import os, requests, json
resp = requests.post(
  "https://your-domain.com/api/v1/screen",
  headers={"Authorization": f"Bearer {os.getenv('MATCHAUDIT_API_KEY')}",
           "Content-Type": "application/json"},
  json={
    "names": ["Northshore Trading GmbH"],
    "entityTypes": ["entity"],
    "country": "Syria",
    "jurisdiction": "US"
  }
)
print(json.dumps(resp.json(), indent=2))

Sample 200 OK response▾

{
  "results": [
    {
      "input": "Northshore Trading GmbH",
      "isSanctioned": false,
      "actionableHit": true,
      "decision": { "status": "BLOCK" }
    }
  ],
  "policyMatches": [],
  "scannedSources": ["un","eu","ofac","uk","seco"],
  "unavailableSources": [],
  "meta": {
    "tookMs": 123,
    "tenantId": "org_...",
    "planKey": "pro",
    "countryRisk": { "recommendation": "BLOCK", "resolvedCountryIso2": "SY" }
  }
}

Implementation note: results[].isSanctioned reflects direct name-list hits. When you supply country context, inspect results[].actionableHit, results[].decision.status, and meta.countryRisk to catch country-only blocks or review outcomes.

Connect Salesforce in one click
If your operating workflow already lives in Salesforce, send one Contact, Account, or Lead to POST /api/v1/integrations/salesforce/screen instead of building a separate compliance workflow from scratch.
This route uses the same API key model and source settings as the rest of the public API. The main difference is the response shape: it is optimized for CRM use and returns a screening status, top match summary, audit reference id, and evidence links ready to store on the Salesforce record.
cURL What to store back on the record
```
curl -sS -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"
  }' | jq
```
```
1. screening.screeningStatus
2. screening.riskLevel
3. screening.summary
4. screening.auditReferenceId
5. screening.evidence.pdfUrl
6. screening.evidence.jsonUrl
```
Tip: Send country or billing country from Salesforce whenever possible. It lets MatchAudit evaluate country-risk in the same request instead of returning a name-only answer.
Verify monthly usage
Check your current-month usage with GET /api/v1/usage/summary. This endpoint requires a credential. Recommended: server-only secret API_AUTH_SECRET (API key auth is also supported).
Set server secret
```
export API_AUTH_SECRET="wh-sec-..."
```
Query usage (cURL)
```
curl -s 'https://your-domain.com/api/v1/usage/summary?tenantId=YOUR_ORG_ID' \
  -H "Authorization: Bearer $API_AUTH_SECRET" | jq
```
Handle errors & limits
Common responses include 401 unauthorized (missing or invalid key), 429 rate_limited (per-second),429 limit_exceeded (monthly cap), and 400 too_many_names (batch cap).
Simulate 401
```
curl -X POST https://your-domain.com/api/v1/screen \
  -H "Authorization: Bearer bad_key" -H "Content-Type: application/json" \
  -d '{ "names": ["Test"], "entityTypes": ["individual"] }'
```
Per-request cap
Per-request limits are plan-based. See Pricing for current caps. Batch larger than your cap returns 400 too_many_names.
Note: Limits are plan-configured and may change. Keep client integrations flexible and avoid hard-coding caps.

Send SAP GTS exports into MatchAudit

If your trade team already works in SAP GTS, use POST /api/v1/integrations/sap-gts/sync when your middleware or scheduled export should create the same reviewable SAP GTS cases that analysts can inspect in the dashboard.

For production use, configure scheduled sync timing and automatic write-back in Integrations > SAP GTS. The sync endpoint handles the intake; the dashboard automation settings control when imports run and where reviewed decisions are sent.

If you are connecting through SAP CPI, save the connector as SAP CPI in the dashboard, store the default mapping profile for that export, and configure the SAP deep link so analysts can jump back into the native worklist.

cURL What happens next

curl -sS -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"
      }
    ]
  }' | jq

1. MatchAudit normalizes the SAP GTS rows.
2. The rows move through the same review workflow used by the dashboard SAP GTS upload page.
3. Recent sync runs appear in Integrations > SAP GTS.
4. Analysts can save draft decisions, finalize reviewed cases, lock final decisions, and export evidence.
5. Middleware can read back finalized decisions from GET /api/v1/integrations/sap-gts, or receive them automatically if write-back is enabled.

Continue to API Reference Review Authentication

5-minute Quickstart

Your first screening with the v1 API

Create an API key, run a screening request, and verify usage metering. No SDK required - just HTTP.

API Reference Authentication

Get an API key
In your dashboard, go to Settings → API Keys and create a key. Copy it and store it as an environment variable - never embed in client-side code.
macOS / Linux
```
export MATCHAUDIT_API_KEY="sk_live_..."
```
Windows (PowerShell)
```
$env:MATCHAUDIT_API_KEY="sk_live_..."
```
Review screening settings first
Before sending screening requests, confirm which sanctions lists your API workflow should use. This is a required implementation step because screening quality depends on the active source selection.
MatchAudit applies a global default source set automatically for new API users. If that default is not appropriate, update it first through PUT /api/v1/settings.
Check current settings Update settings
```
curl -sS https://your-domain.com/api/v1/settings \
  -H "Authorization: Bearer $MATCHAUDIT_API_KEY" | jq
```
```
curl -sS -X PUT https://your-domain.com/api/v1/settings \
  -H "Authorization: Bearer $MATCHAUDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jurisdiction": "global",
    "sources": ["un", "eu", "ofac", "uk", "seco"]
  }' | jq
```
Important: If you do not configure custom settings, MatchAudit will still use the global default source set. In production, you should explicitly review and confirm those settings before relying on the API response.

Make your first request

cURL Node (fetch)Python (requests)

curl -sS -X POST https://your-domain.com/api/v1/screen \
  -H "Authorization: Bearer $MATCHAUDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "names": ["Northshore Trading GmbH"],
    "entityTypes": ["entity"],
    "country": "Syria",
    "jurisdiction": "US"
  }' | jq

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"
  },
  body: JSON.stringify({
    names: ["Northshore Trading GmbH"],
    entityTypes: ["entity"],
    country: "Syria",
    jurisdiction: "US"
  })
});
console.log(await res.json());

import os, requests, json
resp = requests.post(
  "https://your-domain.com/api/v1/screen",
  headers={"Authorization": f"Bearer {os.getenv('MATCHAUDIT_API_KEY')}",
           "Content-Type": "application/json"},
  json={
    "names": ["Northshore Trading GmbH"],
    "entityTypes": ["entity"],
    "country": "Syria",
    "jurisdiction": "US"
  }
)
print(json.dumps(resp.json(), indent=2))

Sample 200 OK response▾

{
  "results": [
    {
      "input": "Northshore Trading GmbH",
      "isSanctioned": false,
      "actionableHit": true,
      "decision": { "status": "BLOCK" }
    }
  ],
  "policyMatches": [],
  "scannedSources": ["un","eu","ofac","uk","seco"],
  "unavailableSources": [],
  "meta": {
    "tookMs": 123,
    "tenantId": "org_...",
    "planKey": "pro",
    "countryRisk": { "recommendation": "BLOCK", "resolvedCountryIso2": "SY" }
  }
}

Connect Salesforce in one click
If your operating workflow already lives in Salesforce, send one Contact, Account, or Lead to POST /api/v1/integrations/salesforce/screen instead of building a separate compliance workflow from scratch.
This route uses the same API key model and source settings as the rest of the public API. The main difference is the response shape: it is optimized for CRM use and returns a screening status, top match summary, audit reference id, and evidence links ready to store on the Salesforce record.
cURL What to store back on the record
```
curl -sS -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"
  }' | jq
```
```
1. screening.screeningStatus
2. screening.riskLevel
3. screening.summary
4. screening.auditReferenceId
5. screening.evidence.pdfUrl
6. screening.evidence.jsonUrl
```
Tip: Send country or billing country from Salesforce whenever possible. It lets MatchAudit evaluate country-risk in the same request instead of returning a name-only answer.
Verify monthly usage
Check your current-month usage with GET /api/v1/usage/summary. This endpoint requires a credential. Recommended: server-only secret API_AUTH_SECRET (API key auth is also supported).
Set server secret
```
export API_AUTH_SECRET="wh-sec-..."
```
Query usage (cURL)
```
curl -s 'https://your-domain.com/api/v1/usage/summary?tenantId=YOUR_ORG_ID' \
  -H "Authorization: Bearer $API_AUTH_SECRET" | jq
```
Handle errors & limits
Common responses include 401 unauthorized (missing or invalid key), 429 rate_limited (per-second),429 limit_exceeded (monthly cap), and 400 too_many_names (batch cap).
Simulate 401
```
curl -X POST https://your-domain.com/api/v1/screen \
  -H "Authorization: Bearer bad_key" -H "Content-Type: application/json" \
  -d '{ "names": ["Test"], "entityTypes": ["individual"] }'
```
Per-request cap
Per-request limits are plan-based. See Pricing for current caps. Batch larger than your cap returns 400 too_many_names.
Note: Limits are plan-configured and may change. Keep client integrations flexible and avoid hard-coding caps.

Send SAP GTS exports into MatchAudit

cURL What happens next

curl -sS -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"
      }
    ]
  }' | jq

1. MatchAudit normalizes the SAP GTS rows.
2. The rows move through the same review workflow used by the dashboard SAP GTS upload page.
3. Recent sync runs appear in Integrations > SAP GTS.
4. Analysts can save draft decisions, finalize reviewed cases, lock final decisions, and export evidence.
5. Middleware can read back finalized decisions from GET /api/v1/integrations/sap-gts, or receive them automatically if write-back is enabled.

Continue to API Reference Review Authentication

Your first screening with the v1 API

Get an API key

Review screening settings first

Make your first request

Connect Salesforce in one click

Verify monthly usage

Handle errors & limits

Send SAP GTS exports into MatchAudit

Your first screening with the v1 API

Get an API key

Review screening settings first

Make your first request

Connect Salesforce in one click

Verify monthly usage

Handle errors & limits

Send SAP GTS exports into MatchAudit