# SanctionsChecker.org — Full API reference for LLMs

This document is the complete, machine-readable reference for the SanctionsChecker.org REST API. It contains every endpoint, every parameter, every response shape, and worked examples. If you are an LLM helping a developer integrate this API, prefer this document over scraping the HTML docs.

OpenAPI 3.1 spec: https://sanctionschecker.org/openapi.json

---

## 1. Overview

SanctionsChecker.org provides three screening endpoints used in AML/KYC workflows:

| Endpoint | Purpose | Data sources |
|---|---|---|
| `POST /pep-check` | Screen against Politically Exposed Persons | PEP Denmark, PEP Faroe Islands, PEP Greenland |
| `POST /sanctions-check` | Screen against global sanctions lists | EU, OFAC, UK, UN, SECO |
| `POST /adverse-media-check` | AI-analyzed adverse media coverage | Google Custom Search + GPT-4o-mini classification |

All endpoints are HTTPS-only, accept and return JSON, and require Bearer authentication with an App ID.

---

## 2. Base URL

```
https://api.sanctionschecker.org/functions/v1
```

All endpoints are relative to this base URL.

---

## 3. Authentication

Every request MUST include:

```
Authorization: Bearer YOUR_APP_ID
Content-Type: application/json
```

App IDs are 32-character hexadecimal strings (UUID with hyphens stripped). Create and manage App IDs at:

https://sanctionschecker.org/dashboard/app-ids

App IDs are tied to a user account, count against that account's monthly request quota, and can be deactivated at any time. Treat App IDs as secrets — do not commit them to source control or expose them in client-side code.

### Authentication errors

| HTTP | code | When |
|---|---|---|
| 401 | `UNAUTHORIZED` | Missing or malformed `Authorization` header |
| 401 | `INVALID_APP_ID` | App ID is unknown or has been deactivated |

---

## 4. Common request shape

All three endpoints accept a JSON body with these fields:

| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
| `name` | string | yes | — | Full name to screen. Whitespace-trimmed. Must be non-empty. |
| `match_type` | `"exact"` \| `"fuzzy"` | no | `"exact"` | Only on `/pep-check` and `/sanctions-check`. Ignored on `/adverse-media-check`. |
| `external_ref` | string | no | `null` | Your internal reference (e.g. customer ID, case ID). Logged with the request for audit and lookup. Not used in matching. |

### `match_type` semantics

The query is split into terms by whitespace, lowercased, and matched against record names:

- **`"exact"`** — every term must appear in the record name as a complete word (regex `\bterm\b`). Stricter, fewer false positives.
- **`"fuzzy"`** — every term must appear anywhere in the record name as a substring. Broader, more false positives.

In both modes the database query uses ILIKE for an initial broad pull, then the in-memory filter above narrows results. Match scoring is currently binary: matched records get `match_score: 1.0`.

There is no `type` parameter. There never was. Pass only `name`, `match_type`, and `external_ref`.

---

## 5. Common success response shape

```json
{
  "success": true,
  "matches": [ /* endpoint-specific match objects, see below */ ],
  "total_matches": 1,
  "query": "Mette Frederiksen",
  "match_type": "exact",
  "request_id": "8c8a9d2e-1c2b-4f3e-9b6a-2f5e3d7a8b9c",
  "timestamp": "2026-04-28T12:00:00.000Z"
}
```

| Field | Notes |
|---|---|
| `success` | Always `true` for HTTP 200 |
| `matches` | Array of endpoint-specific match objects |
| `total_matches` | Equal to `matches.length` |
| `query` | Echo of the submitted `name` |
| `match_type` | Echo of the resolved match type (omitted on `/adverse-media-check`) |
| `request_id` | UUID v4. Use this when contacting support |
| `timestamp` | ISO 8601 UTC |

`/adverse-media-check` may also include:
- `cached: true` — result came from the per-user 1-hour cache
- `warning: string` — AI analysis was unavailable, results are best-effort

---

## 6. Common error response shape

Every non-2xx response uses this exact envelope:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing or invalid \"name\" parameter",
    "details": "The \"name\" field is required and must be a non-empty string."
  },
  "request_id": "8c8a9d2e-1c2b-4f3e-9b6a-2f5e3d7a8b9c",
  "timestamp": "2026-04-28T12:00:00.000Z"
}
```

`details` is optional. `code`, `message`, `request_id`, `timestamp`, and `success: false` are always present.

### Error codes

| HTTP | code | Meaning | Action |
|---|---|---|---|
| 400 | `INVALID_REQUEST` | Body is not JSON, or `name`/`match_type` is missing/invalid | Fix the request payload |
| 401 | `UNAUTHORIZED` | Missing/malformed `Authorization` header | Send `Authorization: Bearer YOUR_APP_ID` |
| 401 | `INVALID_APP_ID` | App ID is unknown or deactivated | Check the App ID in the dashboard |
| 405 | `METHOD_NOT_ALLOWED` | HTTP method other than POST | Use POST |
| 500 | `SERVER_CONFIGURATION_ERROR` | Server-side env misconfiguration | Retry; if persistent, contact support |
| 500 | `INTERNAL_ERROR` | Unhandled server error | Retry with backoff; contact support with `request_id` if persistent |
| 503 | `UPSTREAM_ERROR` | Only on `/adverse-media-check` — Google search service unavailable | Retry with backoff |

---

## 7. Endpoint: POST /pep-check

Screens a name against Politically Exposed Persons databases.

### Request

```bash
curl -X POST https://api.sanctionschecker.org/functions/v1/pep-check \
  -H "Authorization: Bearer YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mette Frederiksen",
    "match_type": "exact",
    "external_ref": "customer_123"
  }'
