Tenant Lists

Manage your own allowlists and blocklists for the screening engine.

Tenant-managed screening lists let you push your own allowlist or blocklist entries into the same fuzzy-match engine that backs sanctions / PEP screening. Hits against tenant lists surface in /api/v1/fraud/screen responses alongside global hits, with a listKind of tenant_blocklist or tenant_allowlist.

When to use which kind

Kind	Effect on screen	Typical use
tenant_blocklist	Counts toward the default kinds filter — every screen hits this list automatically.	Internal denylists: known fraudsters, charged-back customers, banned merchant counterparties.
tenant_allowlist	Off by default — caller must opt in via kinds: [..., 'tenant_allowlist'].	Trusted-counterparty lists used by rules to suppress false positives or relax verdict bands.

Allowlist hits never block on their own — they're informational. Use them inside rule conditions to express "treat this counterparty as safe".

Endpoints

Method	Path	Description
GET	/api/v1/fraud/lists	List the org's tenant lists
POST	/api/v1/fraud/lists	Create a tenant list
GET	/api/v1/fraud/lists/:id	Fetch one list
PATCH	/api/v1/fraud/lists/:id	Rename (only name is mutable)
DELETE	/api/v1/fraud/lists/:id	Hard delete (cascades to entries)
GET	/api/v1/fraud/lists/:id/entries	List entries (paginated)
POST	/api/v1/fraud/lists/:id/entries	Bulk add entries (≤ 1,000 per request)
DELETE	/api/v1/fraud/lists/:id/entries/:entryId	Remove one entry

Property	Value
Scope	fraud:manage
Plan gate	Detection Pack addon (Pro or Enterprise)
Rate limit	500 requests / hour per API key

The global sanctions / PEP / adverse-media lists are admin-managed and refreshed via the daily ingest cron — they cannot be created, updated, or deleted from this surface.

Create a list

curl -X POST https://api.platformxe.com/api/v1/fraud/lists \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "source": "internal-blocklist-v1",
    "name": "Internal blocklist",
    "kind": "tenant_blocklist"
  }'

Field	Type	Required	Description
source	string	Yes	Stable identifier, unique within your organisation. Allowed: alphanumerics + -, _, ., :. ≤ 200 chars.
name	string	Yes	Display name. ≤ 200 chars.
kind	"tenant_blocklist" | "tenant_allowlist"	Yes	Determines screening behaviour (see When to use which kind).

Returns 201 with the created list summary. A duplicate source returns 409 CONFLICT.

Add entries (bulk)

curl -X POST https://api.platformxe.com/api/v1/fraud/lists/slst_xxx/entries \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_..." \
  -d '{
    "entries": [
      { "name": "Jane Doe", "country": "NG" },
      { "name": "John O'Brien", "dob": "1980-04-15", "identifiers": { "bvn": "12345678901" } },
      { "name": "Acme Bad Co.", "raw": { "case_id": "CASE-9281", "notes": "chargeback ring" } }
    ]
  }'

Field	Type	Required	Description
entries[].name	string	Yes	Primary identifier. Will be canonicalised (lowercase, diacritics stripped, honorifics dropped, punctuation collapsed) before storage.
entries[].dob	string	No	ISO date. Used as a soft filter at screen time.
entries[].country	string	No	ISO 3166-1 alpha-2. Auto-uppercased.
entries[].identifiers	Record<string,string>	No	Tenant-specific ids (BVN, NIN, internal case ids). Not used for fuzzy match — preserved for case reconstruction.
entries[].raw	object	No	Raw payload retained alongside the entry for audit. Falls back to { name, dob, country, identifiers } when omitted.

Limits: ≤ 1,000 entries per request. Larger uploads should be split client-side. The endpoint is idempotent — pass an Idempotency-Key header to deduplicate retries.

Search behaviour

Entries are normalised at write-time using the same pipeline as the screen query, so:

"Dr. Jane O'Brien-Smith Jr"   →   "jane o brien smith"
"São Paulo"                    →   "sao paulo"
"Côte d'Ivoire"                →   "cote d ivoire"

This keeps the GIN trigram index from migration 0018_screening_pg_trgm.sql consistent across all access paths.

Deletion semantics

DELETE /api/v1/fraud/lists/:id is a hard delete. The list and all its entries are removed via the cascading FK constraint. There is no soft-delete or tombstone — past fraud_screen_results rows still reference deleted entries, but the source list is gone.

If you want to retire a list without losing the audit trail, prefer renaming it (PATCH) and removing entries one-by-one, or stop pointing rules at it.

Errors

HTTP	Code	Cause
400	BAD_REQUEST	Validation failure: missing or invalid field, source format, kind not in tenant_*, oversized batch.
401	UNAUTHORIZED	Missing or invalid API key.
402	DETECTION_PACK_REQUIRED	Detection Pack addon not enabled.
403	FORBIDDEN	API key has no organisation context, or wrong scope.
404	NOT_FOUND	List or entry unknown, or belongs to a different org.
409	CONFLICT	Duplicate source for an existing list.
429	RATE_LIMITED	500/hr ceiling exceeded.
500	INTERNAL_ERROR	Unexpected service failure.