Lists API

Lists are named sets of values, such as high-risk countries or betting merchant codes, that rules check against as lists.<key>. These endpoints create lists and change their values. Rules pick up changes within about 15 seconds, with no new rule version.

In the app, lists are managed in the Lists panel of the Rules page; see Managing lists. This page is for scripting bulk changes and for checking exactly what is stored.

Before you start

Who can call them. Signed-in people only; an API key gets 401 sign in required. Reading lists needs rules.view; changing them needs lists.manage, which by default only the MLRO has. Every change is written to the audit log under your name.

Signing in with curl. Sign in once and keep the session cookie, as described in Alerts and cases API: before you start. Then add -b ~/.sp-cookies to every request below.

Endpoints at a glance

Endpoint	Does	Permission	Success
GET /api/v1/lists	Every list, with item counts and the rules using it	rules.view	200
POST /api/v1/lists	Create a list	lists.manage	201 {"id": …}
GET /api/v1/lists/{key}/items	The values on a list	rules.view	200
PATCH /api/v1/lists/{key}	Rename a list or change its description	lists.manage	204
DELETE /api/v1/lists/{key}	Delete a list and its values	lists.manage	204
POST /api/v1/lists/{key}/items	Add values, optionally with an end date	lists.manage	200 {"added": n}
PATCH /api/v1/lists/{key}/items	Set or clear one value’s end date	lists.manage	204
DELETE /api/v1/lists/{key}/items?value=…	Remove one value	lists.manage	204

List the lists

GET /api/v1/lists

Each list, in name order:

Field	Meaning
id, key, name	Its ID, the key rules use, and its display name
kind	allow, deny or reference
item_type	What it holds (see below)
description	Free text, empty if none
items	How many values currently apply: values past their end date aren’t counted
used_by	Keys of the running (enabled) rules whose live version mentions this list, as lists.<key> or lists["<key>"]. Empty means no running rule uses it
updated_at	When it last changed

Check used_by before you change a list

Adding a country to high_risk_countries changes what every rule in used_by does, straight away. An empty used_by on a list you expected to matter usually means the rule that needs it isn’t running, or refers to a different key.

Create a list

POST /api/v1/lists

Field	Required	Rules	Meaning
key	Yes	2 to 64 lowercase letters, digits or underscores	How rules refer to it. Can’t be changed later
name	Yes	2 to 120 characters	What people see
kind	Yes	allow, deny, reference	Its purpose. Rules don’t treat kinds differently
item_type	Yes	country, mcc, customer, account, counterparty, device, ip, text	What its values are
description	No	Up to 1,000 characters	Where the values come from and who maintains them

curl -s -b ~/.sp-cookies -H 'Content-Type: application/json' \
  -d '{"key":"high_risk_mcc","name":"High-risk merchant categories","kind":"reference","item_type":"mcc",
       "description":"Gambling and quasi-cash MCCs; reviewed quarterly by the MLRO"}' \
  "$SP/api/v1/lists"

A list with the same key already in your workspace gives 409.

Read a list’s values

GET /api/v1/lists/{key}/items

Every value, alphabetically, up to 5,000: value, note, expires_at (left out when the value has no end date), added_by (display name) and created_at. Values past their end date are still listed until someone removes them; rules ignore them.

curl -s -b ~/.sp-cookies "$SP/api/v1/lists/high_risk_countries/items"

Add values

POST /api/v1/lists/{key}/items

Field	Required	Rules
values	Yes	1 to 1,000 values
note	No	Up to 500 characters. Applied to every value added in this request
expires_at	No	RFC 3339 time, in the future

Before saving, each value is cleaned and checked against the list’s item type:

Item type	Check
country	Spaces trimmed, upper-cased, then exactly two letters: gh becomes GH; Ghana is refused
mcc	Spaces trimmed, then exactly four digits
Everything else	Spaces trimmed, then 1 to 256 characters

If any value fails, the whole request is refused with 422 and nothing is added. The same value twice in one request (after cleaning, so ir and IR) counts once.

