Introducing the Smart Oversight API

Version 2 of the Smart Oversight API is now open. An API lets two pieces of software exchange data directly, without anyone copying it across. Your CRM, onboarding portal or back office can now create clients in Smart Oversight, screen them against sanctions lists, PEP lists and negative media, and read the alerts that come out.

Your compliance officer carries on reviewing those alerts in Smart Oversight.

Each client entered once

Many fiduciaries, accounting firms and law firms keep their client records in another tool: a CRM, an onboarding portal, a practice management system or an in-house back office. Each new client is recorded there, then typed into Smart Oversight a second time.

With the API, your own system creates the client and starts the screening at the moment it records the client.

What the API does

It handles clients, both individuals and companies, with their identity, address, contact details, tax details and risk level. Your system can create, update and archive them. Archiving deactivates a client without deleting it.

On the screening side, a client can be checked against sanctions lists (UN, EU, OFAC SDN and non-SDN, United Kingdom, Swiss SECO), against PEP lists and through an internet search that covers negative media. Each source has its own status.

Alerts are available too. Your system can list and filter them, read the details of each match and record a decision with a comment. Validating an alert needs a separate permission, which you keep for the keys that need it.

Access keys

Software identifies itself to the API with a key, which works as its password. Keys are created by a company administrator in the Smart Oversight app. Each one gets only the permissions (scopes) it needs from clients, screenings, alerts, alert validation and webhooks. A key that only sends new clients from the CRM gets the clients scope and nothing else. If a call goes beyond what its key allows, the API refuses it and says which scope is missing.

A key can have an expiry date, and the administrator can revoke it at any time. To replace a key, the administrator issues a new one and chooses how long the old one stays valid, which gives your IT team time to install the new one.

Smart Oversight keeps only a hashed version of each key. The full key is shown once, when it is created.

Keys are meant for server-to-server calls. Each request carries the key in its authorisation header, never in the URL, and the API refuses calls made from a page open in a web browser. The key therefore stays on your server.

Your own client reference

Every client in your CRM already has an identifier. Your system sends it to Smart Oversight as the client’s external reference, then uses it, with the prefix ext:, whenever it refers to that client. It has no need to keep Smart Oversight’s own identifiers.

The same call creates or replaces a client from this reference. The call below creates the company if reference CRM-88213 does not yet exist in your workspace, and replaces its data if it does. Data travels as JSON, a text format that software reads easily.

PUT /v2/clients/ext:CRM-88213
{
  "kind": "LEGAL",
  "name": "Northwind Holdings SA",
  "organization": {
    "country_of_incorporation": "LU",
    "register_number": "B123456"
  },
  "risk": "MEDIUM"
}

To bring in an existing portfolio, POST /v2/clients/batch accepts up to 100 clients per call. Each client is processed on its own. An error is reported with the client’s position in the list and does not stop the others from being processed.

Starting a screening

A screening request names the client and the sources to check.

POST /v2/screenings
{
  "client": "ext:CRM-88213",
  "media": ["SANCTIONS_LIST", "PEP_LIST", "INTERNET_SCREENING"]
}

The API replies with the screening’s identifier, an overall status and a status for each source. Your system can then call GET /v2/screenings/<id> whenever it likes. The completion date stays empty until every source has finished.

Because each screening is billable, the request must also carry a unique request reference, which your system generates and sends in a header. Any matches then become alerts in Smart Oversight, where your compliance officer reviews them.

Regions

Each workspace belongs to one region: Luxembourg, Switzerland or another European Union country. Your system calls the API in that region, and client data stays there, in Tier III+ data centres in Luxembourg, Switzerland and France.

Technical details

Requests and responses are in JSON, under the /v2 prefix. Long lists come back page by page. Each page includes has_more and next_cursor, and your system passes the cursor back to fetch the next one. A page holds 20 items by default and 100 at most.

Each key can send up to 600 requests per minute. Above that, the API returns status 429 and says when to try again.

Errors all share one format. They give a type (invalid request, missing or insufficient key, rate limit, error on our side), a machine-readable code, a message a person can read, the field concerned if there is one, and a request identifier to quote to our support team.

The reference documentation is generated from the API’s own code. It therefore describes what the API actually does, and we provide it to your team.

The API can also notify your systems when a screening finishes or a client changes. Notifications are covered in a separate article.

Getting started

The Integrations page summarises what the API covers. To connect a CRM, read Connect KYC & AML screening to your CRM. And to talk about your project, contact our team.