---
title: "Add an entry to your block or allow list"
method: POST
path: "/lists/entries"
tags: ["Lists"]
---

# Add an entry to your block or allow list

`POST /lists/entries`

## Request

- Base URL: `https://developers.ozav.io/v2`
- URL: `https://developers.ozav.io/v2/lists/entries`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Adds a value to your organization's own block or allow list. Your lists apply to your
screenings only: a block-list match escalates `suggested_decision` (`review`, or `decline`
with `action: decline`) and always wins over an allow match; an allow-list match suppresses
only contact signals - never a block-list, sanctions or PEP match. See `type` for which
screenings each value type can match.

Values are stored as a keyed hash plus a masked hint - never in full. The same value cannot be
active twice: on the same list it returns 409 `LIST_ENTRY_EXISTS`, on the other list 409
`LIST_ENTRY_CONFLICT`; both return the existing entry id in `error.details.existing_id`.

Up to 10,000 active entries per organization and environment (a soft limit: concurrent
creations right at the limit may pass it by a few entries).

A `name` entry matches every subject with that name: a `name` block with `action: decline`
declines homonyms too. Prefer `document` or `email` for decline, and `review` for names.

Requires the `lists:write` scope (`lists:read` to list). API keys created before these scopes
existed do not gain them: create a new key with the scopes you need.

**Data protection.** Your organization is the controller of what it puts on its lists; OZAV
processes it on your behalf. Deleting an entry stops it from matching at once and keeps a
marked record as the audit trail of your due diligence; a physical purge is done by OZAV on
your written request.

## Request body

- ListEntryCreateRequest
  - `list` 'block' | 'allow', required: - `block` - subjects matching this entry escalate (`review`, or `decline` with `action`). A block match always wins over an allow match. - `allow` - suppresses only contact signals for a matching subject - never a block-list, sanctions or PEP match. A free or disposable email domain cannot be allow-listed.
  - `type` 'name' | 'document' | 'email' | 'email_domain', required: What the value is (no faces, no wallet addresses), and which screenings it can match: | type | inline subject (`person`/`business`) | `customer_id` subject | |---|---|---| | `name` | the name sent | the stored name | | `document` | never (inline screenings carry no document) | the stored tax id | | `email` | the `email` sent | the stored email | | `email_domain` | the domain of the `email` sent | the domain of the stored email |
  - `value` string, required: The value. Stored only as a keyed hash plus a masked hint - it is never returned in full.
  - `action` 'review' | 'decline': Block list only (default `review`): - `review` - a match makes `suggested_decision` `review`. - `decline` - a match makes `suggested_decision` `decline`.

## Response `201`

The entry.

- ListEntry
  - `id` string, required: The entry id (`ozav_lst_...`).
  - `object` 'list_entry', required: Always the literal `list_entry`.
  - `list` 'block' | 'allow', required: `block` or `allow`.
  - `type` 'name' | 'document' | 'email' | 'email_domain', required: The value type.
  - `action` 'review' | 'decline' | 'null', nullable: `review` or `decline` for block entries; `null` for allow entries.
  - `value_hint` string, required: A masked hint of the value (e.g. `J*** D***`, `•••789`, `j***@***`). Never the full value, never an email domain; a document shorter than 8 characters shows only `•••`.
  - `created_at` string, date-time, required: When the entry was created.

## Other responses

- `400`: The request is invalid.
- `401`: Missing or invalid API key.
- `409`: Conflict (e.g. IDEMPOTENCY_KEY_REUSED).
- `422`: The request is well-formed but cannot be fulfilled - e.g. a `rail` that is not served (see `Rail.x-ozav-rail-availability`).
- `503`: A dependency OZAV needs (storage, a resource lookup) could not be reached, so OZAV fails closed rather than guess. Safe to retry with the same `Idempotency-Key` where the operation accepts one.

---

[API](https://skmtc.dev/ozav/apis/ozav-api.md) - [All operations](https://skmtc.dev/ozav/apis/ozav-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ozav/apis/ozav-api/revisions/4133dc2109d7?raw)