Suppressions

Some customers trip the same rule every month for a reason you already understand — a company’s payroll run, a church collecting Sunday offerings by MoMo, a distributor paying dozens of retailers. Investigating the same explained activity every month wastes analyst time and buries the alerts that matter.

A suppression is a formal, time-limited exception: “for this subject and this rule, until this date, do not raise alerts — and here is why.”

On screen or through the API

In the app, propose a suppression from the customer’s page with Suppress alerts (for one rule or all rules, optionally only for one counterparty, for 7 to 365 days). Approvers find it under Suppressions to approve on the Rules page (step by step: Suppressing alerts). Everything can also be done through the Suppressions API. Whichever way you use, a suppression has no effect until a second person approves it.

Don’t create suppressions by editing the database directly: you would bypass the reason, expiry and approval checks, and no audit entry would be written.

The guard rails

Suppressions are powerful — a careless one can hide real laundering — so they are constrained on purpose.

Guard rail	What it means
Always time-limited	Every suppression lasts between 1 and 365 days. There is no “forever”.
Always explained	A reason of at least 10 characters is required: the business explanation an examiner will read.
Approved by someone else	The approver must be a different person from the one who proposed it. Until then it does nothing.
Rejected with a reason	An approver who turns a proposal down must say why (at least 3 characters). The proposer sees the reason.
Never hides evidence	Suppressed hits are still stored, marked with the suppression that covered them.
Revocable	It can be withdrawn or ended before it expires; who did it, when and (optionally) why is recorded.

Suppressed is not deleted

A suppressed hit does not create an alert, but it is kept with everything a normal hit records. If the suppression turns out to be wrong, you can see every hit it swallowed. Auditors will ask for exactly this.

Scopes

A suppression covers one scope. Pick the narrowest one that solves the problem.

Scope	API value	Covers	Example
Counterparty pair	counterparty_pair	One customer’s or account’s transactions with one specific counterparty: one rule, or every rule	A worker receives salary from the same employer twice a month
Subject + rule	subject_rule	One rule, for one customer, account or counterparty	Kumasi Central Market Traders’ Association triggers D1 Fan-in every month from member dues
Subject	subject	Every rule, for one customer, account or counterparty	A test account used by your IT team
Rule	rule	One rule, for everyone	A rule is producing nonsense while it is being recalibrated

The customer page offers the first three for a customer: pick Only with one counterparty for a counterparty pair. Rule-wide suppressions, account subjects and counterparty subjects are created through the Suppressions API.

Counterparty pairs

A counterparty pair holds back a hit only when the transaction that triggered it was with that counterparty. Everything else the customer does still alerts as usual, including the same rule firing on payments from anyone else. That makes it the narrowest, and usually the safest, suppression:

• A pair on a customer also covers hits about that customer’s accounts, just as a customer suppression does.
• A pair with no rule covers every rule for transactions with that counterparty; a pair with a rule covers that rule only.
• A pair always starts from a customer or an account. To quiet a rule that is about the counterparty itself, suppress the counterparty as the subject instead (below).

Rule-wide and subject-wide suppressions are blunt instruments

A rule suppression switches a rule off for your whole customer base; a subject suppression switches every rule off for one customer. Both are occasionally right, but they are the kind of exception examiners look at first. Keep them short — days, not months — and prefer subject + rule or counterparty pair whenever you can.

The subject must be the one the rule is about

A suppression’s subject is matched against the subject of the hit, and that depends on the rule’s entity scope (see Alerts: who an alert is about). A suppression on a customer covers hits about that customer and hits about any of the customer’s accounts, so for most purposes suppress the customer. A suppression on one account covers only that account: it never matches a hit about the customer, or about their other accounts. Hits about a counterparty, from rules such as D7, are about the outside party and are never covered by a customer’s or account’s suppression, nor by a counterparty pair. To quiet them for one counterparty, suppress that counterparty as the subject (subject_type: "counterparty"), through the API.

How to suppress an alert pattern

1. Investigate first. Close the current case with a disposition, and record the evidence that explains the activity — a payroll schedule, a letter from the association, an invoice.
2. Propose the suppression, with the narrowest scope, a clear reason that refers to the evidence, and the shortest sensible length in days. Proposing needs suppressions.create — Analysts and Senior analysts have it.
3. A second person approves it. Approving needs suppressions.approve — by default the MLRO — and cannot be done by the proposer.
4. Diary the expiry. When it runs out, alerts start again. Review the customer and, if the explanation still holds, propose a new suppression.

