Suppressions API

A suppression stops one explained pattern from raising alerts for a limited time. It needs two people: one proposes it, a different person approves it, and until then it does nothing. Suppressed hits are still recorded; they just don’t become alerts.

In the app, suppressions are proposed from a customer’s page (Suppress alerts) and approved under Suppressions to approve on the Rules page; see Suppressing alerts. This page is for scripting, and for scopes the screen doesn’t offer, such as an account or counterparty subject or a rule-wide suppression. The screen proposes customer suppressions, optionally limited to one counterparty, which also cover the customer’s accounts.

Before you start

Who can call them. Signed-in people only; an API key gets 401 sign in required. 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/suppressions	List suppressions	alerts.view	200
POST /api/v1/suppressions	Propose one	suppressions.create	201 {"id": …}
POST /api/v1/suppressions/{id}/approve	Approve someone else’s	suppressions.approve	204
POST /api/v1/suppressions/{id}/reject	Turn down someone else’s, with a reason	suppressions.approve	204
POST /api/v1/suppressions/{id}/revoke	End one early, or withdraw your own pending one	Pending: the proposer only. Active: the proposer or suppressions.approve	204

With the default roles, Analysts and Senior analysts propose, and the MLRO approves.

The suppression object

Field	Meaning
id	Its ID
scope	rule, subject, subject_rule or counterparty_pair (see below)
rule_id, rule_name	The rule it covers, for rule and subject_rule, and for a counterparty_pair limited to one rule
subject_type, subject_id, subject_name	The customer, account or counterparty it covers, for every scope except rule. The name is the customer’s name, the account’s masked identifier, or the counterparty’s name or masked identifier. The name is left out if your role lacks entities.view
counterparty_id, counterparty_name	For counterparty_pair: the other party. The name is left out if your role lacks entities.view
reason	Why it exists. If your role lacks entities.view, it reads (hidden: needs permission to view customers)
starts_at, expires_at	Its life. While pending: from the proposal to that plus the days asked for. On approval both are reset: starts_at becomes the moment of approval and expires_at that plus the same length, so waiting for approval doesn’t shorten it
created_by, created_by_id	Who proposed it (display name and user ID)
approved_by	Who approved it, once approved
revoked_at, revoked_by	When it was rejected, withdrawn or ended early, and by whom (display name)
revoke_reason	Why it was rejected, withdrawn or ended early. Always present for a rejection; optional otherwise. Left out if your role lacks entities.view
created_at	When it was proposed
state	See below

state	Meaning
pending	Proposed, waiting for approval. No effect
active	Approved and in effect
expired	Reached expires_at
revoked	Approved, then ended early
rejected	Ended before approval by someone other than the proposer
withdrawn	Ended before approval by the proposer

List suppressions

GET /api/v1/suppressions

Query parameter	Meaning
state	pending (waiting for approval and not yet expired), active (approved and running), or all (default: every state)

Newest first, at most 200.

The list needs only alerts.view, which some roles hold without being allowed to see customers (for example the default Rule approver). For them, names and explanations are hidden as described above; the rule, dates and state are still shown.

# What is waiting for a second approver?
curl -s -b ~/.sp-cookies "$SP/api/v1/suppressions?state=pending"

Propose a suppression

POST /api/v1/suppressions

Field	Required	Rules	Meaning
scope	Yes	rule, subject, subject_rule, counterparty_pair	What it covers
rule_id	For rule and subject_rule; optional for counterparty_pair	A rule’s ID, from GET /api/v1/rules	The rule to silence
subject_type	For every scope except rule	customer, account or counterparty (counterparty_pair takes customer or account only)	What kind of subject
subject_id	With subject_type	A UUID	The customer, account or counterparty
counterparty_id	For counterparty_pair only	A counterparty’s ID, for example from the counterparties list on GET /api/v1/customers/{id}	The other party whose transactions are expected
reason	Yes	10 to 2,000 characters	The business explanation an examiner will read
days	Yes	1 to 365	How long it lasts. Suppressions always expire

Send exactly the fields the scope needs:

Scope	Covers	Send
counterparty_pair	A customer’s or account’s transactions with one counterparty, for one rule or every rule. The narrowest	subject_type, subject_id, counterparty_id, and optionally rule_id
subject_rule	One rule for one customer, account or counterparty	rule_id, subject_type, subject_id
subject	Every rule for one customer, account or counterparty	subject_type, subject_id
rule	One rule for everyone	rule_id

A counterparty_pair holds back a hit only when the transaction that triggered it was with that counterparty. A pair on a customer also covers the customer’s accounts.

