> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumiid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AML Screening API: Sanctions, PEP, and Watchlist Checks

> Screen individuals and businesses against 40+ sanctions, PEP, and watchlist sources using LumiID's AML screening API. Returns HIT, REVIEW, or CLEAR.

The LumiID AML Screening API lets you screen individuals and businesses against over 40 sanctions lists, PEP registers, adverse media databases, and local watchlists in a single API call. Run it during customer onboarding, before high-value transactions, or as part of scheduled re-screening to satisfy your KYC and AML due-diligence obligations. The API returns a clear `HIT`, `REVIEW`, or `CLEAR` risk signal alongside matched records, match confidence levels, and source URLs for your compliance audit trail.

## What this endpoint screens

* **Sanctions lists** — OFAC (US), UN Security Council Consolidated List, EU Consolidated List, UK HMT, and other national sanctions authorities
* **PEP registers** — Politically exposed persons and their known associates
* **Adverse media / crime and conviction records** — Where available per jurisdiction
* **Local watchlists** — Nigeria, Kenya, Ghana, South Africa, and other supported jurisdictions

***

## Endpoint

```text theme={null}
POST https://api.lumiid.com/v1/aml/screening/
```

### Headers

| Header | Value |
| - | - |
| `Authorization` | `Bearer YOUR_API_KEY` |
| `Content-Type` | `application/json` |

### Request body

**entity\_name** `string` *required*

Full name of the individual or business to screen.

**type** `string` *required*

Entity type. Accepted values: `individual` or `business`.

**country** `array`

One or more countries associated with the entity. Providing this field improves match precision and reduces false positives.

**gender** `string`

Gender of the individual. Accepted values: `male` or `female`. Narrows candidate matches for individuals and reduces false positives.

**date\_of\_birth** `string`

Date of birth in `YYYY-MM-DD` format. Improves match precision and reduces false positives significantly.

**idempotency\_key** `string`

A unique client-generated key for this request. Reuse the same key when retrying a failed request to prevent duplicate billing or re-screening.

> [!TIP]
>
> Always provide optional fields like `date_of_birth`, `gender`, and `country` when you have them. They significantly reduce false positives against common names and improve the quality of the matches returned.

#### Example request

```json theme={null}
{
  "entity_name": "John Doe",
  "type": "individual",
  "country": ["Nigeria"],
  "gender": "male"
}
```

```bash cURL theme={null}
curl -X POST https://api.lumiid.com/v1/aml/screening/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_name": "John Doe",
    "type": "individual",
    "country": ["Nigeria"],
    "gender": "male"
  }'
```

***

## Success response

```json theme={null}
{
  "success": true,
  "code": "AML_SCREENING_COMPLETE",
  "message": "Screening completed",
  "summary": {
    "overall_risk": "HIT",
    "verification_type": "AML_SCREENING"
  },
  "data": {
    "screening_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "entity": {
      "name": "Abubakar Shekau",
      "type": "individual",
      "country": ["Nigeria"]
    },
    "overall_risk": "HIT",
    "review_required": true,
    "categories": [
      { "category": "SANCTIONS", "hits_found": 38 },
      { "category": "NIGERIA_WATCHLIST", "hits_found": 2 },
      { "category": "PEP", "hits_found": 0 },
      { "category": "ADVERSE_MEDIA", "hits_found": 0 }
    ],
    "matches": [
      {
        "matched_name": "Abubakar Mohammed Shekau",
        "category": "SANCTIONS",
        "list_name": "UN Security Council Consolidated Sanctions List",
        "authority": "United Nations Security Council",
        "country": "Nigeria",
        "match_confidence": "HIGH",
        "aliases": ["Shekau", "Shehu", "Imam Darul Tauhid"],
        "source_url": "https://www.un.org/securitycouncil/sanctions/1267/aq_sanctions_list"
      },
      {
        "matched_name": "Shehu Abubakar",
        "category": "NIGERIA_WATCHLIST",
        "list_name": "NAPTIP Sexual Offenders List",
        "authority": "National Agency for the Prohibition of Trafficking in Persons",
        "country": "Nigeria",
        "match_confidence": "MEDIUM",
        "aliases": [],
        "source_url": "https://nsod.naptip.gov.ng/result.php"
      }
    ],
    "lists_screened": 40
  },
  "meta": {
    "request_id": "req_9f8e7d6c5b4a",
    "timestamp": "2026-07-31T05:08:52Z",
    "api_version": "1.0"
  }
}
```