The clock starts at approval

A suppression runs for the number of days you asked for, counted from the moment it is approved: time spent waiting for approval doesn’t shorten it. A proposal still has to be approved within that number of days of being sent; after that it can no longer be approved, and you propose a new one.

How to propose and approve a suppression with the API

To script it, or for a scope the screen doesn’t offer, use the Suppressions API, signed in as yourself with curl (see before you start).

1. Find the IDs you need. The customer’s ID from GET /api/v1/customers?q=<their reference>; the rule’s ID from GET /api/v1/rules.

2. Propose it (the analyst):

   curl -s -b ~/.sp-cookies -H 'Content-Type: application/json' \
     -d '{"scope":"subject_rule","rule_id":"<rule id>","subject_type":"customer","subject_id":"<customer id>",
          "reason":"Monthly retailer payouts; distributor agreement and payout schedule on case SP-2026-000412","days":180}' \
     "$SP/api/v1/suppressions"

   The answer is 201 with the suppression’s id. Its state is pending.

3. Approve it (a different person, with suppressions.approve). They first read the pending list, GET /api/v1/suppressions?state=pending, then:

   curl -s -b ~/.sp-cookies -X POST "$SP/api/v1/suppressions/<id>/approve"

   The answer is 204. Its period restarts from this moment, and within about 15 seconds the evaluator starts applying it. To turn it down instead, the approver sends a reason, which the proposer will read:

   curl -s -b ~/.sp-cookies -H 'Content-Type: application/json' \
     -d '{"reason":"No payout schedule attached; attach it and propose 90 days"}' \
     "$SP/api/v1/suppressions/<id>/reject"

4. To end it early, the proposer or any approver sends POST /api/v1/suppressions/<id>/revoke, optionally with {"reason": "…"}. A proposer also uses this to withdraw a suppression that is still pending.

For a counterparty pair, add the counterparty’s ID (from the counterparties list on GET /api/v1/customers/<id>):

curl -s -b ~/.sp-cookies -H 'Content-Type: application/json' \
  -d '{"scope":"counterparty_pair","subject_type":"customer","subject_id":"<customer id>","counterparty_id":"<counterparty id>",
       "reason":"Monthly salary from employer Volta Agro Exports Ltd; employment letter KYC-2026-311","days":90}' \
  "$SP/api/v1/suppressions"

Worked example

Akosua Foods pays 60 retailers on the last working day of each month. Every month, D2 Fan-out alerts on its account.

Field	Value
Scope	Subject + rule
Subject	Akosua Foods (the customer; D2 is a customer-level rule)
Rule	D2 Fan-out
Reason	Monthly retailer payouts; distributor agreement and payout schedule on case SP-2026-000412
Days	180 (approved 30 October 2026, so it expires on 28 April 2027)
Proposed by	Efua (Analyst)
Approved by	Kofi (MLRO)

D2 still evaluates Akosua Foods’ transactions and stores the hits. Every other rule still alerts as normal — so if Akosua Foods suddenly starts receiving money from 40 unknown wallets, D1 Fan-in still fires.

The life of a suppression

State	Meaning
pending	Proposed, waiting for a second person. No effect
active	Approved and in effect
expired	Reached its end date
revoked	Approved, then ended early
rejected	Turned down by an approver before it took effect
withdrawn	Taken back by its proposer before anyone approved it

When suppressions are checked

The stream evaluator checks for a live suppression after a rule hits and before the hit is merged into an alert. A suppression applies from its start time until it expires or is revoked. The evaluator re-reads suppressions every 15 seconds, so a new, expired or revoked suppression takes effect within about 15 seconds.

Shadow hits are checked too, so the record shows which shadow hits a suppression would have covered.

Suppression or rule change?

If…	Use
One or a few known customers trip a rule for an explained reason	A suppression
A whole group of customers — all merchants, all agents — trip a rule	A rule change: a new version with a different segment or threshold. See Rules and versions.
Two parties trade with each other regularly and legitimately	A counterparty-pair suppression. See Counterparty pairs.

Related

• Suppressions API
• Alerts and cases
• Lists
• Roles and permissions