Sanctions Screening API

Sanctions screening checks whether a customer, supplier or payee appears on a government sanctions list before you do business with them. The API searches over 50,000 listed parties and 130,000 names and aliases and returns the potential matches, each with a score, the list it comes from and the details you need to review it.

Real-world names rarely match the list letter for letter. The API finds a listed party even when the name you screen is spelled differently:

• Typos and spelling variants – Sadam Husein finds Saddam HUSSEIN
• Transliterations – Evgenij Prigojin finds Evgeny Prigozhin
• Other scripts – Владимир Путин finds Vladimir Putin
• Word order and joined names – Mohammed Ali finds Ali Mohammed, and Abdulrahman finds Abdul Rahman
• Legal forms – Surgutneftegaz finds PJSC SURGUTNEFTEGAZ and Surgutneftegaz OAO, because words like PJSC, Ltd or Joint Stock Company are ignored

Sanctions lists

Each list is imported from its official source every day, so newly listed parties can be found soon after publication and delisted parties drop out of the results.

How it works

Send a POST request to the /v2/sanctions-screening endpoint with the name to screen in the JSON body. The name is sent in the request body rather than the URL, so it doesn't end up in URLs or access logs. Optional fields narrow the search:

• name – the person, company, vessel or aircraft name to screen (required)
• type – only match parties of this type: INDIVIDUAL, ENTITY, VESSEL or AIRCRAFT
• sources – only screen against these lists, e.g. ["OFAC_SDN", "EU"]. All lists by default
• min_score – the minimum match score, from 70 to 100. The default is 90

Example request

To screen a name, call /v2/sanctions-screening with the POST method:

• cURL
• PHP
• Python
• Node
• JavaScript

curl 'https://api.fincodesapi.com/v2/sanctions-screening' \
    --request POST \
    --header 'X-Api-Key: your-api-key-here' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --data '{"name":"Sadam Husein"}'

# INSTALLATION
$ composer require guzzlehttp/guzzle

# REQUEST
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.fincodesapi.com/v2/sanctions-screening', [
    'headers' => [
        'Accept' => 'application/json',
        'X-Api-Key' => 'your-api-key-here',
    ],
    'json' => [
        'name' => 'Sadam Husein',
    ],
]);

echo $response->getBody();

# INSTALLATION
$ python -m pip install requests

# REQUEST
import requests

url = "https://api.fincodesapi.com/v2/sanctions-screening"

headers = {
    "Accept": "application/json",
    "X-Api-Key": "your-api-key-here"
}

payload = {
    "name": "Sadam Husein"
}
response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

# INSTALLATION
$ npm install node-fetch --save

// REQUEST
import fetch from 'node-fetch';

const url = 'https://api.fincodesapi.com/v2/sanctions-screening';
const options = {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'X-Api-Key': 'your-api-key-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    'name': 'Sadam Husein'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

const options = {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'X-Api-Key': 'your-api-key-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    'name': 'Sadam Husein'
  })
};

fetch('https://api.fincodesapi.com/v2/sanctions-screening', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

The response lists the potential matches, best match first. This is the response when the search is limited to the OFAC SDN and EU lists and to individuals ("sources": ["OFAC_SDN", "EU"], "type": "INDIVIDUAL"):

{
    "success": true,
    "data": {
        "name": "Sadam Husein",
        "matches": [
            {
                "id": "246b7989-10e1-4496-bb37-aafd2670ea2f",
                "source": "OFAC_SDN",
                "source_reference": "7843",
                "type": "INDIVIDUAL",
                "name": "Saddam Hussein AL-TIKRITI",
                "matched_name": "Saddam HUSSEIN",
                "score": 96,
                "programs": ["IRAQ2"],
                "birth_dates": ["1937-04-28"],
                "listed_on": "2003-09-03"
            },
            {
                "id": "77198017-6882-4a61-878b-12ca28a48465",
                "source": "OFAC_SDN",
                "source_reference": "7845",
                "type": "INDIVIDUAL",
                "name": "Uday Saddam Hussein AL-TIKRITI",
                "matched_name": "Udai Saddam HUSSEIN",
                "score": 90,
                "programs": ["IRAQ2"],
                "birth_dates": ["1964", "1967"],
                "listed_on": "2003-09-03"
            },
            {
                "id": "ef947777-8b4c-4859-b07b-042be956bf4a",
                "source": "EU",
                "source_reference": "EU.27.28",
                "type": "INDIVIDUAL",
                "name": "Saddam Hussein Al-Tikriti",
                "matched_name": "Saddam Hussein Al-Tikriti",
                "score": 90,
                "programs": ["IRQ"],
                "birth_dates": ["1937-04-28"],
                "listed_on": "2003-07-08"
            }
        ]
    }
}

Each match includes:

• source and source_reference – the list and the party's reference in it, to look the party up in the official list
• name – the party's primary name
• matched_name – the name or alias that matched, which can differ from the primary name
• score – how closely the names match, from 0 to 100
• programs – the sanctions programs or regimes the party is listed under
• birth_dates – known birth dates of individuals, as YYYY, YYYY-MM or YYYY-MM-DD
• listed_on – the date the party was listed

If the name doesn't match any listed party, matches is an empty array.

How the score works

Before comparing, both names are converted to plain Latin letters and lowercase. Punctuation, titles such as Mr, and legal forms such as Ltd or JSC are removed. Each word of your name is then compared with the words of every name and alias of the listed parties. The comparison tolerates spelling differences and words that sound the same, and word order doesn't matter.

The score reflects how many of your words find a close match, and how close those matches are. Words in the listed name that aren't in yours lower the score only slightly. A score of 100 means the same words. Scores in the 90s mean small spelling differences:

• Hussein Saddam vs Saddam Hussein – 100
• Sadam Husein vs Saddam HUSSEIN – 96
• Saddam Hussein vs Saddam Hussein Al-Tikriti – 93
• Evgenij Prigojin vs Evgeny Prigozhin – 92

A single-word name, such as a company name, has to match the listed name as a whole, so John doesn't match every John Smith.

Reviewing matches

A match means the name is similar to a listed name, not that the person or company you screened is the listed party. Many people share names. In the example above, the second match is Saddam Hussein's son, found because the two names share Saddam and Hussein.

Treat matches as alerts to review rather than decisions. Compare other details you hold, such as date of birth, nationality or address, with the listed party, using the birth_dates in the response or the full entry in the official list. To see fewer weak matches, raise min_score. To see more, lower it, down to 70.

Sanctions screening supports your compliance process but doesn't replace it. You remain responsible for your own sanctions compliance, including deciding which lists apply to your business and how to handle matches.

Availability and pricing

Sanctions screening is available on all plans at no extra cost, including the free trial. Each distinct name you screen counts as one unique request toward your plan's monthly limit. Screening the same name again within 30 days doesn't count again.

Compare plans or start a free trial.

You can find full API documentation here.

Also validating bank details? Explore our Bank Account Validation API and Verification of Payee.