***

## Response fields

**success** `boolean`

Indicates whether the screening request completed successfully.

**code** `string`

Machine-readable result code. See [Response codes](#response-codes) below.

**message** `string`

Human-readable result message.

**summary** `object`

High-level screening summary.

**summary fields**

**overall\_risk** `string`

Top-level risk outcome: `CLEAR`, `REVIEW`, or `HIT`. See [overall\_risk values](#overall_risk-values) for guidance on each outcome.

**verification\_type** `string`

Always `AML_SCREENING`.

**data** `object`

Full screening result.

**data fields**

**screening\_id** `string`

Unique identifier for this screening run. Store for audit and re-screening workflows.

**entity** `object`

The entity that was screened, echoing back `name`, `type`, and `country` from your request.

**overall\_risk** `string`

Top-level risk outcome: `CLEAR`, `REVIEW`, or `HIT`.

**review\_required** `boolean`

`true` when the result is `REVIEW` or `HIT`, indicating that a human compliance reviewer should assess the result before you proceed.

**categories** `array`

Hit counts broken down by screening category. Each entry contains a `category` (e.g. `SANCTIONS`, `PEP`, `NIGERIA_WATCHLIST`, `ADVERSE_MEDIA`) and a `hits_found` integer.

**matches** `array`

Individual matched records — deduplicated, one entry per distinct list.

**matches\[n] fields**

**matched\_name** `string`

The name as it appears on the source list.

**category** `string`

Screening category the match was found in (e.g. `SANCTIONS`, `NIGERIA_WATCHLIST`).

**list\_name** `string`

The specific list on which the match was found.

**authority** `string`

The authority or body that maintains the list.

**country** `string`

Country associated with the matched record.

**match\_confidence** `string`

Bucketed match strength: `HIGH`, `MEDIUM`, or `LOW`.

**aliases** `array`

Known aliases for the matched entity as recorded on the source list.

**source\_url** `string`

Public URL of the source list entry. Use this in your compliance audit trail.

**lists\_screened** `integer`

Total number of lists checked during this screening run. Useful for audit and reporting purposes.

**meta** `object`

Request metadata.

**meta fields**

**request\_id** `string`

Unique request identifier. Store this for audit and support purposes.

**timestamp** `string`

ISO 8601 timestamp of when the screening was completed.

**api\_version** `string`

API version that produced this response.

***

## `overall_risk` values

| Value | Meaning | Recommended action |
| - | - | - |
| `CLEAR` | No hits found across all screened lists. | Safe to proceed with normal onboarding. |
| `REVIEW` | Low or ambiguous confidence matches found. | Do not proceed automatically. Route to a human compliance reviewer before making a decision. |
| `HIT` | One or more high-confidence matches found. | Escalate immediately. Apply enhanced due diligence (EDD) and do not proceed without a compliance decision. |

> [!WARNING]
>
> When `review_required` is `true`, your workflow should pause and route the case to a human reviewer before taking any onboarding or transaction action. Automated approval of `REVIEW` or `HIT` results is not recommended.

***

## Response codes

| Code | Meaning |
| - | - |
| `AML_SCREENING_COMPLETE` | Screening ran successfully. Check `overall_risk` for the outcome. |
| `AML_ENTITY_NOT_FOUND` | Insufficient identifying information to run a screen. Provide more entity details. |
| `AML_SCREENING_TIMEOUT` | An upstream list provider timed out. No charge is applied — it is safe to retry. |
| `AML_INVALID_REQUEST` | Missing or malformed required fields. Check `entity_name` and `type`. |

***

## Best practices

> [!TIP]
>
> Provide `date_of_birth`, `gender`, and `country` whenever you have them. These optional fields significantly reduce false positives, especially for common names.

* When `review_required` is `true` on a `REVIEW` result, trigger your manual review workflow rather than proceeding automatically.
* Use `idempotency_key` every time you retry a failed request to avoid double billing or duplicate screening records.
* Store `screening_id`, `request_id`, `lists_screened`, and `source_url` values from each response to build a defensible compliance audit trail.
* Run AML screening not only at onboarding but also before high-value transactions and as part of scheduled periodic re-screening of your existing customer base.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.