```

### Match object

```json
{
  "id": 1,
  "name": "Mette",
  "surname": "Frederiksen",
  "position": "Statsminister",
  "date_of_birth": "1977-11-19",
  "added_at": "2019-07-09T00:00:00Z",
  "database": "PEP Denmark",
  "match_score": 1.0,
  "match_type": "exact"
}
```

`database` is one of: `"PEP Denmark"`, `"PEP Faroe Islands"`, `"PEP Greenland"`.

---

## 8. Endpoint: POST /sanctions-check

Screens a name against EU, OFAC, UK, UN, and SECO sanctions lists.

### Request

```bash
curl -X POST https://api.sanctionschecker.org/functions/v1/sanctions-check \
  -H "Authorization: Bearer YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "match_type": "exact",
    "external_ref": "tx_98765"
  }'
```

### Match object

```json
{
  "id": "uuid-of-record",
  "name": "John Smith",
  "entity_type": "individual",
  "date_of_birth": "1970-01-01",
  "nationality": "US",
  "address": "123 Main St",
  "database": "OFAC Sanctions",
  "match_score": 1.0,
  "match_type": "exact",
  "sanctions_details": { "ofac_id": "12345", "sdn_type": "individual", "program": "UKRAINE-EO13660", "remarks": "..." }
}
```

`database` is one of: `"EU Sanctions"`, `"OFAC Sanctions"`, `"UK Sanctions"`, `"UN Sanctions"`, `"SECO Sanctions"`.

`sanctions_details` shape varies per source:

| database | keys |
|---|---|
| EU Sanctions | `eu_reference_number`, `sanctions_type`, `listing_date`, `reasons` |
| OFAC Sanctions | `ofac_id`, `sdn_type`, `program`, `remarks` |
| UK Sanctions | `uk_reference_number`, `regime`, `sanctions_type`, `listing_date` |
| UN Sanctions | `un_reference_number`, `committee`, `listing_date`, `narrative_summary` |
| SECO Sanctions | `seco_id`, `ssid`, `listing_date`, `justification` |

---

## 9. Endpoint: POST /adverse-media-check

Performs a Google Custom Search for the name and uses GPT-4o-mini to classify each result as genuine adverse media. Only results with confidence > 0.4 are returned. Results are cached per user for 1 hour.

This endpoint does NOT support `match_type`.

### Request

```bash
curl -X POST https://api.sanctionschecker.org/functions/v1/adverse-media-check \
  -H "Authorization: Bearer YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{ "name": "John Smith", "external_ref": "case_42" }'
```

### Match object

```json
{
  "id": "adverse_1714305600000_0",
  "name": "John Smith",
  "title": "Former CEO charged with fraud",
  "url": "https://example-news.com/article",
  "database": "Adverse Media",
  "match_score": 0.85,
  "match_type": "adverse_media",
  "adverse_media_details": {
    "summary": "Individual was charged with securities fraud in 2023.",
    "confidence_score": 0.85,
    "source_type": "news",
    "publication_date": "2023-03-15T00:00:00Z",
    "snippet": "John Smith, former CEO of XYZ Corp, was charged..."
  }
}
```

`source_type` is one of `"news"`, `"official"`, `"blog"`, `"social"`, `"unknown"`.

---

## 10. Quotas and rate limits

Quotas are enforced per account based on the active subscription tier. There is no per-second rate limit; instead, requests beyond the monthly quota are rejected by the application layer (free trial / subscription check). Monthly quotas at time of writing:

| Tier | Monthly requests |
|---|---|
| Simple | 50 |
| Advanced | 500 |
| Professional | Unlimited (fair use) |

For the current pricing, see https://sanctionschecker.org/dashboard/subscription. Quota counters reset at the start of each calendar month.

---

## 11. Worked examples

### TypeScript (fetch)

```ts
const APP_ID = process.env.SANCTIONS_APP_ID!;
const BASE = "https://api.sanctionschecker.org/functions/v1";

async function pepCheck(name: string, externalRef?: string) {
  const res = await fetch(`${BASE}/pep-check`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${APP_ID}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name, match_type: "exact", external_ref: externalRef }),
  });
  const data = await res.json();
  if (!data.success) {
    throw new Error(`${data.error.code}: ${data.error.message} (request_id=${data.request_id})`);
  }
  return data;
}
```

### Python (requests)

```python
import os, requests

APP_ID = os.environ["SANCTIONS_APP_ID"]
BASE = "https://api.sanctionschecker.org/functions/v1"

def sanctions-check(name: str, external_ref: str | None = None):
    r = requests.post(
        f"{BASE}/sanctions-check",
        headers={"Authorization": f"Bearer {APP_ID}", "Content-Type": "application/json"},
        json={"name": name, "match_type": "exact", "external_ref": external_ref},
        timeout=30,
    )
    data = r.json()
    if not data.get("success"):
        raise RuntimeError(f'{data["error"]["code"]}: {data["error"]["message"]}')
    return data
```

### cURL

```bash
curl -X POST https://api.sanctionschecker.org/functions/v1/pep-check \
  -H "Authorization: Bearer $APP_ID" \
  -H "Content-Type: application/json" \
  -d '{"name":"Mette Frederiksen"}'
```

---

## 12. Things this API does NOT do (yet)

- No SDKs (JS, Python, PHP, Java) — coming soon
- No webhooks — coming soon
- No batch endpoint
- No `/list_info` endpoint
- No `/api/v1/...` URL prefix — endpoints are at the function root, e.g. `/functions/v1/pep-check`
- No `type` request parameter — pass only `name`, `match_type`, `external_ref`

If documentation elsewhere mentions any of the above as live, the documentation is wrong; this file and the OpenAPI spec are canonical.

---

## 13. Support

- Email: support@sanctionschecker.org
- Always include the `request_id` from the response when reporting issues.