curl -s -b ~/.sp-cookies -H 'Content-Type: application/json' \
  -d '{
    "scope": "subject_rule",
    "rule_id": "0192f3c1-aaaa-7bbb-8ccc-0123456789ab",
    "subject_type": "customer",
    "subject_id": "0192f3a4-5b6c-7d8e-9f01-23456789abcd",
    "reason": "Monthly retailer payouts; distributor agreement and payout schedule on case SP-2026-000412",
    "days": 180
  }' \
  "$SP/api/v1/suppressions"

Salary from one employer, for every rule, for 90 days:

curl -s -b ~/.sp-cookies -H 'Content-Type: application/json' \
  -d '{
    "scope": "counterparty_pair",
    "subject_type": "customer",
    "subject_id": "0192f3a4-5b6c-7d8e-9f01-23456789abcd",
    "counterparty_id": "0192f3b7-1111-7222-8333-444455556666",
    "reason": "Monthly salary from employer Volta Agro Exports Ltd; employment letter on file, ref KYC-2026-311",
    "days": 90
  }' \
  "$SP/api/v1/suppressions"

Match the subject to the rule

A suppression’s subject is matched against the subject of the hit. A customer suppression covers hits about that customer and hits about any of the customer’s accounts. An account suppression covers only that account. Hits about a counterparty (rules whose entity scope is counterparty) are never covered by a customer’s or account’s suppression, nor by a counterparty_pair; suppress the counterparty itself as the subject. See The subject must be the one the rule is about.

Approve a suppression

POST /api/v1/suppressions/{id}/approve

No body. Only a pending suppression can be approved, and not by the person who proposed it. Its period restarts from the moment of approval (see starts_at above). The evaluator starts applying it within about 15 seconds.

curl -s -b ~/.sp-cookies -X POST "$SP/api/v1/suppressions/0192f3d2-0000-7000-8000-000000000001/approve"

Reject a suppression

POST /api/v1/suppressions/{id}/reject

Field	Required	Rules	Meaning
reason	Yes	3 to 2,000 characters	Why it is turned down. The proposer sees it on the customer’s page

Only a pending suppression can be rejected, and not by the person who proposed it: they withdraw it with revoke instead. Its state becomes rejected.

curl -s -b ~/.sp-cookies -H 'Content-Type: application/json' \
  -d '{"reason":"No payout schedule attached; attach it and propose 90 days, not 365"}' \
  "$SP/api/v1/suppressions/0192f3d2-0000-7000-8000-000000000001/reject"

Revoke a suppression

POST /api/v1/suppressions/{id}/revoke

Field	Required	Rules	Meaning
reason	No	Up to 2,000 characters	Why. Kept in revoke_reason and the audit log

The body is optional. Ends an active suppression early (state revoked), or withdraws a pending one (state withdrawn). Only the proposer can withdraw a pending suppression; anyone else gets 403 and must reject it with a reason. An active suppression can be ended by its proposer or by anyone with suppressions.approve. Alerts start again within about 15 seconds.

curl -s -b ~/.sp-cookies -H 'Content-Type: application/json' \
  -d '{"reason":"Payroll arrangement ended in September"}' \
  "$SP/api/v1/suppressions/0192f3d2-0000-7000-8000-000000000001/revoke"

Turning down someone else’s proposal

An approver who calls revoke on someone else’s pending proposal also marks it rejected, but without requiring a reason. Use reject so the proposer always learns why.

Errors

Status	Meaning	Examples
401	Not signed in, or called with an API key	sign in required
403	Missing permission, approving or rejecting your own, withdrawing someone else’s pending proposal, or ending someone else’s without suppressions.approve	forbidden: someone other than the proposer must approve; forbidden: withdraw your own proposal instead of rejecting it; forbidden: only the proposer can withdraw a pending suppression; reject it with a reason instead; forbidden: only the proposer or an approver can end a suppression
404	No such suppression, rule, customer, account or counterparty in your workspace, or (for revoke) the suppression has already been rejected, withdrawn or revoked	not found
409	The suppression isn’t pending (or has passed its end date while pending)	conflict: only pending suppressions can be approved; conflict: only pending suppressions can be rejected
422	A field fails its rules: reason too short, days out of range, unknown scope, or the fields don’t fit the scope	Lists each problem; invalid: scope subject_rule needs rule_id, subject_type and subject_id; invalid: counterparty_pair pairs a customer or account with a counterparty; invalid: give a reason for the rejection

How to suppress an explained pattern end to end

1. Investigate and close the case first, recording the evidence that explains the activity.
2. Find the IDs: the customer from GET /api/v1/customers?q=…, the rule from GET /api/v1/rules.
3. Propose with the narrowest scope and the shortest sensible days.
4. Ask your approver to review GET /api/v1/suppressions?state=pending and approve it. Its period starts when it is approved. If they reject it, read revoke_reason, fix the proposal and send a new one.
5. Diary the expiry (expires_at). When it ends, alerts start again; review the customer and propose a new one if the explanation still holds.

Related

• Suppressions
• Customers API
• Lists API
• Choosing a disposition