> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dojah.io/llms.txt
> Use this file to discover all available pages before exploring further.
# AML screening
> Screen an individual or organization against global PEP, sanctions, warning and adverse-media lists, and read every match in one call.
POST
/api/v1/aml/v2/screening
Screen an individual or organization against global PEP, sanctions, warning and adverse-media lists — across 200+ countries and 40,000+ databases — and get back every match in one call.
## Headers
| Header | Required | Description |
| --------------- | -------- | --------------------------------------------------- |
| `Authorization` | Yes | Your app's secret key, sent as-is — *not* `Bearer`. |
| `AppId` | Yes | The App ID from your dashboard. |
| `Content-Type` | Yes | `application/json` |
## Body parameters
| Parameter | Type | Required | Description |
| --------------------------------------- | ------- | -------- | ------------------------------------------------------------------- |
| `schema` | string | Yes | What you're screening — `"individual"` or `"organization"`. |
| `unique_reference` | string | No | Your own reference for the request, echoed back for reconciliation. |
| `properties.names` | string | Yes | The full name to screen (e.g. `"John Doe"`). |
| `properties.gender` | string | No | e.g. `"male"` — narrows the candidate set. |
| `properties.date_of_birth` | string | No | `YYYY-MM-DD`. Strengthens match scoring. |
| `properties.nationality` | string | No | The subject's nationality. |
| `properties.id_number` | string | No | A government-issued ID number. |
| `properties.registration_number` | array | No | Business registration numbers — `organization` schema only. |
| `properties.country_of_incorporation` | array | No | Country codes — `organization` schema only. |
| `screening_options.pep_check` | boolean | No | Screen against politically-exposed-person registries. |
| `screening_options.sanction` | boolean | No | Screen against sanctions lists. |
| `screening_options.adverse_media_check` | boolean | No | Screen against adverse media. |
| `screening_options.watchlists` | array | No | Restrict to specific watchlists, or omit/leave empty to search all. |
| `screening_options.match_threshold` | number | No | Minimum match score to return, `0`–`1` (e.g. `0.85`). |
| `properties` | | No | |
| `screening_options` | | No | |
## What gets screened
Every result carries a `source_type` identifying which kind of list it came from:
| Category | What it covers |
| --------------- | ---------------------------------------------------------------------------------------------------------- |
| `PEP` | Politically exposed persons — current and former office-holders and their close associates. |
| `Sanctions` | Global and regional sanctions and embargo lists (OFAC, UN, EU and more). |
| `Adverse Media` | Negative news — categorised (e.g. `violent_crime`, `terrorism`, `political`) with the underlying articles. |
| `Warning` | Regulatory and law-enforcement warning lists. |
The overall record is graded with a `risk_level` (e.g. Low / Medium / High) and a `match_status` — one of **No Match**, **Partially Matched**, **Potential Match** or **Confirmed Match**.
## Response
Returns an `entity` with the `search_query`, `total_results` / `total_articles` counts, an overall `risk_level` and `match_status`, and a `results` array. Each result is either a **profile match** (`source_type` such as `"PEP"`, with names, aliases, positions, country and dates of birth, and `match: true`) or an **adverse-media group** (`source_type: "ADVERSE_MEDIA"` with a `media_category` and an `articles` array). The response opposite is trimmed for readability.
## Fetch match details
An individual screen returns its matches inline. To pull the full, normalised detail for a single profile — or to retrieve results from a [business screen](/api-reference/aml-background/business-screening), which returns only lightweight candidates — call `GET /api/v2/aml/screening/info` with the `profile_id` from the screen as a query parameter.
```bash cURL theme={null}
curl "https://api.dojah.io/api/v2/aml/screening/info?profile_id=57994afb-357b-4288-bc5d-9f3954d037e3" \
-H "Authorization: {{secret_key}}" \
-H "AppId: {{app_id}}"
```
The result `entity.result` exposes a numeric `match_score` (`0`–`1`), an `entryCategory` (`"PEP"`, `"sanction"`, `"adverse-media"` or `"warning"`), a `watch` flag, the subject’s `aliases`, `dob` and `countryName`, and — for adverse media — a `media` array of `title` / `snippet` / `url` / `date`. Trimmed below.
```json 200 — /api/v2/aml/screening/info theme={null}
{
"entity": {
"result": {
"name": "John Doe Musa",
"aliases": [ { "name": "John D. Musa" } ],
"firstName": "John",
"lastName": "Musa",
"dob": "1985",
"countryName": "Nigeria",
"entryCategory": "adverse-media",
"watch": false,
"media": [
{
"date": "2022-12-22T00:00:00Z",
"title": "2022 in Review: Key Financial Crime Moments",
"snippet": "… found guilty of laundering money from various online crimes …",
"url": "https://complyadvantage.com/insights/…"
}
],
"entityType": "person",
"riskLevel": "",
"match_score": 0.7
}
}
}
```
## Errors
| Code | Meaning |
| ----- | --------------------------------------------------------------------------------------------- |
| `400` | Bad request — a required field is missing or malformed. |
| `401` | Unauthorized — check your key and `AppId` (no `Bearer` prefix). |
| `402` | Insufficient wallet balance. [Fund your wallet](/api-reference/core-concepts/wallet-billing). |
| `429` | Too many requests — back off and retry. |
```bash cURL theme={null}
curl -X POST "https://api.dojah.io/api/v1/aml/v2/screening" \
-H "Authorization: {{secret_key}}" \
-H "AppId: {{app_id}}" \
-H "Content-Type: application/json" \
-d '{
"schema": "individual",
"unique_reference": "ref_8821",
"properties": {
"names": "John Doe",
"date_of_birth": "1985-04-15",
"nationality": "NG"
},
"screening_options": {
"pep_check": true,
"sanction": true,
"adverse_media_check": true,
"match_threshold": 0.85
}
}'
```
```js Node.js theme={null}
const res = await fetch("https://api.dojah.io/api/v1/aml/v2/screening", {
method: "POST",
headers: {
Authorization: process.env.DOJAH_SECRET_KEY,
AppId: process.env.DOJAH_APP_ID,
"Content-Type": "application/json",
},
body: JSON.stringify({
schema: "individual",
properties: { names: "John Doe", date_of_birth: "1985-04-15" },
screening_options: { pep_check: true, sanction: true, adverse_media_check: true }
}),
});
const data = await res.json();
```
```python Python theme={null}
import os, requests
res = requests.post(
"https://api.dojah.io/api/v1/aml/v2/screening",
headers={
"Authorization": os.environ["DOJAH_SECRET_KEY"],
"AppId": os.environ["DOJAH_APP_ID"],
},
json={
"schema": "individual",
"properties": { "names": "John Doe", "date_of_birth": "1985-04-15" },
"screening_options": { "pep_check": True, "sanction": True, "adverse_media_check": True },
},
)
data = res.json()
```
```json POST /api/v1/aml/v2/screening theme={null}
{
"entity": {
"entity_type": "individual",
"entity_id": "123450987qwergoi",
"date": "2026-01-20T10:15:10.257Z",
"total_results": 47,
"total_articles": 43,
"search_query": "John Doe",
"risk_level": "Medium",
"match_status": "Confirmed Match",
"results": [
{
"name": [ "John Doe Adekunle" ],
"entity_type": "individual",
"source_type": "PEP",
"date_of_birth": [ "1952-03-29" ],
"gender": [ "male" ],
"country": [ "ng" ],
"positions": [ "Senator", "State Governor (1999-2007)" ],
"match": true
},
{
"source_type": "ADVERSE_MEDIA",
"media_category": "political",
"articles": [
{
"timestamp": "2025-06-01T01:27:35Z",
"headline": "Opposition queries spending under President's tenure",
"source": "https://example.news/article/70169100"
}
]
}
]
}
}
```