{ "openapi": "3.1.0", "info": { "title": "Export Controls Screening API", "version": "1.0.0", "description": "Screen a buyer, consignee, end user or supplier against six US export-control lists and the four sanctions\nlists of our Sanctions Screening API, in one call:\n\n- US Entity List, Denied Persons List, Unverified List and Military End User List (Bureau of Industry and\n Security)\n- US ITAR Debarred List and Nonproliferation Sanctions (State Department)\n- UK Sanctions List (FCDO), UN Security Council consolidated list, EU consolidated financial sanctions list and\n the US OFAC SDN and non-SDN lists\n\nThe US lists come from the official Consolidated Screening List file and the sanctions lists from their\npublishers, refreshed daily at 04:00 UTC.\n\nEvery result names each list it checked with two dates: `listUpdated`, when the publisher last changed the list\n(these lists change unevenly, some only a few times a year), and `weCheckedOn`, when we last fetched it. Any of\nthe ten lists the check could not cover is named in `listsNotScreened`, so a result never reads as a check of all\nten when it covered fewer. Each result carries a `checkId`, the time it ran and the inputs it used, so you can keep\nit as a dated record of the check. We keep no copy of the names you screen.\n\nEach result is a screening record, not a licensing decision. Whether you need a licence depends on the goods, the\ndestination and the end use.\n\nFor a UK company, `GET /ownership/{companyNumber}` also screens everyone recorded in its ownership at Companies\nHouse and reads the result against the US rule on companies 50% or more owned by Entity List or Military End User\nList parties.\n\nUsage: one name screened is one check; a bulk request counts one check per name; an ownership check is one check. `GET /lists`, `GET /changes`\nand the watchlist routes do not count. Each screening response carries `X-Checks-Used`, `X-Checks-Included` and\n`X-Checks-Limit` headers for the current calendar month (UTC). Past your plan's allowance, extra checks are billed\nat your plan's per-check rate; at twice the allowance (or at the allowance during the free trial) screening pauses\nwith a 429 until the 1st of the next month.\n\nIf a screen fails (429, 5xx, a timeout), treat the name as not yet screened: retry, and do not treat it as clear.\n", "contact": { "name": "Stratum APIs", "url": "https://stratumapis.com", "email": "support@stratumapis.com" }, "termsOfService": "https://stratumapis.com/legal/terms", "x-logo": { "url": "https://stratumapis.com/icon.svg", "altText": "Stratum APIs" } }, "servers": [ { "url": "https://api.stratumapis.com/v1/export-screening", "description": "Production" } ], "security": [ { "apiKey": [] } ], "paths": { "/screen": { "get": { "summary": "Screen one name against the six US export-control lists and the four sanctions lists", "operationId": "screen", "parameters": [ { "in": "query", "name": "name", "required": true, "example": "Niki Kyriakou", "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Person or organisation name to screen" }, { "in": "query", "name": "country", "required": false, "example": "GB", "schema": { "type": "string" }, "description": "The party's country as a two-letter ISO 3166 code. Compared with the countries of a listing's addresses and reported as `countryMatch` on export-list matches. It never hides a match." }, { "in": "query", "name": "type", "required": false, "example": "entity", "schema": { "type": "string", "enum": [ "person", "entity", "any" ], "default": "any" }, "description": "On the sanctions lists, match person listings only, organisation listings only (`entity`; `organisation` and `company` also accepted), or both. The US export lists do not mark people and organisations apart, so every export listing is screened whatever the type." }, { "in": "query", "name": "minScore", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.7 }, "description": "Candidates scoring below this are left out" }, { "in": "query", "name": "reference", "required": false, "example": "order-4471", "schema": { "type": "string", "maxLength": 100 }, "description": "Your own reference (for example an order number). Echoed back in the result, never stored." } ], "responses": { "200": { "description": "Screening result. `result` is `no_match` when nothing matched at the threshold on any list screened.", "headers": { "X-Checks-Used": { "$ref": "#/components/headers/ChecksUsed" }, "X-Checks-Included": { "$ref": "#/components/headers/ChecksIncluded" }, "X-Checks-Limit": { "$ref": "#/components/headers/ChecksLimit" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreeningResult" }, "examples": { "entityListMatch": { "summary": "A possible match on the US Entity List, with a London address", "value": { "checkId": "chk_0143e5d0-1c6c-427a-a96b-91a08634185b", "screenedAt": "2026-10-10T09:12:44.512Z", "reference": "order-4471", "query": "Niki Kyriakou", "result": "possible_match", "count": 1, "matches": [ { "list": "us_el", "listLabel": "US Entity List (BIS)", "name": "Niki Panteli Kyriakou", "score": 0.951, "addresses": [ { "text": "91, Evgeniou Voulgareous, 4153", "city": "Limassol", "country": "CY" }, { "text": "38, Princes Court-88 Brompton Road Knightsbridge, SW3 1ES", "city": "London", "country": "GB" } ], "countries": [ "CY", "GB" ], "countryMatch": "match", "listedOn": "2011-08-15", "federalRegister": "76 FR 50407 (8/15/2011)", "licenceRequirement": "For all items subject to the EAR (See §744.11 of the EAR)", "licencePolicy": "Presumption of denial", "listingId": "828daede017810c4fdcaa56f51cf07cb91ed16bdd05faff93d169b9f", "sourceUrl": "https://www.bis.gov/regulations/ear/744#supplement-4-744", "moreInfoUrl": "https://www.bis.gov/licensing/guidance-on-end-user-and-end-use-controls-and-us-person-controls" } ], "screenedWith": { "type": "any", "minScore": 0.7, "country": "GB" }, "listsScreened": [ { "list": "ofsi", "name": "UK Sanctions List (FCDO)", "listUpdated": "2026-10-10", "weCheckedOn": "2026-10-10" }, { "list": "un", "name": "UN Security Council Consolidated Sanctions List", "listUpdated": "2026-10-10", "weCheckedOn": "2026-10-10" }, { "list": "eu", "name": "EU Consolidated Financial Sanctions List", "listUpdated": "2026-10-10", "weCheckedOn": "2026-10-10" }, { "list": "ofac", "name": "US OFAC Sanctions Lists (SDN and non-SDN)", "listUpdated": "2026-10-10", "weCheckedOn": "2026-10-10" }, { "list": "us_el", "name": "US Entity List (BIS)", "listUpdated": "2026-08-21", "weCheckedOn": "2026-10-10" }, { "list": "us_dpl", "name": "US Denied Persons List (BIS)", "listUpdated": "2026-04-28", "weCheckedOn": "2026-10-10" }, { "list": "us_dtc", "name": "US ITAR Debarred List (State Department)", "listUpdated": "2026-07-24", "weCheckedOn": "2026-10-10" }, { "list": "us_uvl", "name": "US Unverified List (BIS)", "listUpdated": "2026-02-10", "weCheckedOn": "2026-10-10" }, { "list": "us_isn", "name": "US Nonproliferation Sanctions (State Department)", "listUpdated": "2026-10-02", "weCheckedOn": "2026-10-10" }, { "list": "us_meu", "name": "US Military End User List (BIS)", "listUpdated": "2026-02-20", "weCheckedOn": "2026-10-10" } ], "listsNotScreened": [], "notice": "This is a screening record, not a licensing decision. Whether you need a licence depends on the goods, the destination and the end use." } }, "noMatch": { "summary": "No match, with one list not loaded at the last refresh", "value": { "checkId": "chk_7d0e2f61-0a7b-4c55-9e0f-3b2b8a7c1e44", "screenedAt": "2026-10-10T09:14:02.118Z", "query": "Harbour Freight Ltd", "result": "no_match", "count": 0, "matches": [], "screenedWith": { "type": "entity", "minScore": 0.7 }, "listsScreened": [ { "list": "ofsi", "name": "UK Sanctions List (FCDO)", "listUpdated": "2026-10-10", "weCheckedOn": "2026-10-10" }, { "list": "us_el", "name": "US Entity List (BIS)", "listUpdated": "2026-08-21", "weCheckedOn": "2026-10-10" } ], "listsNotScreened": [ { "list": "us_meu", "name": "US Military End User List (BIS)", "why": "Could not be loaded at our last refresh, so this check did not cover it." } ], "notice": "This is a screening record, not a licensing decision. Whether you need a licence depends on the goods, the destination and the end use." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/LimitReached" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/bulk": { "post": { "summary": "Screen up to 100 names in one request (one check per name)", "description": "Each name can be a plain string, or an object with its own `country`, `type`, `minScore` and `reference`.\nTop-level `type` and `minScore` are defaults for names that don't set their own; `country` goes on each name.\nIf the request would take you past your monthly limit it is refused whole (429), with how many checks remain.\nA request answers within about 20 seconds: if names are left when time runs out, the response has\n`incomplete: true` and lists them in `notScreened`; send those again. Only screened names are charged.\n", "operationId": "screenBulk", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "names" ], "properties": { "names": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "$ref": "#/components/schemas/BulkName" } ] } }, "type": { "type": "string", "enum": [ "person", "entity", "any" ], "default": "any" }, "minScore": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.7 } } }, "example": { "names": [ { "name": "Harbour Freight Ltd", "country": "GB", "type": "organisation", "reference": "consignee-18" }, { "name": "Niki Kyriakou", "country": "CY", "reference": "end-user-18" } ] } } } }, "responses": { "200": { "description": "One screening result per name, in request order, each with its own `checkId`", "headers": { "X-Checks-Used": { "$ref": "#/components/headers/ChecksUsed" }, "X-Checks-Included": { "$ref": "#/components/headers/ChecksIncluded" }, "X-Checks-Limit": { "$ref": "#/components/headers/ChecksLimit" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "description": "Names screened in this response" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ScreeningResult" } }, "incomplete": { "type": "boolean", "description": "Present and true when time ran out before every name was screened" }, "notScreened": { "type": "array", "description": "The names not screened yet (with their position in the request); send them again", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "name": { "type": "string" } } } }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/LimitReached" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/lists": { "get": { "summary": "The ten lists, their size and both dates (free)", "operationId": "listsMetadata", "responses": { "200": { "description": "The lists loaded now, and any that are not", "content": { "application/json": { "schema": { "type": "object", "properties": { "lists": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/ListScreened" }, { "type": "object", "properties": { "url": { "type": "string", "description": "The list's home page" }, "entryCount": { "type": "integer" } } } ] } }, "listsNotLoaded": { "type": "array", "items": { "$ref": "#/components/schemas/ListNotScreened" } }, "exportFileDate": { "type": "string", "description": "When trade.gov built the Consolidated Screening List file we read" } } }, "example": { "lists": [ { "list": "us_el", "name": "US Entity List (BIS)", "url": "https://www.bis.gov/regulations/ear/744#supplement-4-744", "entryCount": 3419, "listUpdated": "2026-08-21", "weCheckedOn": "2026-10-10" } ], "listsNotLoaded": [], "exportFileDate": "2026-10-09T23:15:00.025206+00:00" } } } }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/changes": { "get": { "summary": "Each day's additions, removals and amended listings on the six US export lists (free)", "description": "What changed on each US export-control list, day by day, from the daily 04:00 UTC refresh. A listing whose reference changed but which is otherwise the same counts once, as amended; a step too large to be one day of listings (a change of source or file format) is withheld with its counts. Days with no change are left out. Free: does not count as a check.", "operationId": "listChanges", "parameters": [ { "in": "query", "name": "days", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 120, "default": 30 }, "description": "How many days back from the last refresh" }, { "in": "query", "name": "list", "required": false, "example": "us_el,us_meu", "schema": { "type": "string" }, "description": "Comma-separated list slugs (us_el, us_dpl, us_dtc, us_uvl, us_isn, us_meu); every list when left out" } ], "responses": { "200": { "description": "The change history", "content": { "application/json": { "schema": { "type": "object", "properties": { "updatedAt": { "type": "string", "format": "date-time", "description": "When the last refresh was compared" }, "from": { "type": "string", "format": "date", "description": "First day covered" }, "lists": { "type": "array", "items": { "type": "object", "properties": { "slug": { "$ref": "#/components/schemas/ExportListSlug" }, "name": { "type": "string" }, "url": { "type": "string" }, "entryCount": { "type": "integer" }, "lastRefreshed": { "type": "string", "format": "date-time", "description": "When we last fetched the list" }, "lastChanged": { "type": "string", "format": "date", "description": "Last day with a change on this list", "if any": null } } } }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "lists": { "type": "object", "description": "Keyed by list slug; only lists that changed that day", "additionalProperties": { "type": "object", "properties": { "added": { "type": "array", "items": { "$ref": "#/components/schemas/ListChangeItem" } }, "removed": { "type": "array", "items": { "$ref": "#/components/schemas/ListChangeItem" } }, "amended": { "type": "array", "items": { "$ref": "#/components/schemas/ListChangeItem" } }, "withheld": { "type": "object", "properties": { "added": { "type": "integer" }, "removed": { "type": "integer" }, "reason": { "type": "string" } } } } } } } } } } } } } }, "400": { "description": "Bad days or list value (`invalid_days`, `invalid_list`)" }, "503": { "description": "The change history starts with the next daily refresh (`changes_not_ready`)" } } } }, "/ownership/{companyNumber}": { "get": { "summary": "Screen a UK company and everyone recorded in its ownership at Companies House (one check)", "description": "Screens the company by its registered name, then every owner and controller recorded at Companies House\n(people, UK companies, and foreign companies by name, walking up through UK holding companies up to five\nlevels) against the same ten lists, and reads the result against the US rule that extends Entity List and\nMilitary End User List restrictions to companies those parties own 50% or more of, directly or indirectly,\nindividually or together.\n\nCompanies House records holdings as bands, not exact figures, so the result says what the bands allow. More than\n75% of the shares, or more than 50% but not more than 75%, is read as owning 50% or more. More than 25% but not\nmore than 50% could be exactly 50%, so it is a possible 50% owner, never a certain one. Voting rights, the right to appoint\ndirectors or significant influence, with no share band, means the holder controls the company but owns 25% of\nthe shares or less.\n\nOwnership is followed as a chain: a company 50% or more owned by a listed party is itself covered, and so is a\ncompany it owns 50% or more of. `ownership.level` is one of `listed_owner_50_percent`,\n`listed_owners_may_reach_50_percent`, `listed_party_in_ownership` (any list, any holding, including control)\nor `nothing_found`. The 50% levels need a strong name match (0.85 or more); weaker possible matches are still\nlisted per owner. Every match is a possible match by name, to be checked.\n\nThis covers ownership recorded at Companies House only: owners above a foreign company are not recorded there,\nand `ownership.limits` names each place the check could not see past. It is not a determination under the US\nrule.\n\nCounts as one check, only when the ownership was read: an unknown company (404) or a Companies House failure\n(503) is not charged and never reads as \"nothing found\".\n", "operationId": "ownership", "parameters": [ { "in": "path", "name": "companyNumber", "required": true, "example": "08991238", "schema": { "type": "string" }, "description": "As Companies House shows it, for example 01234567 or SC123456. A shorter all-digit number is padded with leading zeros." } ], "responses": { "200": { "description": "The company's screen (the same shape as `/screen`) with its ownership", "headers": { "X-Checks-Used": { "$ref": "#/components/headers/ChecksUsed" }, "X-Checks-Included": { "$ref": "#/components/headers/ChecksIncluded" }, "X-Checks-Limit": { "$ref": "#/components/headers/ChecksLimit" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ScreeningResult" }, { "type": "object", "required": [ "companyNumber", "ownership" ], "properties": { "companyNumber": { "type": "string" }, "result": { "type": "string", "enum": [ "no_match", "possible_match" ], "description": "possible_match when the company or anyone in its ownership is a possible match" }, "ownership": { "$ref": "#/components/schemas/Ownership" } } } ] }, "example": { "checkId": "chk_5b3c0c7e-2f61-4c1e-9a54-0d2f8a6b1e90", "screenedAt": "2026-10-10T21:03:48.402Z", "companyNumber": "08991238", "query": "HIKVISION UK LIMITED", "result": "possible_match", "count": 0, "matches": [], "screenedWith": { "type": "entity", "minScore": 0.7 }, "listsScreened": [ { "list": "us_el", "name": "US Entity List (BIS)", "listUpdated": "2026-08-21", "weCheckedOn": "2026-10-10" } ], "listsNotScreened": [], "ownership": { "level": "listed_party_in_ownership", "message": "Hangzhou Hikvision Digital Technology Corporation Limited, recorded as controlling this company, is a possible match for a party on the US OFAC Sanctions Lists (SDN and non-SDN) and the US Entity List (BIS). Check the match.", "owners": [ { "name": "Coöperatief Hikvision Europe U.A.", "kind": "corporate", "companyNumber": null, "through": [], "band": "fifty_plus", "reach": "fifty_plus", "holding": "owns 50% or more", "matches": [] }, { "name": "Hangzhou Hikvision Digital Technology Corporation Limited", "kind": "corporate", "companyNumber": null, "through": [], "band": "control", "reach": "control", "holding": "controls the company (no shareholding over 25% recorded)", "matches": [ { "list": "ofac", "listLabel": "US OFAC Sanctions Lists (SDN and non-SDN)", "name": "HANGZHOU HIKVISION DIGITAL TECHNOLOGY CO.", "LTD.": null, "score": 1 }, { "list": "us_el", "listLabel": "US Entity List (BIS)", "name": "Hangzhou Hikvision Digital Technology Co.", "Ltd.": null, "score": 1 } ] } ], "limits": [ "Coöperatief Hikvision Europe U.A. (registered in Netherlands): its own owners are not recorded at Companies House.", "Hangzhou Hikvision Digital Technology Corporation Limited (registered in Zhejiang, China): its own owners are not recorded at Companies House." ], "companiesHouseNote": "This covers ownership recorded at Companies House only. Owners above a foreign company are not recorded there.", "ownershipReadAt": "2026-10-10T21:03:47.143Z" }, "notice": "This is a screening record, not a licensing decision. Whether you need a licence depends on the goods, the destination and the end use." } } } }, "400": { "description": "Not a UK company number (`invalid_company_number`)" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Companies House has no company with that number (`company_not_found`). Not charged." }, "429": { "$ref": "#/components/responses/LimitReached" }, "503": { "description": "The ownership could not be read from Companies House (`ownership_not_checked`), or the export lists are unavailable (`export_lists_unavailable`). Nothing was checked or charged; treat the company as not yet checked, never as clear." } } } }, "/monitored": { "post": { "summary": "Add a buyer, consignee or supplier to your export watchlist (free)", "description": "Watchlist entries are re-screened against the ten lists every day at 05:00 UTC. A listing that newly matches\nappears in `GET /monitored/changes` with its details, and we email an alert. This watchlist is separate from a\nSanctions Screening watchlist: each lists, counts and alerts only its own entries.\nWatchlist size: Starter 250, Growth 1,000, Pro 5,000.\n", "operationId": "addMonitored", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entityName", "entityType" ], "properties": { "entityName": { "type": "string", "maxLength": 200 }, "entityType": { "type": "string", "enum": [ "individual", "company" ] }, "country": { "type": "string", "example": "GB", "description": "The party's country as a two-letter ISO 3166 code. Optional; reported against the export lists' addresses." }, "customerEmail": { "type": "string", "description": "Where alerts for this entry go. Defaults to the email you subscribed with." } } } } } }, "responses": { "201": { "description": "Added", "content": { "application/json": { "schema": { "type": "object", "properties": { "entityId": { "type": "string" }, "entityName": { "type": "string" }, "entityType": { "type": "string", "enum": [ "individual", "company" ] }, "country": { "type": "string" }, "addedAt": { "type": "string", "format": "date-time" }, "cap": { "type": "integer", "description": "Your plan's watchlist size" }, "remaining": { "type": "integer" } } } } } }, "400": { "description": "Invalid body. Returns { \"error\": \"\", \"message\": \"...\" }. `dateOfBirth`, `nationality` and `rescreenCadence` belong to the Sanctions Screening watchlist and are refused here (`unsupported_field`)." }, "409": { "description": "Watchlist full (`tier_cap_reached`)" } } }, "get": { "summary": "List your export watchlist with each entry's latest result (free)", "operationId": "listMonitored", "responses": { "200": { "description": "Watchlist", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "entityId": { "type": "string" }, "entityName": { "type": "string" }, "entityType": { "type": "string", "enum": [ "individual", "company" ] }, "country": { "type": "string", "description": "As given when the entry was added" }, "addedAt": { "type": "string", "format": "date-time" }, "lastScreenedAt": { "type": "string", "format": "date-time" }, "lastResult": { "type": "object", "description": "Summary of the latest daily screen" } } } } } } } } } } } }, "/monitored/changes": { "get": { "summary": "New matches on your export watchlist in the last N days (free)", "description": "Poll after 05:00 UTC. The first screen of a new entry lists every match as new (`kind` `first-screen`).", "operationId": "monitoredChanges", "parameters": [ { "in": "query", "name": "days", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 7 } } ], "responses": { "200": { "description": "Changes, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "days": { "type": "integer" }, "changes": { "type": "array", "items": { "type": "object", "properties": { "entityId": { "type": "string" }, "entityName": { "type": "string" }, "screenedAt": { "type": "string", "format": "date-time" }, "change": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "first-screen", "delta" ] }, "netNewSanctions": { "type": "integer", "description": "New possible matches on any of the ten lists" }, "newSanctionsMatches": { "type": "array", "description": "The listings that newly match, with enough detail to review them", "items": { "type": "object", "properties": { "list": { "type": "string", "description": "A list slug: us_el, us_dpl, us_dtc, us_uvl, us_isn, us_meu, ofsi, un, eu or ofac" }, "listingId": { "type": "string" }, "name": { "type": "string" }, "score": { "type": "number" }, "listedOn": { "type": "string", "format": "date", "description": "Export lists only" }, "federalRegister": { "type": "string", "description": "Export lists only" }, "sourceUrl": { "type": "string" } } } } } } } } } } } } } } } } }, "/monitored/{entityId}": { "delete": { "summary": "Remove an entry from your export watchlist (idempotent)", "operationId": "deleteMonitored", "parameters": [ { "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "204": { "description": "Removed (or was not on this watchlist)" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Stratum-Key" } }, "headers": { "ChecksUsed": { "description": "Checks used this calendar month (UTC), including this request", "schema": { "type": "integer" } }, "ChecksIncluded": { "description": "Checks included in your plan each month", "schema": { "type": "integer" } }, "ChecksLimit": { "description": "Where screening pauses this month (twice the allowance; the allowance during the free trial)", "schema": { "type": "integer" } } }, "responses": { "BadRequest": { "description": "Invalid input. `code` says which: `missing_name`, `invalid_name`, `invalid_type`, `invalid_country`,\n`invalid_reference`, `unsupported_field`, `invalid_json`, `missing_names`, `too_many_names`, `per_name_field`.\nIn `/bulk` the message names the item, for example `names[3].country ...`. A country we can't read is always\nrefused, never silently ignored. `dateOfBirth`, `nationality` and `pepAndAdverseMedia` belong to the Sanctions\nScreening API and are refused here (`unsupported_field`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_country", "message": "country must be a two-letter ISO 3166 country code, for example GB", "requestId": "EYIY1iPIrPEEPcg=" } } } } }, "Unauthorised": { "description": "Missing, invalid or revoked API key (`missing_key`, `invalid_key`, `revoked_key`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The key belongs to a different Stratum API (`wrong_api`; a Sanctions Screening key does not work here), the account has no Export Controls Screening plan (`no_plan`), or the call came through RapidAPI, where this API is not listed (`not_on_rapidapi`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "LimitReached": { "description": "This month's limit is reached (`monthly_limit_reached`, at twice your plan's allowance) or the free trial's\nallowance is used (`trial_limit_reached`). Nothing was screened or counted. Treat the names as not screened.\nScreening resumes on the 1st of next month, on upgrading, or when we raise your limit.\n", "headers": { "X-Checks-Used": { "$ref": "#/components/headers/ChecksUsed" }, "X-Checks-Included": { "$ref": "#/components/headers/ChecksIncluded" }, "X-Checks-Limit": { "$ref": "#/components/headers/ChecksLimit" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServerError": { "description": "The screen did not complete. Treat the name as not yet screened and retry with backoff; do not treat it as\nclear.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unavailable": { "description": "The export-control lists are not available right now (`export_lists_unavailable`), or the service timed out.\nNothing was screened or charged: a screen is never answered from the sanctions lists alone. Treat the name as\nnot yet screened and retry with backoff; do not treat it as clear.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "ExportListSlug": { "type": "string", "enum": [ "us_el", "us_dpl", "us_dtc", "us_uvl", "us_isn", "us_meu" ], "description": "`us_el` US Entity List, `us_dpl` Denied Persons List, `us_uvl` Unverified List, `us_meu` Military End User\nList (all BIS); `us_dtc` ITAR Debarred List, `us_isn` Nonproliferation Sanctions (both State Department)\n" }, "ListScreened": { "type": "object", "required": [ "list", "name", "listUpdated", "weCheckedOn" ], "properties": { "list": { "type": "string", "description": "A list slug: ofsi, un, eu, ofac, or one of the export list slugs" }, "name": { "type": "string" }, "listUpdated": { "type": [ "string", "null" ], "format": "date", "description": "When the publisher last changed the list. For the sanctions lists, their daily refresh date. `null` when the publisher's date was not in the file we read (never our own date in its place)." }, "weCheckedOn": { "type": "string", "format": "date", "description": "When we last fetched the list" } } }, "ListNotScreened": { "type": "object", "properties": { "list": { "type": "string" }, "name": { "type": "string" }, "why": { "type": "string" } } }, "Ownership": { "type": "object", "required": [ "level", "message", "owners", "limits", "companiesHouseNote" ], "properties": { "level": { "type": "string", "enum": [ "listed_owner_50_percent", "listed_owners_may_reach_50_percent", "listed_party_in_ownership", "nothing_found" ] }, "message": { "type": "string", "description": "What the ownership shows", "in a sentence": null, "for your record": null }, "owners": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "individual", "corporate" ] }, "companyNumber": { "type": [ "string", "null" ], "description": "For a UK company owner" }, "through": { "type": "array", "items": { "type": "string" }, "description": "The companies between this owner and the company checked", "nearest first": null }, "band": { "type": "string", "enum": [ "fifty_plus", "over_25_up_to_50", "control" ], "description": "This owner's own recorded holding" }, "reach": { "type": "string", "enum": [ "fifty_plus", "possible", "control" ], "description": "The whole chain read under the 50% rule" }, "holding": { "type": "string", "example": "owns 50% or more" }, "matches": { "type": "array", "description": "The strongest possible matches, at most five", "items": { "type": "object", "properties": { "list": { "type": "string" }, "listLabel": { "type": "string" }, "name": { "type": "string" }, "score": { "type": "number" } } } }, "moreMatches": { "type": "integer", "description": "Further", "weaker possible matches not shown": null } } } }, "limits": { "type": "array", "items": { "type": "string" }, "description": "Where the check could not see further (foreign owners", "withheld details": null, "loops": null, "depth)": null }, "companiesHouseNote": { "type": "string" }, "ownershipReadAt": { "type": "string", "format": "date-time", "description": "When the ownership was read from Companies House" } } }, "ListChangeItem": { "type": "object", "properties": { "name": { "type": "string", "description": "Name as the list publishes it" }, "listingId": { "type": "string", "description": "The Consolidated Screening List's id for the record" }, "previousListingId": { "type": "string", "description": "For an amended listing", "the id it replaced": null }, "federalRegister": { "type": "string", "description": "The Federal Register notice" }, "listedOn": { "type": "string", "format": "date", "description": "When the party was listed" }, "countries": { "type": "string", "description": "Countries of the listed addresses", "ISO codes joined": null } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "missing_name" }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "Quote this if you contact support" } } } } }, "BulkName": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "country": { "type": "string", "description": "Two-letter ISO 3166 code" }, "type": { "type": "string", "enum": [ "person", "entity", "any" ] }, "reference": { "type": "string", "maxLength": 100 }, "minScore": { "type": "number", "minimum": 0, "maximum": 1 } } }, "ScreeningResult": { "type": "object", "required": [ "checkId", "screenedAt", "query", "result", "count", "matches", "screenedWith", "listsScreened", "listsNotScreened", "notice" ], "properties": { "checkId": { "type": "string", "description": "Unique id for this screen. Keep it with your record; we keep no copy of the result." }, "screenedAt": { "type": "string", "format": "date-time", "description": "When the screen ran (UTC)" }, "reference": { "type": "string", "description": "Your reference", "when you sent one": null }, "query": { "type": "string", "description": "The name as screened" }, "result": { "type": "string", "enum": [ "no_match", "possible_match" ] }, "count": { "type": "integer", "description": "Number of possible matches at or above minScore", "across every list screened": null }, "matches": { "type": "array", "description": "Best first, from any of the lists screened", "items": { "oneOf": [ { "$ref": "#/components/schemas/ExportMatch" }, { "$ref": "#/components/schemas/SanctionsMatch" } ] } }, "screenedWith": { "type": "object", "description": "The inputs this screen used", "properties": { "type": { "type": "string", "enum": [ "person", "entity", "any" ] }, "minScore": { "type": "number" }, "country": { "type": "string" } } }, "listsScreened": { "type": "array", "items": { "$ref": "#/components/schemas/ListScreened" }, "description": "Each list this check covered, with both dates. Keep this with your record of the check." }, "listsNotScreened": { "type": "array", "items": { "$ref": "#/components/schemas/ListNotScreened" }, "description": "Any of the ten lists this check could not cover, and why. Empty when all ten were covered." }, "notice": { "type": "string", "description": "The screening-record notice, for your record" } } }, "ExportMatch": { "type": "object", "required": [ "list", "listLabel", "name", "score" ], "properties": { "list": { "$ref": "#/components/schemas/ExportListSlug" }, "listLabel": { "type": "string", "example": "US Entity List (BIS)" }, "name": { "type": "string", "description": "Name on the list" }, "aliases": { "type": "array", "items": { "type": "string" } }, "score": { "type": "number", "minimum": 0, "maximum": 1, "description": "How closely the name matches (1.0 = exact). A possible match is something to review", "not a confirmed match.": null }, "matchedAlias": { "type": "string", "description": "The listed alias that matched", "when the match came through an alias": null }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Street address and postal code" }, "city": { "type": "string" }, "country": { "type": "string", "description": "ISO 3166 code" } } } }, "countries": { "type": "array", "items": { "type": "string" }, "description": "ISO codes of every listed address" }, "countryMatch": { "type": "string", "enum": [ "match", "mismatch", "not_listed" ], "description": "Present when you sent a country. `not_listed` means the listing gives no address country." }, "listedOn": { "type": "string", "format": "date", "description": "When the party was listed" }, "endsOn": { "type": "string", "format": "date", "description": "When a time-limited order ends (mainly Denied Persons orders)" }, "federalRegister": { "type": "string", "description": "The Federal Register notice" }, "licenceRequirement": { "type": "string", "description": "As the list states it" }, "licencePolicy": { "type": "string", "description": "As the list states it, e.g. \"Presumption of denial\"" }, "programmes": { "type": "array", "items": { "type": "string" }, "description": "Nonproliferation Sanctions programmes" }, "listingId": { "type": "string", "description": "The Consolidated Screening List's id for the record" }, "sourceUrl": { "type": "string", "format": "uri", "description": "The list's page at its publisher" }, "moreInfoUrl": { "type": "string", "format": "uri" } } }, "SanctionsMatch": { "type": "object", "required": [ "list", "listLabel", "name", "type", "score" ], "description": "The same fields as a match from the Sanctions Screening API, plus `listLabel`", "properties": { "list": { "type": "string", "enum": [ "ofsi", "un", "eu", "ofac" ], "description": "`ofsi` is the UK Sanctions List (FCDO)" }, "listLabel": { "type": "string", "example": "UK Sanctions List (FCDO)" }, "name": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "person", "entity" ] }, "score": { "type": "number", "minimum": 0, "maximum": 1 }, "matchedAlias": { "type": "string" }, "dateOfBirth": { "type": "string" }, "nationality": { "type": "string" }, "sanctionRegime": { "type": "string" }, "designationDate": { "type": "string" }, "listingId": { "type": "string" }, "sourceUrl": { "type": "string", "format": "uri" } } } } } }