Designations API

A risk designation is a flag on a customer or counterparty, such as PEP or sanctioned, that rules read when they evaluate transactions. These endpoints add and revoke designations. To see a customer’s designations, read their profile with the Customers API.

In the app, the same is done on a customer’s page with Flag and Remove; see Flagging a customer. This page is for scripting, and for designating counterparties, which have no screen.

Before you start

Who can call them. Signed-in people only, with the designations.manage permission (by default Senior analyst and MLRO). 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
POST /api/v1/designations	Add a designation	designations.manage	201 {"id": …}
POST /api/v1/designations/{id}/revoke	Revoke one, with a reason	designations.manage	204

Add a designation

POST /api/v1/designations

Field	Required	Rules	Meaning
subject_type	Yes	customer or counterparty	What you are flagging. Accounts can’t be designated: flag their customer
subject_id	Yes	A UUID	SpeculaPro’s ID for the customer or counterparty. Find a customer’s with GET /api/v1/customers?q=…
type	Yes	pep, pep_rca, sanctioned, high_risk, adverse_media, watchlist, or custom:<key> with a lowercase key	What kind of flag. See Types
pep_class	No	domestic, foreign or international_org	Only for pep and pep_rca
reason	Yes	3 to 2,000 characters	Why, with the source you relied on. Examiners read this
valid_from	No	RFC 3339 time, now or later (up to a minute in the past is accepted, for clock differences)	When it starts applying. Leave it out to start now. It can’t be backdated: rules have already run without it
valid_to	No	RFC 3339 time, after the start	When it stops applying, for example 12 months after leaving office. Leave it out to keep it until revoked
evidence	No	An object; see below	What you relied on, for the examiner who asks later

evidence has three optional fields:

Field	Rules	Meaning
sources	Up to 10 links, each http:// or https:// with a host, up to 500 characters	The public sources: a gazette notice, an official register, a news article
reference	Up to 200 characters	The document or file reference in your own records, for example EDD-2026-014
notes	Up to 2,000 characters	Anything else worth keeping with the evidence. Returned by the API; the profile screen doesn’t show it

Evidence can’t be changed after the designation is added. It is returned as evidence on each entry of the customer’s designation_history (an empty object when none was given).

The designation applies from the moment you add it, or from valid_from if you give a later time, and its source is recorded as manual.

curl -s -b ~/.sp-cookies -H 'Content-Type: application/json' \
  -d '{
    "subject_type": "customer",
    "subject_id": "0192f3a4-5b6c-7d8e-9f01-23456789abcd",
    "type": "pep",
    "pep_class": "domestic",
    "reason": "Deputy Regional Minister since Jan 2025 (Government Gazette, 12 Jan 2025). Match confirmed on Ghana Card number.",
    "valid_to": "2029-01-31T00:00:00Z",
    "evidence": {
      "sources": ["https://www.example.gov.gh/gazette/2025/012"],
      "reference": "EDD-2026-014"
    }
  }' \
  "$SP/api/v1/designations"

{ "id": "0192f3b0-1c2d-7e3f-8a4b-5c6d7e8f9012" }

When rules see it. Rules read designations afresh for every batch of transactions, so the flag applies from the customer’s very next transaction after it starts. Earlier evaluations are not re-run.

A designation that starts later

Until its valid_from, a designation is in designation_history with active: false, and rules don’t see it; the customer isn’t listed by designated=true either. The customer’s profile marks it scheduled with its start date, and people with designations.manage can Remove it there. To cancel it with a script, revoke it as you would an active one.

To tell the states apart in designation_history: revoked_at set means removed; otherwise active: false with a valid_from in the future means scheduled, and with a valid_to in the past means ended.

No overlapping designations of the same type

A subject can’t have two designations of the same type covering the same moment. Adding a pep whose period overlaps a pep that isn’t revoked gives 409 conflict: already designated pep for part of that period. Periods that only touch are fine: one that ends on 31 January and another that starts on 31 January can both exist. Revoked and expired designations never count. To correct one, revoke it and add it again.

Two identical requests sent at the same moment, for example a double-click or a retry, create only one designation; the second gets the 409.

Revoke a designation

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

Field	Required	Rules
reason	Yes	3 to 2,000 characters

The designation is not deleted. It stays in the customer’s designation_history with revoked_at, revoked_by and revoke_reason, and stops applying to rules from the next batch.

curl -s -b ~/.sp-cookies -H 'Content-Type: application/json' \
  -d '{"reason":"Wrong match: different date of birth (1971 vs 1984) and different Ghana Card number. Reviewed by MLRO."}' \
  "$SP/api/v1/designations/0192f3b0-1c2d-7e3f-8a4b-5c6d7e8f9012/revoke"

Errors

Status	Meaning	Examples
401	Not signed in, or called with an API key	sign in required
403	Missing permission	missing permission designations.manage
404	No such customer, counterparty or designation in your workspace, or the designation is already revoked	not found
409	The subject already has a designation of the same type for part of that period	conflict: already designated pep for part of that period
422	A field fails its rules: an unknown type, a reason too short, a bad date, a start in the past or an end before the start, more than 10 evidence links or one that isn’t a web address, or pep_class sent with a type other than pep or pep_rca	Lists each problem; invalid: pep_class applies to pep and pep_rca only; invalid: valid_from can't be in the past; invalid: valid_to must be after the designation starts; invalid: evidence source "file://scan.pdf" must be an http(s) link of up to 500 characters

How to flag a PEP end to end

1. Confirm the match against the source: same name, date of birth, ID number. A wrong match is worse than none.
2. Find the customer’s ID: GET /api/v1/customers?q=<their reference>.
3. Add the designation as above, with the class and a reason that names the source.
4. Check it on the profile: GET /api/v1/customers/{id} shows it in designation_history with "active": true, and designations now includes pep.
5. Review open alerts and cases for the customer: the profile’s open_alerts and active_cases tell you whether any need a fresh look. See PEPs and high-risk customers.

Related

• Risk designations
• Customers API
• F. Customer risk and designations