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

# Screen a party

> Screen a name against denied-party and sanctions lists.

Requires the `screen:read` scope.

Screens the `name` — and, when given, the `company` as a second query with
results merged — against the active screening lists. Matching is exact
case-insensitive (score `1.0`) plus fuzzy similarity over names and
alternate names; hits scoring **0.7 or higher** are returned, top 20 by
score. Every request is logged as compliance evidence.

<Note>
  Unlike the other endpoints, this response has **no `success`/`message`
  envelope** — the body is the result object directly.
</Note>

<ParamField body="name" type="string" required>
  The party name to screen (person or organisation), 1–500 chars.
</ParamField>

<ParamField body="company" type="string">
  Company name — screened as a second query; an entry hit by both keeps
  its best score.
</ParamField>

<ParamField body="address" type="object">
  Optional address, currently informational (matching is name-based):
  `line_1`, `city`, `state`, `postal_code`, `country_code` (ISO alpha-2).
</ParamField>

<ParamField body="type" type="string">
  `individual` or `entity` — narrows hits to that party type (vessel,
  aircraft, and unclassified listings are always kept in scope).
</ParamField>

## Response

<ResponseField name="matches" type="array">
  Best score first. Each match:

  * `score` — 0.7–1.0 (1.0 = exact name or alt-name match)
  * `list_code` — which screening list the entry is on
  * `entry` — the listing: `name`, `alt_names`, `entry_type`
    (`individual` | `entity` | `vessel` | `aircraft` | `unknown`),
    `programs`, `addresses`, `source_ref`, `remarks`
</ResponseField>

<ResponseField name="match_count" type="number">
  Number of matches returned.
</ResponseField>

<ResponseField name="searched_lists" type="array">
  Codes of every active list that was screened against.
</ResponseField>

Your reference for this call is the **`X-Request-Id` response header** (a
UUIDv7) — quote it to support or look it up via
[`GET /api/requests`](/api-reference/api-requests/list) to retrieve the
archived original payload.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://{partner}.mytraddal.com/admin/api/v1/screen \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {access_token}' \
    -d '{
      "name": "John Doe",
      "company": "Acme Trading FZE",
      "address": {
        "line_1": "12 Harbour Rd",
        "city": "Dubai",
        "country_code": "AE"
      },
      "type": "individual"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "matches": [
      {
        "score": 0.82,
        "list_code": "SDN",
        "entry": {
          "name": "DOE, John",
          "alt_names": ["DOE, Jonathan"],
          "entry_type": "individual",
          "programs": ["SDGT"],
          "addresses": [
            { "city": "Dubai", "country": "United Arab Emirates" }
          ],
          "source_ref": "12345",
          "remarks": null
        }
      }
    ],
    "match_count": 1,
    "searched_lists": ["EL", "SDN", "UVL"]
  }
  ```
</ResponseExample>

A connectivity check is available at `GET /screen/health`, returning
`{ "status": "ok", "service": "screen" }`.