Values already on the list are skipped, keeping their existing note and end date; to change an end date, use PATCH. A value that is on the list but past its end date is brought back instead, with this request’s note and expires_at, and counts as added. The answer says how many were actually added:

curl -s -b ~/.sp-cookies -H 'Content-Type: application/json' \
  -d '{"values":["7995","6051","7801"],"note":"Gambling and quasi-cash; MLRO review October 2026"}' \
  "$SP/api/v1/lists/high_risk_mcc/items"

{ "added": 3 }

A temporary block on a device for two weeks:

curl -s -b ~/.sp-cookies -H 'Content-Type: application/json' \
  -d '{"values":["dev-7f3a9c"],"note":"Account takeover investigation, case SP-2026-000519","expires_at":"2026-10-23T23:59:59Z"}' \
  "$SP/api/v1/lists/blocked_devices/items"

Set or clear a value’s end date

PATCH /api/v1/lists/{key}/items

Field	Required	Rules	Meaning
value	Yes	1 to 256 characters	The value, cleaned as when it was added
expires_at	Yes	RFC 3339 time, or null	The new end date, or null to keep the value until it is removed

# Keep this device blocked for good
curl -s -b ~/.sp-cookies -X PATCH -H 'Content-Type: application/json' \
  -d '{"value":"dev-7f3a9c","expires_at":null}' \
  "$SP/api/v1/lists/blocked_devices/items"

A value that isn’t on the list gives 404. A time in the past ends the value straight away.

Rename or describe a list

PATCH /api/v1/lists/{key}

Field	Required	Rules
name	No	2 to 120 characters
description	No	Up to 1,000 characters. An empty string clears it

Send only what you want to change. The key, kind and item_type can’t change: rules refer to the key, and the values were checked against the item type. The audit entry (list.update) keeps the name and description before and after.

curl -s -b ~/.sp-cookies -X PATCH -H 'Content-Type: application/json' \
  -d '{"description":"FATF call-for-action and increased-monitoring jurisdictions; reviewed after each plenary"}' \
  "$SP/api/v1/lists/high_risk_countries"

Delete a list

DELETE /api/v1/lists/{key}

Deletes the list and every value on it. This can’t be undone; the audit entry (list.delete) records the key and how many values it had.

It is refused with 409 while any rule version that could still run refers to the list: a rule’s current version (even if the rule is switched off), a shadow test, a draft, or a version awaiting approval. The message names the rules, for example conflict: rules still use this list (core.high_risk_jurisdiction); change them first. This is stricter than used_by, which lists only running rules.

curl -s -b ~/.sp-cookies -X DELETE "$SP/api/v1/lists/old_watch_devices"

Remove a value

DELETE /api/v1/lists/{key}/items?value=…

Removes one value. It is cleaned the same way as when it was added, so on a country list gh removes GH. A value that isn’t on the list gives 404.

curl -s -b ~/.sp-cookies -X DELETE "$SP/api/v1/lists/high_risk_mcc/items?value=7801"

Errors

Status	Meaning	Examples
401	Not signed in, or called with an API key	sign in required
403	Missing permission	missing permission lists.manage
404	No list with that key, or no such value on it	not found
409	The key is taken, or rules still use a list you are deleting	a list with key "high_risk_mcc" exists; conflict: rules still use this list (core.high_risk_jurisdiction); change them first
422	A field fails its rules: a key with capitals, an unknown kind or item type, more than 1,000 values, a value that fails its item-type check, or an expires_at in the past when adding	Lists each problem; invalid: "Ghana" is not a 2-letter country code; invalid: "795" is not a 4-digit MCC; invalid: expires_at must be in the future

How to set up the lists the core pack needs

The core pack’s E1 and H4 rules don’t fire until their lists exist and have values. See Pack contents.

1. Create high_risk_countries: kind reference, item type country.
2. Add the countries your policy names, with a note citing the source and date.
3. Create high_risk_mcc: kind reference, item type mcc, and add the codes.
4. Check GET /api/v1/lists: both should show a non-zero items count and, if E1 and H4 are running, their keys in used_by.

Related

• Lists
• Lists in rules
• E. Geography and high-risk exposure