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

# GET /v1/identity/watchlist — Sanctions and PEP Screening

> GET /v1/identity/watchlist — screen a user against global sanctions, PEP lists, and adverse media databases. Returns match status and matched entries.

Watchlist screening checks a user's identity against global sanctions lists, politically exposed person (PEP) databases, and adverse media sources to support your Anti-Money Laundering (AML) and compliance obligations. FraudEG aggregates data from OFAC, EU sanctions, UN sanctions, and multiple PEP and adverse media providers into a single API call — so you can fulfill regulatory screening requirements without managing multiple third-party integrations yourself.

## Endpoint

```http theme={null}
GET https://api.fraudeg.com/v1/identity/watchlist?user_id={user_id}
```

## Request Headers

| Header          | Value              | Required |
| --------------- | ------------------ | -------- |
| `Authorization` | `Bearer <API_KEY>` | Yes      |

## Query Parameters

<ParamField query="user_id" type="string" required>
  Your internal user ID. The user must have an existing identity record on FraudEG (created via `POST /v1/identity/verify`). FraudEG uses the stored identity data to perform the screening.
</ParamField>

<ParamField query="lists" type="string">
  Comma-separated list of watchlist databases to screen against. Omit this parameter to screen against all available lists by default. Accepted values:

  * `ofac` — OFAC Specially Designated Nationals (SDN) list
  * `eu_sanctions` — EU Consolidated Sanctions List
  * `un_sanctions` — UN Security Council Consolidated List
  * `pep` — Politically Exposed Persons database
  * `adverse_media` — Adverse media and negative news sources

  **Example:** `?user_id=usr_8f3kd92&lists=ofac,pep`
</ParamField>

<ParamField query="name" type="string">
  Screen by name directly, without requiring the user to have an existing identity record in FraudEG. Use this for one-off lookups during onboarding before you call `/v1/identity/verify`.
</ParamField>

<ParamField query="date_of_birth" type="string">
  ISO 8601 date (`YYYY-MM-DD`). Provide this alongside `name` to narrow matches and reduce false positives when multiple entities share the same name.
</ParamField>

## Response Fields

<ResponseField name="user_id" type="string">
  Your internal user ID, echoed back from the request.
</ResponseField>

<ResponseField name="status" type="string">
  Overall screening result. One of:

  * `clear` — No matches found across all screened lists.
  * `match` — A high-confidence match was found. Do not proceed until reviewed.
  * `possible_match` — A potential match was found with lower confidence. Manual review is required.
</ResponseField>

<ResponseField name="matches" type="array">
  List of match objects. This array is empty when `status` is `clear`.

  <Expandable title="match object fields">
    <ResponseField name="list" type="string">
      The watchlist database that returned this match (e.g., `ofac`, `pep`, `adverse_media`).
    </ResponseField>

    <ResponseField name="match_score" type="number">
      Confidence score for this match, from `0` (no confidence) to `1` (exact match). Scores above `0.85` indicate a high-confidence match.
    </ResponseField>

    <ResponseField name="entity_name" type="string">
      The name of the matched entity as it appears in the watchlist database.
    </ResponseField>

    <ResponseField name="entity_type" type="string">
      Whether the matched entity is an `individual` or an `organization`.
    </ResponseField>

    <ResponseField name="reason" type="string">
      A plain-language description of why the entity is listed (e.g., `"Designated for sanctions violations"`, `"Senior government official"`, `"Subject of money laundering investigation"`).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="screened_at" type="string">
  ISO 8601 timestamp of when the screening was performed (e.g., `"2024-11-15T13:20:00Z"`).
</ResponseField>

## Code Example

```bash cURL theme={null}
curl --request GET \
  --url 'https://api.fraudeg.com/v1/identity/watchlist?user_id=usr_8f3kd92&lists=ofac,pep,eu_sanctions' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

### Example Response — Clear

```json theme={null}
{
  "user_id": "usr_8f3kd92",
  "status": "clear",
  "matches": [],
  "screened_at": "2024-11-15T13:20:00Z"
}
```

### Example Response — Possible Match

```json theme={null}
{
  "user_id": "usr_4t7pZ9kM",
  "status": "possible_match",
  "matches": [
    {
      "list": "pep",
      "match_score": 0.74,
      "entity_name": "John M. Williams",
      "entity_type": "individual",
      "reason": "Senior government official — Ministry of Finance"
    }
  ],
  "screened_at": "2024-11-15T13:22:00Z"
}
```

<Note>
  A `possible_match` status means FraudEG found an entity with a similar name or profile, but the confidence score is below the threshold for a confirmed match. You must complete a manual review before onboarding or transacting with this user. Record the outcome of your review using `POST /v1/decisions` to maintain a complete compliance audit trail.
</Note>