Sanctions search
https://api.on8.ai/api/v1/screening/sanctionsScreen a person, company, organization or vessel name against the merged sanctions index (OFAC, UN, EU, HMT and the rest of the catalogue). Returns up to limit hits, each with the source records it was found in; a name that matches more records than that comes back cut short, and totalHits says how many there were. Read isClear for the verdict, not the length of hits: it is the field that weighs the matches, and in fuzzy mode each hit also carries its own match, score_band and match_confidence.
API key permission: portal.sanctions-search Read or higher. A lower level answers 403 API_PERMISSION_DENIED.
Body Params
querystringrequiredName of the person, company, organization or vessel.
Example: Vladimir Petrov
schemaTypestringoptionalEntity type to search. Case-sensitive: send the value exactly as listed.
Example: Person
countrystringoptionalISO 3166-1 alpha-2 country. Currently not applied: results are not filtered by country.
Example: RU
modestringoptionalMatching mode. Default exact. exact is full-text: every word of the query must appear in the record's name, aliases or notes, and hits are not scored - a common name can match many unrelated records, and one extra word such as a title can return none. fuzzy tolerates typos and transliteration and scores each hit. Case-sensitive: send the value exactly as listed.
Example: fuzzy
thresholdnumberoptionalMinimum match score, greater than 0 and at most 1 (fuzzy mode only). Default 0.7. 0 and any value outside that range are refused with 400 VALIDATION_ERROR "threshold must be greater than 0 and at most 1."; leave the field out for the default. The threshold you send is the one the screen runs at, lower or higher than your tenant's Sanctions & watchlists threshold (portal Settings, Scan Thresholds). That tenant value is used only when you send none.
Example: 0.7
limitintegeroptionalMaximum number of hits to return, between 1 and 100. Default 20.
Example: 20
Response fields
What the response carries. The example on the right shows the shape; this says what to read.
isClearbooleanThe verdict, on data rather than on a hit. false means at least one hit passed the threshold. Branch on this, not on the length of hits or on totalHits.
totalHitsintegerHow many matches the screen found, which can exceed the number returned when limit cuts the list short.
matchbooleanWhether this hit passed the threshold. Only present in fuzzy mode; exact mode does not score, so it sends no match. Every hit returned has match: true - candidates the screen rejected are removed before you see them.
score_bandstringHow strong the match is in words: strong or possible. (below_threshold is the band for a rejected candidate, which this endpoint no longer returns.)
match_confidencestringHIGH, MEDIUM or LOW in fuzzy mode; UNKNOWN in exact mode, which does not score a hit.
entity_idstringStable identifier for the matched entity. Use it to fetch the full profile or to de-duplicate hits across searches.
namestringThe entity's primary name as the source list publishes it.
entity_typestringWhat the matched entity is: person, company, organization or vessel.
scorenumberSimilarity of this hit to the query, 0 to 1. Null in exact mode, which does not score.
datasetsstring[]The index the hit was found in: ["smartsanction"], because every source list is merged into one. It does not say which list matched; read source_records for that.
risk_tagsstring[]Readable risk labels for the hit, e.g. Sanctioned Entity.
classificationobjectOur own grading of the hit. buckets names the kinds of risk found (sanctions, pep, adverse_media); detail[] carries one topic/category/severity per finding; worst_severity is the highest of them (LOW … CRITICAL) and is the single field to escalate on.
regulatoryobjectThe published designation: programs (GB-RUS, EU-RUS, US-SSI, …), regimes, measures, designation_basis, legal_references, source_urls, wind_down, secondary_sanctions, and start_date / end_date. Read the dates with care: when an entity carries several sanction records they are merged into one block, so start_date is the EARLIEST across all of them and end_date the LATEST. An end_date can therefore belong to one lapsed listing while other listings are still in force; it is not an expiry for the designation as a whole.
match_contextobjectWhy this hit matched: matched_fields and matched_names name what was compared, matched_on_name / matched_on_address / matched_on_content say where the match came from, coverage how much of the query was covered, and snippets show the matched text.
positionsstring[]Public offices or roles recorded for a person.
descriptionsstring[]Free-text notes the source lists publish about the entity.
countriesstring[]Countries linked to the entity (nationality, registration, address), as ISO 3166-1 alpha-2 codes.
birth_datestring[]Recorded dates of birth. A list, not a single value: sources disagree, and every recorded spelling is kept.
death_datestring[]Recorded dates of death, when a source publishes one.
first_seenstringWhen our index first carried this entity. An INDEX date, not the designation date - a 2018 listing picked up later carries the later date.
last_seenstringWhen our index last confirmed the entity was still published by a source.
source_recordsstring[]The source-list records behind the hit, by record id (gb-hmt-17169, eu-sancmap-..., ca-sema-...); the prefix names the list. This is where to read which lists matched, and what to cite in a filed report.