Decisions made through the API carry a name

When your CRM or case management tool closes an alert through the Smart Oversight API, the call is authenticated with an API key. The key proves that the call is authorised. It does not say who, in your firm, reviewed the hit and made the decision.

Yet that is what an auditor or your supervisory authority will ask. Every call to the API can now name the team member it is made for, and the decision is recorded in that person’s name.

Naming the team member

The team member is named in an optional request header, a piece of technical information sent with the call. Your tool puts either their member identifier, usr_…, or email: followed by their email address. An address on its own, without the prefix, is refused. Every operation in the API accepts this header.

The API looks for the person among the members of your workspace, guests included. If no active member matches, it returns 400 actor_unknown. A malformed value returns 400 resource_id_invalid.

The decision is then recorded with the team member as its author and the key as the intermediary acting on their behalf, following the delegation model described in RFC 8693. The alert’s status history points to their user account, just as if they had reviewed the alert in the app.

The team member’s role counts too

A validation always requires the key to have the alerts:validate scope. When it is made in a team member’s name, the API also checks their role. The validation is recorded only if they are your MLRO (Money Laundering Reporting Officer) in this workspace. If you name, say, a compliance officer who is not the MLRO, the API replies 403 actor_not_permitted.

Without this check, the audit trail could attribute a validation to someone who had no right to give it. So the API refuses the call.

Roles are held per workspace. The same person can be MLRO in one workspace and compliance officer in another, and it is their role in the key’s workspace that is checked.

Finding team members with GET /v2/users

GET /v2/users lists the active members of the workspace, with their identifier, email address, full name and roles. The call needs the users:read scope. Your tool uses it to match its own users to their Smart Oversight accounts, and to see which of them can validate.

GET /v2/users

{
  "object": "list",
  "data": [
    {
      "object": "user",
      "id": "usr_66f1a2b3c4d5e6f708191b2c",
      "email": "<address>",
      "full_name": "John Doe",
      "roles": ["MLRO"]
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Recording a decision

Decisions go through POST /v2/alerts/{id}/review, which needs the alerts:write scope. The status field is OPEN, DONE or VALIDATED. The resolution field takes one of UNRESOLVED, NOT_RELATED_TO_CLIENT, TRUE_RELEVANT or TRUE_NOT_RELEVANT.

You can add a comment, which is appended to the existing one and never replaces it. You can also ask for actions (MARK_AS_PEP, REPORT_INTERNATIONAL_SANCTION or REPORT_ADMINISTRATIVE_SANCTION), which set the matching flag on every client linked to the alert.

In the example below, the MLRO confirms that a PEP list hit does concern the client, and marks the client as a PEP.

# Add the header naming the team member (see the documentation).
curl -X POST "$API_BASE/v2/alerts/alr_66f1a2b3c4d5e6f708194000/review" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "VALIDATED",
    "resolution": "TRUE_RELEVANT",
    "comment": "Match confirmed against the passport copy on file.",
    "actions": ["MARK_AS_PEP"]
  }'

When several screenings have found the same hit, it is stored once for each of them. The decision applies to all of these copies, as it does in the app.

To find alerts to review, GET /v2/alerts filters by status and by source (sanctions lists, PEP lists or internet screening). GET /v2/clients/{ref}/alerts returns one client’s alerts, using either its cli_… identifier or your own ext:… reference.

One history for each alert

A named decision appears in the alert’s history, attributed to the team member, in the same form as decisions made in the app. An auditor therefore reads a single history for each alert, whichever tool was used for the review.

Decisions without a name

If the header is missing, the decision is recorded against the API key. The key’s identifier is still a trace, but it does not identify a person. The response flags this with a warning header.

The API then has no role to check, and only the key’s scopes apply. We advise naming the team member on every decision.

Further reading

This article follows the introduction to the Smart Oversight API and webhooks for screenings and alerts. The integrations page lists what the API covers, and Connect KYC & AML screening to your CRM walks through a complete integration, from creating a client to reviewing an alert.