Lists

A list is a named set of values your rules can check against: “is this country on our high-risk list?”, “is this device on our deny list?”. Lists let you change what a rule looks for without changing the rule — add a country to the high-risk list and every rule that uses the list picks it up within about 15 seconds, with no new rule version and no approval round.

On screen or through the API

In the app, lists are on the Rules page, in the Lists panel: create a list, add values with a source note, and remove values (step by step: Managing lists). The same can be done through the Lists API. Until a list exists and has values, rules that need it simply don’t fire (see below). Don’t edit list tables in the database by hand: nothing would be checked or written to the audit log.

Kinds of list

Kind	Purpose	Example
Allow	Values you trust, which rules can skip	Your own settlement accounts; a known payroll bureau
Deny	Values you do not want to deal with	Accounts of exited customers; devices linked to confirmed fraud
Reference	Values a rule needs to know about, neither good nor bad in themselves	FATF high-risk countries; high-risk merchant category codes; border regions

What a list can hold

Every list holds one type of item, chosen when the list is created:

Item type	Example values	What SpeculaPro checks when you add one
country	IR, KP, MM	Two letters. Lowercase is turned into uppercase, so ir is stored as IR
mcc	7995 (betting), 6051 (quasi-cash)	Exactly four digits
customer, account, counterparty, device	Your own references for these records	1 to 256 characters
ip	196.61.12.4	1 to 256 characters
text	Anything else	1 to 256 characters

Spaces at either end of a value are removed. A value that fails these checks rejects the whole request, and nothing from it is added.

Each item can have a note: why it is there. Notes are set for each batch of values you add.

Each item can also have an end date (expires_at). After it, rules stop seeing the value within about 15 seconds, without anyone removing it, which suits temporary measures such as blocking a device while a fraud case is open. The expired value stays visible on the list, marked as expired, until someone removes it, and adding it again brings it back. An end date can be cleared at any time to keep the value for good. See Managing lists.

Planned: protected identifiers

The database has room for an identifier_hash item type, for phone or ID numbers matched without storing them in clear. It can’t be used yet.

How rules use lists

Every list has a key — lowercase letters, digits and underscores, such as high_risk_countries. Rules refer to a list by its key, as lists.<key>. For example, E1 checks whether a transfer’s country or counterparty country is in lists.high_risk_countries.

What a rule sees is simply the list’s current values, as text:

• Only items that have not expired are included.
• Values are compared exactly. Country lists are upper-cased for you, but the codes must still be the ones your transactions use (IR, not Iran). Merchant codes must match the four digits as sent (7995). Other values must match character for character, including capital letters.
• The list’s kind (allow, deny, reference) describes its purpose for people. Rules don’t treat the kinds differently: what matters is how the rule uses the list.
• The evaluator re-reads lists every 15 seconds.

Until a list exists, rules that need it don’t fire

A list with no current items is treated as not existing.

• Rules in SpeculaPro’s own packs check for the list first. If it is missing, they quietly don’t fire: E1 needs high_risk_countries, and H4 needs high_risk_mcc. Installing those rules without creating the lists therefore does nothing, without any error.
• A custom rule that names a missing list as lists.my_list (or lists["my_list"]) sees an empty list, so it doesn’t fire either, and nothing is logged. Write the key out in one of those two forms so SpeculaPro can spot it. See Lists in rules.

Create the lists your rules need when you install a pack

After installing the core pack, create and fill high_risk_countries and high_risk_mcc, or E1 and H4 will never fire. See Pack contents.

Rules depend on list keys

A rule refers to a list by its key, and the key can’t be changed once the list exists. A typing mistake in the key means rules looking for the right key won’t find it. The name and description can be changed at any time. Each list in GET /api/v1/lists shows used_by: the running rules whose live version mentions it.

A list can be deleted, with all its values, only once no rule version that could still run refers to it: not a rule’s current version (even if the rule is switched off), a shadow test, a draft, or a version awaiting approval. Deleting a list a rule depends on would silently empty that rule’s input, so SpeculaPro refuses and names the rules.

How to create and fill a list with the API

To script changes, for example a quarterly FATF update, use the Lists API, signed in as yourself with curl (see before you start). This example creates the list that E1 needs.

1. Create the list. The key is 2 to 64 lowercase letters, digits or underscores:

   curl -s -b ~/.sp-cookies -H 'Content-Type: application/json' \
     -d '{"key":"high_risk_countries","name":"High-risk jurisdictions (FATF + internal)","kind":"reference","item_type":"country"}' \
     "$SP/api/v1/lists"

   The answer is 201. A list with that key already existing gives 409.

2. Add values, up to 1,000 at a time, with a note:

   curl -s -b ~/.sp-cookies -H 'Content-Type: application/json' \
     -d '{"values":["IR","KP","MM"],"note":"FATF call for action, public statement October 2026"}' \
     "$SP/api/v1/lists/high_risk_countries/items"

   The answer tells you how many were added; values already on the list are skipped.

3. Check it. GET /api/v1/lists shows the item count and which live rules use it. Rules pick up the change within about 15 seconds.

4. Remove a value when it no longer applies. It is cleaned the same way as when it was added, so mm and MM both remove MM from a country list:

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

Who can change lists

Creating, editing and deleting lists needs lists.manage — with the built-in roles, only the MLRO. Seeing lists and their values needs rules.view. That is deliberate: adding an account to an allow list can stop it from alerting, so it carries the same weight as approving a suppression.

Every change to a list is recorded in the audit log.

Worked example: high-risk countries

The FATF publishes, several times a year, a list of jurisdictions under increased monitoring and those subject to a call for action. Kweku Pay keeps a reference list:

Field	Value
Key	high_risk_countries
Name	High-risk jurisdictions (FATF + internal)
Kind	Reference
Item type	Country

When the FATF updates its lists, the MLRO adds and removes countries with a note citing the FATF statement and date. Rule E1 — and any other rule that refers to lists.high_risk_countries — uses the change within about 15 seconds.

Keep the source in the note

“Added per FATF public statement, October 2026” in an item’s note answers the examiner’s first question before they ask it.

Allow list or suppression?

Both reduce alerts. Use:

• an allow list for values that are trusted across many rules and do not need a review date — your own accounts, for example;
• a suppression for an explained exception that should be reviewed — it always expires, needs a second approver, and keeps every suppressed hit.

When in doubt, use a suppression. It leaves a better trail.

Related

• Lists API
• Risk designations
• Suppressions
• E. Geography and high-risk exposure