Introduction
The ComplyAdvantage API enables you to integrate your systems with our services to automate many of the functions available through the web user interface. Our API follows the REST convention and accepts and returns JSON data.
All requests should use the ComplyAdvantage root API URL (IP addresses of the API are dynamic) which can be found at:
https://api.complyadvantage.com/
All API requests must be made over HTTPS; calls made over plain HTTP will fail. API requests without authentication will also fail - see the Authentication section for information on correctly authenticating calls to the ComplyAdvantage API.
You can use any standard HTTPS client to access the web service. For simplicity and brevity we have provided code samples in this document in Javascript and Python. axios library is used for JavaScript samples and requests library is used for Python samples, but any http client library can be used.
| Language | Library for examples |
|---|---|
| JavaScript | axios |
| Python | requests |
Authentication
Example
const axios = require('axios');
// Authentication based on query parameter
axios.get('https://api.complyadvantage.com/users?api_key=<<.. your API key ..>>')
.then((response) => {
console.log(response.data);
});
// Authentication based on headers
const options = {
url: 'https://api.complyadvantage.com/users',
method: 'GET',
headers: {'Authorization': 'Token <<.. your API key ..>>'}
};
axios(options)
.then((response) => {
console.log(response.data);
});
import requests
# Authentication based on query parameter
url = "https://api.complyadvantage.com/users?api_key=<<.. your API key ..>>"
response = requests.get(url)
print(response.json())
# Authentication based on headers
url = "https://api.complyadvantage.com/users"
response = requests.get(url, headers= {'Authorization': 'Token <<.. your API key ..>>'})
print(response.json())
The ComplyAdvantage API uses API keys to authenticate requests. These API keys can be generated within the web platform and must be supplied with each request.
Your API keys can be used to perform a variety of actions against the API; whilst GET requests do not affect data in your account, the PATCH and POST requests can create, alter and reassign searches - so please ensure you follow best practice for managing API keys.
There is a raft of information about this on the web but in brief we suggest that you:
- Keep the keys secure - do not share API keys or give them to parties outside your organisation
- Rotate your API keys on a frequent basis
- Never, ever store your API keys in publicly-accessible locations - public github repositories, client-side code, documentation files and so on
When making requests to the ComplyAdvantage API there are two methods for providing your API key:
- As a query string parameter, e.g.
POST /searches?api_key=ggPS2ZOe8DQlCr2scgm2SBelVpNN1B6X
- In the Authorization header on the API request, e.g.
Token ggPS2ZOe8DQlCr2scgm2SBelVpNN1B6X
The code examples illustrate the two integration methods.
Responses & errors
We use standard HTTP status codes to indicate the success or failure of a request to our API.
Successful requests to our API will have a 200 HTTP status code; the “status” and “content” key-value pairs will detail the status message and the content of the response.
{
"status": "success",
"content": "... API response goes here ..."
}
Unsuccessful requests to our API will have a non-200 HTTP status code and will contain "code", "message" and "status" fields. The "message" field will contain any further information about the unsucessful request.
{
"code": 500,
"message": "Internal Server Error",
"status": "failure"
}
Note that the message may have more details about the error.
API Endpoints
The current list of available API endpoints on the ComplyAdvantage API is shown below. For a list of deprecated endpoints, please see the deprecated endpoints section.
| ENDPOINT | DESCRIPTION |
|---|---|
GET /users |
Get a list of users in your account |
GET /searches |
Get a list of your previous searches |
POST /searches |
Create a new search |
GET /searches/[id] |
Get an overview of one of your searches |
GET /searches/[id]/details |
Get full search results of one of your searches |
PATCH /searches/[id] |
Update details of one of your searches (eg, assigned user, status) |
PATCH /searches/[id]/entities |
Update entities details (eg, is_whitelisted risk_level, match_status) of one of your searches |
GET /searches/[id]/monitors |
Get monitored search details |
PATCH /searches/[id]/monitors |
Update monitored search details (start/stop monitoring) |
Concepts
Entities
Payload example
{
"id": "KCVZXTP179KK5KY",
"entity_type": "person",
"last_updated_utc": "2014-11-11T11:38:54",
"name": "Robert Mugabe",
"first_name": "Robert",
"last_name": "Mugabe",
"sources": [
"example-1-list"
],
"types": [
"sanction",
"pep"
],
"fields": [
{
"name": "Date of Birth",
"tag": "date_of_birth",
"value": "1924-02-21",
"source": "example-2-list"
},
{
"name": "Place of Birth",
"tag": "place_of_birth",
"value": "Zimbabwe",
"source": "example-3-list"
},
{
"name": "Nationality",
"tag": "nationality",
"value": "Zimbabwe",
"source": "example-3-list"
},
{
"name": "Address",
"value": "Harare, Zimbabwe",
"source": "example-4-list"
},
{
"name": "OFAC ID",
"value": "OFAC-16547",
"source": "example-5-list"
}
],
"aka": [
{
"name": "Robert Gabriel Mugabe"
}
],
"associates": [
{
"name": "Grace Mugabe",
"association": "Spouse"
}
],
"media": [
{
"date": "2018-09-17T00:00:00Z",
"snippet": "- Mugabe's son-in-law under probe PRESIDENT Emmerson Mnangagwa's anti-corruption unit has reportedly opened investigations into former President Robert Mugabe's son-in-law, Simba Chikore's involvement in the botched ZimAirways deal, NewsDay can reveal. BY RICHARD CHIDZA Highly-placed sources told NewsDay last week that Chikore, married to Mugabe's daughter, Bona, is the subject of an investigation over his involvement in the purchase of aircraft under a ZimAirways deal.",
"title": "Mugabe's son-in-law under probe – The Zimbabwe Mail",
"url": "https://www.thezimbabwemail.com/law-crime/mugabes-son-in-law-under-probe/"
}
]
}
{
"id": "KCVZXTP179KK5KY",
"entity_type": "person",
"last_updated_utc": "2014-11-11T11:38:54",
"name": "Robert Mugabe",
"first_name": "Robert",
"last_name": "Mugabe",
"sources": [
"example-1-list"
],
"types": [
"sanction",
"pep"
],
"fields": [
{
"name": "Date of Birth",
"tag": "date_of_birth",
"value": "1924-02-21",
"source": "example-2-list"
},
{
"name": "Place of Birth",
"tag": "place_of_birth",
"value": "Zimbabwe",
"source": "example-3-list"
},
{
"name": "Nationality",
"tag": "nationality",
"value": "Zimbabwe",
"source": "example-3-list"
},
{
"name": "Address",
"value": "Harare, Zimbabwe",
"source": "example-4-list"
},
{
"name": "OFAC ID",
"value": "OFAC-16547",
"source": "example-5-list"
}
],
"aka": [
{
"name": "Robert Gabriel Mugabe"
}
],
"associates": [
{
"name": "Grace Mugabe",
"association": "Spouse"
}
],
"media": [
{
"date": "2018-09-17T00:00:00Z",
"snippet": "- Mugabe's son-in-law under probe PRESIDENT Emmerson Mnangagwa's anti-corruption unit has reportedly opened investigations into former President Robert Mugabe's son-in-law, Simba Chikore's involvement in the botched ZimAirways deal, NewsDay can reveal. BY RICHARD CHIDZA Highly-placed sources told NewsDay last week that Chikore, married to Mugabe's daughter, Bona, is the subject of an investigation over his involvement in the purchase of aircraft under a ZimAirways deal.",
"title": "Mugabe's son-in-law under probe – The Zimbabwe Mail",
"url": "https://www.thezimbabwemail.com/law-crime/mugabes-son-in-law-under-probe/"
}
]
}
{
"id": "KCVZXTP179KK5KY",
"entity_type": "person",
"last_updated_utc": "2014-11-11T11:38:54",
"name": "Robert Mugabe",
"first_name": "Robert",
"last_name": "Mugabe",
"sources": [
"example-1-list"
],
"types": [
"sanction",
"pep"
],
"fields": [
{
"name": "Date of Birth",
"tag": "date_of_birth",
"value": "1924-02-21",
"source": "example-2-list"
},
{
"name": "Place of Birth",
"tag": "place_of_birth",
"value": "Zimbabwe",
"source": "example-3-list"
},
{
"name": "Nationality",
"tag": "nationality",
"value": "Zimbabwe",
"source": "example-3-list"
},
{
"name": "Address",
"value": "Harare, Zimbabwe",
"source": "example-4-list"
},
{
"name": "OFAC ID",
"value": "OFAC-16547",
"source": "example-5-list"
}
],
"aka": [
{
"name": "Robert Gabriel Mugabe"
}
],
"associates": [
{
"name": "Grace Mugabe",
"association": "Spouse"
}
],
"media": [
{
"date": "2018-09-17T00:00:00Z",
"snippet": "- Mugabe's son-in-law under probe PRESIDENT Emmerson Mnangagwa's anti-corruption unit has reportedly opened investigations into former President Robert Mugabe's son-in-law, Simba Chikore's involvement in the botched ZimAirways deal, NewsDay can reveal. BY RICHARD CHIDZA Highly-placed sources told NewsDay last week that Chikore, married to Mugabe's daughter, Bona, is the subject of an investigation over his involvement in the purchase of aircraft under a ZimAirways deal.",
"title": "Mugabe's son-in-law under probe – The Zimbabwe Mail",
"url": "https://www.thezimbabwemail.com/law-crime/mugabes-son-in-law-under-probe/"
}
]
}
Because no two entities are the same, the data returned when fetching an entity may include more or less information than another entity. The information is provided in the fields array, as shown in the Javascript sample.
A full description of the data contained in the entity is covered below:
| FIELD | DESCRIPTION |
|---|---|
id |
This is the unique identity of a ComplyAdvantage entity. |
entity_type |
This is the type of the entity, such as "person", "company" etc... |
last_updated_utc |
This is the time that the entity was last updated (UTC) |
name |
Name of entity, such as person name (e.g. "Robert Mugabe") |
first_name |
First name of entity, such as "Robert" (note, this only appears if present and when entity_type is person) |
middle_name |
Middle name of entity, such as "Gabriel" (note, this only appears if present and when entity_type is person) |
last_name |
Last name of entity, such as "Mugabe" (note, this only appears if present and when entity_type is person) |
sources |
Array of data sources (eg. sanction lists) |
types |
What kind of alert or warning is associated with the entity (from "sanction", "pep", "warning") |
aka |
Array of alternative names for the entity. Note that the "name" field is present at the minimum. |
associates |
Array of names of associated entities. Note that the "name" field present at the minimum, also the "association" (such as "Spouse", "Brother" etc...) and "comment" fields. |
fields |
Array of data fields with "name" and "value" parameters at the minimum. |
media |
List of media entries where appropriate, with the "date", "title", "snippet" and "url" parameters. |
A fields may have a "tag" parameter in addition to "name" and "value" when it falls into one of the following categories:
| TAG | DESCRIPTION |
|---|---|
date_of_birth |
Date of Birth for entity (yyyy or yyyy-mm-dd) |
place_of_birth |
Place of Birth for entity |
date_of_death |
Date of Death for entity (yyyy or yyyy-mm-dd) |
country_codes |
Associated country codes for a person or company |
country_names |
Associated country names for a person or company |
Please note that all dates are in "yyyy-mm-dd" or "yyyy" format.
Case & Client Management
Our /search endpoints not only allow you to perform new searches, but manage your existing ones as well. You can assign searches to team members, set the search status, and set the risk level. This allows you to build complex applications on top of our API, where searches are treated as cases which are assigned to users and need to be resolved.
Further details are available within the Endpoints section below.
Clients & Whitelisting
One of the key features of the Search system is the ability to supply your own unique client reference along with your searches. One benefit of this is that you can then view all the historical searches for a particular client, but the second benefit can offer significant benefits in terms of team workflow - result whitelisting.
The whitelisting feature means that if you perform a search on a client of yours (ie, you have supplied a client reference as part of the search) we will track the results. If there are any hits, the system takes note of this, and WILL NOT REPORT THE SAME RESULTS for subsequent searches on that client, unless the contents of those results change as well.
As an example, you may be integrating our service as part of a live transaction monitoring platform. If you have a particular client making transactions every day, who happens to flag up every time, it would be inefficient to have to manually dismiss the same results every time. By simply supplying the client reference when the search is performed, we will track and automatically dismiss future identical results to which you have already been alerted.
In order to activate this functionality, you simply need to include the optional client_ref when making a search. Please see the documentation for creating, retrieving and updating searches for more information.
Searches & Tags
Tags example:
{
"tags": {
"MyTag": "NewValue"
},
"labels": [
{
"type": "tag",
"name": "MyTag",
"value": "OldValue"
},
{
"type": "tag",
"name": "MyTag",
"value": "NewValue"
}
]
}
{
"tags": {
"MyTag": "NewValue"
},
"labels": [
{
"type": "tag",
"name": "MyTag",
"value": "OldValue"
},
{
"type": "tag",
"name": "MyTag",
"value": "NewValue"
}
]
}
{
"tags": {
"MyTag": "NewValue"
},
"labels": [
{
"type": "tag",
"name": "MyTag",
"value": "OldValue"
},
{
"type": "tag",
"name": "MyTag",
"value": "NewValue"
}
]
}
When performing a search via the API, you are able to attach Tags to the search. These are key: value pairs which can be used to add additional information to your search. They can also be added when updating a search status via API, or via our Case Management GUI in the web application.
Tag names have to be set up in the web application before you can use them in the API. For example, if you wanted to separate the searches into "prospects" and "clients" you might add a new tag name called type. You could then add type: prospect to some searches and type: client to others.
Another useful example is if you have a URL on an internal system to which you would like to link. Adding the tag BackOfficeURL: https://bp.example.com/mysystem/client-1234 (for example) will mean the URL is displayed when viewing the search result in the web application, allowing you to click through to your internal system. Again, the BackOfficeURL tag name will need to be set up in advance.
Tags can be added to API requests as per the documentation for the relevant endpoints, eg POST /searches
When retrieving a search containing the same tag with multiple values, the tags field will contain the latest value for that particular tags, but the labels field will contain all values, as shown in the code sample area.
Creating Searches
POST /searches
Create a new search by POSTing search terms, parameters and filters. By default creating a search will pull the first 100 results (if that many exist) from our database. By using the offset and limit parameters, you can expand this, or create multiple searches which "paginate" through our data sources.
Example Request 1
Example request 1
const url = 'https://api.complyadvantage.com/searches?api_key=<<.. your API key ..>>'
axios.post(url, {
"search_term": "A Bad Company Ltd",
"fuzziness": 0.6,
"filters": {
"types": [
"sanction",
"warning"
]
},
"tags": {
"name": "value"
},
"share_url": 1
})
.then((response) => {
console.log(response.data);
});
url = "https://api.complyadvantage.com/searches?api_key=<<.. your API key ..>>"
response = requests.post(url, data = {
"search_term": "A Bad Company Ltd",
"fuzziness": 0.6,
"filters": {
"types": [
"sanction",
"warning"
]
},
"tags": {
"name": "value"
},
"share_url": 1
})
print(response.json())
{
"search_term": "A Bad Company Ltd",
"fuzziness": 0.6,
"filters": {
"types": [
"sanction",
"warning"
]
},
"tags": {
"name": "value"
},
"share_url": 1
}
This illustrates the simplest search request, with the minimum of information required.
Example Request 2
Example request 2
const url = 'https://api.complyadvantage.com/searches?api_key=<<.. your API key ..>>'
// search_term format 1
axios.post(url, {
"search_term": "Robert Gabriel Mugabe",
"client_ref": "CUST000456",
"fuzziness": 0.6,
"search_profile": "my-usa-profile-1",
"filters": {
"birth_year": "1924",
"entity_type": "person",
"country_codes": ["BD", "LK"]
},
"share_url": 1
})
.then((response) => {
console.log(response.data);
});
// search_term format 2
// last_name is compulsory in this format
// middle_names and first_name are optional
axios.post(url, {
"search_term": {
"last_name": "Mugabe",
"middle_names": "Gabriel",
"first_name": "Robert"
},
"client_ref": "CUST000456",
"fuzziness": 0.6,
"filters": {
"types": ["sanction", "warning"],
"birth_year": "1924"
},
"share_url": 1
})
.then((response) => {
console.log(response.data);
});
# search_term format 1
url = "https://api.complyadvantage.com/searches?api_key=<<.. your API key ..>>"
response = requests.post(url, data = {
"search_term": "Robert Gabriel Mugabe",
"client_ref": "CUST000456",
"fuzziness": 0.6,
"search_profile": "my-usa-profile-1",
"filters": {
"birth_year": "1924",
"entity_type": "person",
"country_codes": ["BD", "LK"]
},
"share_url": 1
})
print(response.json())
# search_term format 2
# last_name is compulsory in this format
# middle_names and first_name are optional
response = requests.post(url, data = {
"search_term": {
"last_name": "Mugabe",
"middle_names": "Gabriel",
"first_name": "Robert"
},
"client_ref": "CUST000456",
"fuzziness": 0.6,
"filters": {
"types": [
"sanction",
"warning"
],
"birth_year": "1924"
},
"share_url": 1
})
print(response.json())
# search_term format 1
{
"search_term": "Robert Gabriel Mugabe",
"client_ref": "CUST000456",
"fuzziness": 0.6,
"search_profile": "my-usa-profile-1",
"filters": {
"birth_year": "1924",
"entity_type": "person",
"country_codes": [
"BD",
"LK"
]
},
"share_url": 1
}
# search_term format 2
# last_name is compulsory in this format
# middle_names and first_name are optional
{
"search_term": {
"last_name": "Mugabe",
"middle_names": "Gabriel",
"first_name": "Robert"
},
"client_ref": "CUST000456",
"fuzziness": 0.6,
"filters": {
"types": [
"sanction",
"warning"
],
"birth_year": "1924"
},
"share_url": 1
}
This example includes the client reference and search profile
Example Request 3
Example request 3
const url = 'https://api.complyadvantage.com/searches?api_key=<<.. your API key ..>>'
axios.post(url, {
"search_term": "Robert Gabriel Mugabe",
"client_ref": "CUST000456",
"exact_match": true,
"search_profile": "my-usa-profile-1",
"filters": {
"birth_year": "1924",
"entity_type": "person",
"country_codes": [
"BD",
"LK"
]
},
"share_url": 1
})
.then((response) => {
console.log(response.data);
});
url = "https://api.complyadvantage.com/searches?api_key=<<.. your API key ..>>"
response = requests.post(url, data = {
"search_term": "Robert Gabriel Mugabe",
"client_ref": "CUST000456",
"exact_match": true,
"search_profile": "my-usa-profile-1",
"filters": {
"birth_year": "1924",
"entity_type": "person",
"country_codes": [
"BD",
"LK"
]
},
"share_url": 1
})
print(response.json())
{
"search_term": "Robert Gabriel Mugabe",
"client_ref": "CUST000456",
"exact_match": true,
"search_profile": "my-usa-profile-1",
"filters": {
"birth_year": "1924",
"entity_type": "person",
"country_codes": [
"BD",
"LK"
]
},
"share_url": 1
}
This example includes the exact_match option
JSON POST PARAMETERS
| FIELD TYPE | TYPE | DESCRIPTION |
|---|---|---|
search_term (required, max 255 characters) |
String/Object | A string representing the name of the entity or an Object (see examples) |
client_ref (optional) |
String | Your reference for this person/entity for which you are searching. Used for tracking searches and auto-whitelisting recurring results |
search_profile (optional) |
String | The slug of any of your previously created search profiles, which can be found in the main platform UI for search profiles |
fuzziness (optional) |
Float(0.0 to 1.0) | Determines how closely the returned results must match the supplied name. Overridden by exact_match (see below) |
offset (optional) |
Integer(default 0) | Match results from the database, starting from the offset value |
limit (optional) |
Integer(default 100, Max 100) | Match results from the database, taking up to this many matches each search |
filters (optional) |
Object | Specify filters within the search to narrow down the results. These are specified below, and are all optional |
tags (optional) |
Object | Object of name => value pairs (name must be string) |
share_url (optional) |
Integer(0 or 1) | Include a shareable URL to access search publicly |
country_codes (optional) |
Array of ISO 3166-1 alpha-2 strings | Results are filtered by the entity nationality or country of residence |
exact_match (optional) |
Boolean | Exact match disables all standard and optional matching behaviours (Honorifics, affixes, initials, glued name, name variation, equivalent names, extra words in entity,...) 0% fuzziness disables 1 letter typo matching but keeps all other matching behaviours (standard and optional) |
Filters in searches
Filters example
const url = 'https://api.complyadvantage.com/searches?api_key=<<.. your API key ..>>'
axios.post(url, {
"search_term": {
"last_name": "Mugabe",
"middle_names": "Gabriel",
"first_name": "Robert"
},
"client_ref": "CUST000456",
"fuzziness": 0.6,
"filters": {
"types": [
"sanction",
"warning"
],
"birth_year": "1924"
},
"share_url": 1
})
.then((response) => {
console.log(response.data);
});
url = "https://api.complyadvantage.com/searches?api_key=<<.. your API key ..>>"
response = requests.post(url, data = {
"search_term": {
"last_name": "Mugabe",
"middle_names": "Gabriel",
"first_name": "Robert"
},
"client_ref": "CUST000456",
"fuzziness": 0.6,
"filters": {
"types": [
"sanction",
"warning"
],
"birth_year": "1924"
},
"share_url": 1
})
print(response.json())
{
"search_term": {
"last_name": "Mugabe",
"middle_names": "Gabriel",
"first_name": "Robert"
},
"client_ref": "CUST000456",
"fuzziness": 0.6,
"filters": {
"types": [
"sanction",
"warning"
],
"birth_year": "1924"
},
"share_url": 1
}
Filters are used within the search to refine the result set. There is an extensive range of filters available - use of the filters is entirely optional. The example shows how the filters should be included in the request to the endpoint.
The full range of filter parameters available is outlined below.
| FIELD NAME | TYPE | DESCRIPTION |
|---|---|---|
types |
Array of strings | (*) One or more of:
|
birth_year |
Integer | Year of birth, if known |
remove_deceased |
"1" or "0" | A flag which when set, removes deceased people from search results |
country_codes |
Array of ISO 3166-1 alpha-2 strings | Results are filtered by the entity nationality or country of residence. Country code filtering applies to:
Country code filtering does not apply to (i.e. results will still appear regardless of the country filter):
|
entity_type |
String (one of):
|
Entity type filter is not a hard filter between different entity types. It only optimizes the matching logic to the relevant entity type. Matching:
Optional: If missing, a default set of rules and logic will be applied. |
(*) Note that search_profile and types are mutually exclusive, and only one of these two options should be provided.
Example response 1
Response sample
{
"content": {
"data": {
"id": 46,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 1,
"search_profile": {
"name": "My USA Profile 1",
"slug": "my-usa-profile-1"
},
"filters": {
"entity_type": "person",
"types": [
"sanction",
"warning"
],
"birth_year": "1924",
"passport": "AD10095",
"exact_match": false,
"fuzziness": 0.6
},
"match_status": "potential_match",
"risk_level": "unknown",
"search_term": "Robert Mugabe",
"total_hits": 1,
"updated_at": "2015-06-18 16:52:42",
"created_at": "2015-06-18 16:52:42",
"tags": {
"name": "value"
},
"hits": [
{
"doc": {
"aka": [],
"associates": [
{
"name": "Grace Mugabe",
"association": "Spouse"
}
],
"entity_type": "person",
"fields": [
{
"locale": "en",
"name": "Justification",
"source": "swiss-seco-list",
"value": "Head of Government and responsible for activities that seriously undermine democracy, respect for human rights and the rule of law."
},
{
"name": "Other Information",
"source": "swiss-seco-list",
"value": "President."
},
{
"name": "Date of Birth",
"source": "swiss-seco-list",
"tag": "date_of_birth",
"value": "1924"
}
],
"first_name": "Robert",
"id": "RU4326M8GFUAHMF",
"last_name": "Mugabe",
"last_updated_utc": "2015-06-16T01:11:14Z",
"middle_names": "Gabriel",
"media": [
{
"date": "2018-09-17T00:00:00Z",
"snippet": "- Mugabe's son-in-law under probe PRESIDENT Emmerson Mnangagwa's anti-corruption unit has reportedly opened investigations into former President Robert Mugabe's son-in-law, Simba Chikore's involvement in the botched ZimAirways deal, NewsDay can reveal. BY RICHARD CHIDZA Highly-placed sources told NewsDay last week that Chikore, married to Mugabe's daughter, Bona, is the subject of an investigation over his involvement in the purchase of aircraft under a ZimAirways deal.",
"title": "Mugabe's son-in-law under probe – The Zimbabwe Mail",
"url": "https://www.thezimbabwemail.com/law-crime/mugabes-son-in-law-under-probe/"
}
],
"name": "Mugabe Robert Gabriel",
"sources": [
"swiss-seco-list"
],
"types": [
"sanction"
]
},
"is_whitelisted": false,
"match_types": [
"name_exact",
"year_of_birth"
],
"match_types_details": [],
"score": 3.511
}
],
"share_url": "http://app.complyadvantage.com/public/search/1496748100-l9qHqbVF/64a6114f299b"
}
},
"status": "success"
}
{
"content": {
"data": {
"id": 46,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 1,
"search_profile": {
"name": "My USA Profile 1",
"slug": "my-usa-profile-1"
},
"filters": {
"entity_type": "person",
"types": [
"sanction",
"warning"
],
"birth_year": "1924",
"passport": "AD10095",
"exact_match": false,
"fuzziness": 0.6
},
"match_status": "potential_match",
"risk_level": "unknown",
"search_term": "Robert Mugabe",
"total_hits": 1,
"updated_at": "2015-06-18 16:52:42",
"created_at": "2015-06-18 16:52:42",
"tags": {
"name": "value"
},
"hits": [
{
"doc": {
"aka": [],
"associates": [
{
"name": "Grace Mugabe",
"association": "Spouse"
}
],
"entity_type": "person",
"fields": [
{
"locale": "en",
"name": "Justification",
"source": "swiss-seco-list",
"value": "Head of Government and responsible for activities that seriously undermine democracy, respect for human rights and the rule of law."
},
{
"name": "Other Information",
"source": "swiss-seco-list",
"value": "President."
},
{
"name": "Date of Birth",
"source": "swiss-seco-list",
"tag": "date_of_birth",
"value": "1924"
}
],
"first_name": "Robert",
"id": "RU4326M8GFUAHMF",
"last_name": "Mugabe",
"last_updated_utc": "2015-06-16T01:11:14Z",
"middle_names": "Gabriel",
"media": [
{
"date": "2018-09-17T00:00:00Z",
"snippet": "- Mugabe's son-in-law under probe PRESIDENT Emmerson Mnangagwa's anti-corruption unit has reportedly opened investigations into former President Robert Mugabe's son-in-law, Simba Chikore's involvement in the botched ZimAirways deal, NewsDay can reveal. BY RICHARD CHIDZA Highly-placed sources told NewsDay last week that Chikore, married to Mugabe's daughter, Bona, is the subject of an investigation over his involvement in the purchase of aircraft under a ZimAirways deal.",
"title": "Mugabe's son-in-law under probe – The Zimbabwe Mail",
"url": "https://www.thezimbabwemail.com/law-crime/mugabes-son-in-law-under-probe/"
}
],
"name": "Mugabe Robert Gabriel",
"sources": [
"swiss-seco-list"
],
"types": [
"sanction"
]
},
"is_whitelisted": false,
"match_types": [
"name_exact",
"year_of_birth"
],
"match_types_details": [],
"score": 3.511
}
],
"share_url": "http://app.complyadvantage.com/public/search/1496748100-l9qHqbVF/64a6114f299b"
}
},
"status": "success"
}
{
"content": {
"data": {
"id": 46,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 1,
"search_profile": {
"name": "My USA Profile 1",
"slug": "my-usa-profile-1"
},
"filters": {
"entity_type": "person",
"types": [
"sanction",
"warning"
],
"birth_year": "1924",
"passport": "AD10095",
"exact_match": false,
"fuzziness": 0.6
},
"match_status": "potential_match",
"risk_level": "unknown",
"search_term": "Robert Mugabe",
"total_hits": 1,
"updated_at": "2015-06-18 16:52:42",
"created_at": "2015-06-18 16:52:42",
"tags": {
"name": "value"
},
"hits": [
{
"doc": {
"aka": [],
"associates": [
{
"name": "Grace Mugabe",
"association": "Spouse"
}
],
"entity_type": "person",
"fields": [
{
"locale": "en",
"name": "Justification",
"source": "swiss-seco-list",
"value": "Head of Government and responsible for activities that seriously undermine democracy, respect for human rights and the rule of law."
},
{
"name": "Other Information",
"source": "swiss-seco-list",
"value": "President."
},
{
"name": "Date of Birth",
"source": "swiss-seco-list",
"tag": "date_of_birth",
"value": "1924"
}
],
"first_name": "Robert",
"id": "RU4326M8GFUAHMF",
"last_name": "Mugabe",
"last_updated_utc": "2015-06-16T01:11:14Z",
"middle_names": "Gabriel",
"media": [
{
"date": "2018-09-17T00:00:00Z",
"snippet": "- Mugabe's son-in-law under probe PRESIDENT Emmerson Mnangagwa's anti-corruption unit has reportedly opened investigations into former President Robert Mugabe's son-in-law, Simba Chikore's involvement in the botched ZimAirways deal, NewsDay can reveal. BY RICHARD CHIDZA Highly-placed sources told NewsDay last week that Chikore, married to Mugabe's daughter, Bona, is the subject of an investigation over his involvement in the purchase of aircraft under a ZimAirways deal.",
"title": "Mugabe's son-in-law under probe – The Zimbabwe Mail",
"url": "https://www.thezimbabwemail.com/law-crime/mugabes-son-in-law-under-probe/"
}
],
"name": "Mugabe Robert Gabriel",
"sources": [
"swiss-seco-list"
],
"types": [
"sanction"
]
},
"is_whitelisted": false,
"match_types": [
"name_exact",
"year_of_birth"
],
"match_types_details": [],
"score": 3.511
}
],
"share_url": "http://app.complyadvantage.com/public/search/1496748100-l9qHqbVF/64a6114f299b"
}
},
"status": "success"
}
When performing a search for one or more names, the response will contain a results array, with each object in this array corresponding to a search term.
Each of these search terms will contain a hits array. This array contains entity objects matching the search term. The format of the entity objects can be seen above in the entities section.
FIELDS TO NOTE IN THE RESPONSE DATA
is_whitelisted
This indicates whether or not an entity has been whitelisted according to the supplied client-ref, and appears if the whitelist feature has been switched on for your account. You can modify this via your settings page or contact your account manager at Complyadvantage for more information about this feature. Entities are regarded as whitelisted if they are matched as false positive via your client reference, and have not been updated since.
score
The search results match and ranking is computed via a score that is included a part of the metadata. This score is not an absolute ranking of the document, and should only be used in the context of ordering search results, and give some relative indication of relevance.
match_type
Whenever we match against a document, we try to include some data as to what matched. We return the first value that is true from the following possible values:
name_exact matched against the entity name exactly
aka_exact matched against an entity AKA (also known as) entry exactly
name_fuzzy matched closely to the name, but at least one word had an edit distance change
aka_fuzzy matched closely to an AKA name, but at least one word had an edit distance change
phonetic_name matched against the entity name phonetically
phonetic_aka matched against an entity AKA phonetically
equivalent_name matched against the entity name with a synonym, e.g. "Robert Mugabe" => "Bob Mugabe"
equivalent_aka matched against an entity AKA with a synonym, e.g. "Robert Mugabe" => "Bob Mugabe"
unknown matched for a more complex reason, such as based on an acronym
Along with, if appropriate:
year_of_birth matched the birth year as given in filters, can be the exact year of +-1 year regarding the fuzziness and options
removed_personal_title a personal title, for example 'Mrs', was stripped from the search term
removed_personal_suffix a personal suffix, for example 'PhD', was stripped from the search term
removed_organisation_prefix an organisation prefix, for example 'JSC', was stripped from the search term
removed_organisation_suffix an organisation suffix, for example 'Ltd', was stripped from the search term
removed_clerical_mark a clerical mark, for example 'DECEASED', was stripped from the search term
match_types_details
This fields gives a more detailed breakdown of why a match happened. Please refer to the Match Types Details section for more information.
Example response 2
{
"code": 200,
"status": "success",
"content": {
"data": {
"id": 23236657,
"ref": "1554108581-EG5TXMgr",
"searcher_id": 2246,
"assignee_id": 2246,
"filters": {
"birth_year": 1924,
"country_codes": [],
"remove_deceased": 0,
"types": [
"sanction",
"warning"
],
"exact_match": false,
"fuzziness": 0.6
},
"match_status": "potential_match",
"risk_level": "unknown",
"search_term": "Robert Gabriel Mugabe",
"submitted_term": "Robert Gabriel Mugabe",
"client_ref": "CUST000456",
"total_hits": 1,
"updated_at": "2019-04-01 08:49:42",
"created_at": "2019-04-01 08:49:42",
"tags": [],
"limit": 100,
"offset": 0,
"share_url": "https://app-qa.complyadvantage.com/public/search/1554108581-EG5TXMgr/646dc1368af0",
"searcher": {
"id": 2246,
"email": "my profile email",
"name": "my profile name",
"phone": "",
"created_at": "2019-02-26 14:58:41"
},
"assignee": {
"id": 2246,
"email": "assignee's email",
"name": "assignee's name",
"phone": "",
"created_at": "2019-02-26 14:58:41"
},
"hits": [
{
"doc": {
"aka": [
{
"name": "Роберта Мугабе"
},
{
"name": "Робърт Мугабе"
},
{
"name": "Roberta Mugabe"
},
{
"name": "Ρόμπερτ Μουγκάμπε"
},
{
"name": "รอเบิร์ต มูกาบี"
},
{
"name": "ராபர்ட் முகாபே"
},
{
"name": "Rob Mugabe"
},
{
"name": "Robert Gabriel Mugabe"
}
]
}
}
]
}
}
}
{
"code": 200,
"status": "success",
"content": {
"data": {
"id": 23236657,
"ref": "1554108581-EG5TXMgr",
"searcher_id": 2246,
"assignee_id": 2246,
"filters": {
"birth_year": 1924,
"country_codes": [],
"remove_deceased": 0,
"types": [
"sanction",
"warning"
],
"exact_match": false,
"fuzziness": 0.6
},
"match_status": "potential_match",
"risk_level": "unknown",
"search_term": "Robert Gabriel Mugabe",
"submitted_term": "Robert Gabriel Mugabe",
"client_ref": "CUST000456",
"total_hits": 1,
"updated_at": "2019-04-01 08:49:42",
"created_at": "2019-04-01 08:49:42",
"tags": [],
"limit": 100,
"offset": 0,
"share_url": "https://app-qa.complyadvantage.com/public/search/1554108581-EG5TXMgr/646dc1368af0",
"searcher": {
"id": 2246,
"email": "my profile email",
"name": "my profile name",
"phone": "",
"created_at": "2019-02-26 14:58:41"
},
"assignee": {
"id": 2246,
"email": "assignee's email",
"name": "assignee's name",
"phone": "",
"created_at": "2019-02-26 14:58:41"
},
"hits": [
{
"doc": {
"aka": [
{
"name": "Роберта Мугабе"
},
{
"name": "Робърт Мугабе"
},
{
"name": "Roberta Mugabe"
},
{
"name": "Ρόμπερτ Μουγκάμπε"
},
{
"name": "รอเบิร์ต มูกาบี"
},
{
"name": "ராபர்ட் முகாபே"
},
{
"name": "Rob Mugabe"
},
{
"name": "Robert Gabriel Mugabe"
}
]
}
}
]
}
}
}
{
"code": 200,
"status": "success",
"content": {
"data": {
"id": 23236657,
"ref": "1554108581-EG5TXMgr",
"searcher_id": 2246,
"assignee_id": 2246,
"filters": {
"birth_year": 1924,
"country_codes": [],
"remove_deceased": 0,
"types": [
"sanction",
"warning"
],
"exact_match": false,
"fuzziness": 0.6
},
"match_status": "potential_match",
"risk_level": "unknown",
"search_term": "Robert Gabriel Mugabe",
"submitted_term": "Robert Gabriel Mugabe",
"client_ref": "CUST000456",
"total_hits": 1,
"updated_at": "2019-04-01 08:49:42",
"created_at": "2019-04-01 08:49:42",
"tags": [],
"limit": 100,
"offset": 0,
"share_url": "https://app-qa.complyadvantage.com/public/search/1554108581-EG5TXMgr/646dc1368af0",
"searcher": {
"id": 2246,
"email": "my profile email",
"name": "my profile name",
"phone": "",
"created_at": "2019-02-26 14:58:41"
},
"assignee": {
"id": 2246,
"email": "assignee's email",
"name": "assignee's name",
"phone": "",
"created_at": "2019-02-26 14:58:41"
},
"hits": [
{
"doc": {
"aka": [
{
"name": "Роберта Мугабе"
},
{
"name": "Робърт Мугабе"
},
{
"name": "Roberta Mugabe"
},
{
"name": "Ρόμπερτ Μουγκάμπε"
},
{
"name": "รอเบิร์ต มูกาบี"
},
{
"name": "ராபர்ட் முகாபே"
},
{
"name": "Rob Mugabe"
},
{
"name": "Robert Gabriel Mugabe"
}
]
}
}
]
}
}
}
When performing a search with no tag reference, the response will contain an array of empty tags as shown in the example.
Match Types Details
Response sample
{
"search_term": "Robert Gabrial Mugabe",
"hits": [
{
"doc": {},
"match_types_details": [
{
"matching_name": "Robert Gabriel Mugabe",
"sources": [
"OFAC SDN List"
],
"aml_types": [
"sanction"
],
"name_matches": [
{
"query_term": "robert",
"match_types": [
"exact_match"
]
},
{
"query_term": "gabrial",
"match_types": [
"edit_distance"
]
},
{
"query_term": "mugabe",
"match_types": [
"exact_match"
]
}
],
"secondary_matches": [
{
"query_term": "1924",
"match_types": [
"exact_birth_year_match"
]
}
]
},
{
"matching_name": "Robert Mugabe",
"sources": [
"ComplyAdvantage Adverse Media"
],
"aml_types": [
"adverse-media"
],
"name_matches": [
{
"query_term": "robert",
"match_types": [
"exact_match"
]
},
{
"query_term": "gabrial",
"match_types": [
"name_variations_removal"
]
},
{
"query_term": "mugabe",
"match_types": [
"exact_match"
]
}
],
"secondary_matches": [
{
"query_term": "1924",
"match_types": [
"exact_birth_year_match"
]
}
]
}
]
}
]
}
{
"search_term": "Robert Gabrial Mugabe",
"hits": [
{
"doc": {},
"match_types_details": [
{
"matching_name": "Robert Gabriel Mugabe",
"sources": [
"OFAC SDN List"
],
"aml_types": [
"sanction"
],
"name_matches": [
{
"query_term": "robert",
"match_types": [
"exact_match"
]
},
{
"query_term": "gabrial",
"match_types": [
"edit_distance"
]
},
{
"query_term": "mugabe",
"match_types": [
"exact_match"
]
}
],
"secondary_matches": [
{
"query_term": "1924",
"match_types": [
"exact_birth_year_match"
]
}
]
},
{
"matching_name": "Robert Mugabe",
"sources": [
"ComplyAdvantage Adverse Media"
],
"aml_types": [
"adverse-media"
],
"name_matches": [
{
"query_term": "robert",
"match_types": [
"exact_match"
]
},
{
"query_term": "gabrial",
"match_types": [
"name_variations_removal"
]
},
{
"query_term": "mugabe",
"match_types": [
"exact_match"
]
}
],
"secondary_matches": [
{
"query_term": "1924",
"match_types": [
"exact_birth_year_match"
]
}
]
}
]
}
]
}
{
"search_term": "Robert Gabrial Mugabe",
"hits": [
{
"doc": {},
"match_types_details": [
{
"matching_name": "Robert Gabriel Mugabe",
"sources": [
"OFAC SDN List"
],
"aml_types": [
"sanction"
],
"name_matches": [
{
"query_term": "robert",
"match_types": [
"exact_match"
]
},
{
"query_term": "gabrial",
"match_types": [
"edit_distance"
]
},
{
"query_term": "mugabe",
"match_types": [
"exact_match"
]
}
],
"secondary_matches": [
{
"query_term": "1924",
"match_types": [
"exact_birth_year_match"
]
}
]
},
{
"matching_name": "Robert Mugabe",
"sources": [
"ComplyAdvantage Adverse Media"
],
"aml_types": [
"adverse-media"
],
"name_matches": [
{
"query_term": "robert",
"match_types": [
"exact_match"
]
},
{
"query_term": "gabrial",
"match_types": [
"name_variations_removal"
]
},
{
"query_term": "mugabe",
"match_types": [
"exact_match"
]
}
],
"secondary_matches": [
{
"query_term": "1924",
"match_types": [
"exact_birth_year_match"
]
}
]
}
]
}
]
}
The match_types_details field contains a detailed breakdown of why a hit occured. For every name you matched on an entity, it will give you how each term from your search matched it, as well other information about that name. The fields for each match_types document in the list are:
matching_name
A name (equivalently AKA) you matched against
sources
The list of sources (e.g. OFAC SDN List) associated with the matching name
aml_types
The list of aml types (e.g. sanction) associated with the matching_name
name_matches
A breakdown of how each word in the search term matched the matching_name. The fields for every element in the list are:
- query_term
A cleaned word from your search term
- match_types
A list of ways that word matched. Possible match types are:
exact_match The word exactly matched a word in the matching_name
edit_distance The word was a single insertion/deletion/replacement/transposition away from a word in the matching_name
phonetic Phonetic token(s) of word matched the phonetic token(s) of a word in the matching_name
equivalent_name An equivalent name matched a word in the matching_name
word_to_initial The first letter of the word matched an initial in the matching_name
initial_to_word Initial matched the first letter of a word in the matching name
removed_spaces Concatenating this word with others in the search_term matched a word in the matching_name
word_to_digit The digit representation of this number occurs in the matching name
digit_to_word The word representation of this number occurs in the matching name
name_variations_removal The word was allowed to be missing from hit as part of name_variations behaviour
removed_personal_title The word was identified as a personal title and was stripped from the search term
removed_personal_suffix The word was identified as a personal suffix and was stripped from the search term
removed_organisation_prefix The word was identified as an organisation prefix and was stripped from the search term
removed_organisation_suffix The word was identified as a organisation suffix and was stripped from the search term
removed_clerical_mark The word was identified as a clerical mark and was stripped from the search term
secondary_matches
A breakdown of how other information (e.g. birth_year) supplied with a search matched the matching_name
- query_term
A secondary piece of information from your query
- match_types
A list of ways that term matched. Possible match types are:
exact_birth_year_match The supplied birth_year matched exactly with one attached to the entity
fuzzy_birth_year_match The supplied birth_year fell within the allowed range of one attached to the entity
Retrieving Searches
GET /Searches
Example Request (showing sorting and pagination)
const url = 'https://api.complyadvantage.com/searches?api_key=YOURAPIKEY&per_page=20&page=2&sort_by=id&sort_dir=asc'
axios.get(url)
.then((response) => {
console.log(response.data);
});
url = "https://api.complyadvantage.com/searches?api_key=YOURAPIKEY&per_page=20&page=2&sort_by=id&sort_dir=asc"
response = requests.get(url)
print(response.json())
Example Request (showing filtering)
const url = 'https://api.complyadvantage.com/searches?api_key=YOURAPIKEY&match_status=potential_match,true_positive&assignee_id=15&created_at_from=2015-03-31'
axios.get(url)
.then((response) => {
console.log(response.data);
});
url = "https://api.complyadvantage.com/searches?api_key=YOURAPIKEY&match_status=potential_match,true_positive&assignee_id=15&created_at_from=2015-03-31"
response = requests.get(url)
print(response.json())
Example Response
{
"content": {
"data": [
{
"id": 20,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 14,
"filters": {
"exact_match": false,
"fuzziness": 1
},
"match_status": "potential_match",
"risk_level": "medium",
"search_term": "Hugo Jinkis",
"total_hits": 1,
"updated_at": "2015-06-16 09:58:22",
"created_at": "2015-06-11 15:02:30"
},
{
"id": 18,
"ref": "1495711341-TuJJDF9s",
"searcher_id": 1,
"assignee_id": 1,
"filters": {
"exact_match": false,
"fuzziness": 1
},
"match_status": "potential_match",
"risk_level": "high",
"search_term": "Vladimir Putin",
"total_hits": 7,
"updated_at": "2015-06-16 17:12:50",
"created_at": "2015-06-11 14:45:11"
}
]
},
"status": "success"
}
{
"content": {
"data": [
{
"id": 20,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 14,
"filters": {
"exact_match": false,
"fuzziness": 1
},
"match_status": "potential_match",
"risk_level": "medium",
"search_term": "Hugo Jinkis",
"total_hits": 1,
"updated_at": "2015-06-16 09:58:22",
"created_at": "2015-06-11 15:02:30"
},
{
"id": 18,
"ref": "1495711341-TuJJDF9s",
"searcher_id": 1,
"assignee_id": 1,
"filters": {
"exact_match": false,
"fuzziness": 1
},
"match_status": "potential_match",
"risk_level": "high",
"search_term": "Vladimir Putin",
"total_hits": 7,
"updated_at": "2015-06-16 17:12:50",
"created_at": "2015-06-11 14:45:11"
}
]
},
"status": "success"
}
{
"content": {
"data": [
{
"id": 20,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 14,
"filters": {
"exact_match": false,
"fuzziness": 1
},
"match_status": "potential_match",
"risk_level": "medium",
"search_term": "Hugo Jinkis",
"total_hits": 1,
"updated_at": "2015-06-16 09:58:22",
"created_at": "2015-06-11 15:02:30"
},
{
"id": 18,
"ref": "1495711341-TuJJDF9s",
"searcher_id": 1,
"assignee_id": 1,
"filters": {
"exact_match": false,
"fuzziness": 1
},
"match_status": "potential_match",
"risk_level": "high",
"search_term": "Vladimir Putin",
"total_hits": 7,
"updated_at": "2015-06-16 17:12:50",
"created_at": "2015-06-11 14:45:11"
}
]
},
"status": "success"
}
Retrieve the previous searches on your account. This includes many options for pagination and filtering results.
Filtering parameters
The following parameters can be applied to the querystring to filter the data returned.
| FIELD | DESCRIPTION |
|---|---|
assignee_id |
Show searches assigned to a specific user |
searcher_id |
Show searches performed by a specific user |
risk_level |
Show searches where the risk level is one of the specified options: ('low', 'medium', 'high', 'unknown'). Use commas to separate multiple options, eg &risk_level=medium,high |
submitted_term |
Show searches where the term is unsanitised and includes symbols and punctuation marks |
match_status |
Show searches where the match_status is one of the specified options: ('no_match', 'false_positive', 'potential_match', 'true_positive','unknown'). Use commas to separate multiple options, eg &match_status=potential_match,true_positive |
search_term |
Searches that match search term (3 characters min) |
created_at_from |
Searches made from date (yyyy-mm-dd) |
created_at_to |
Searches made to date (yyyy-mm-dd) |
tags |
Searches registered against given tags, comma separated represented as 'name:value', eg 'internal_ref:1234' or internal_ref:1234,t_type:custom' |
monitored |
Searches with a specific monitored status, eg. suspended for suspended searches, un-suspended for actively monitored searches and false for searches which are not monitored |
Sorting parameters
The following parameters can be applied to the querystring to sort the data returned.
| FIELD | DESCRIPTION |
|---|---|
sort_by |
One of 'id', 'created_at', 'updated_at', 'assignee_id', 'searcher_id' |
sort_dir |
One of 'ASC, 'DESC' |
Pagination parameters
The following parameters can be applied to the querystring to paginate the data returned.
| FIELD | DESCRIPTION |
|---|---|
per_page |
Number of searches to return per "page" (integer, max 100) |
page |
Which page to fetch (integer) |
GET /searches/[id]
Example Request
const url = 'https://api.complyadvantage.com/searches/46?api_key=YOURAPIKEY&share_url=1'
axios.get(url)
.then((response) => {
console.log(response.data);
});
url = "https://api.complyadvantage.com/searches/46?api_key=YOURAPIKEY&share_url=1"
response = requests.get(url)
print(response.json())
Example Response
{
"content": {
"data": {
"id": 20,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 14,
"search_profile": {
"name": "My USA Profile 1",
"slug": "my-usa-profile-1"
},
"filters": {
"exact_match": false,
"fuzziness": 1
},
"match_status": "potential_match",
"risk_level": "medium",
"search_term": "Hugo Jinkis",
"total_hits": 1,
"updated_at": "2015-06-16 09:58:22",
"created_at": "2015-06-11 15:02:30",
"share_url": "http://app.complyadvantage.com/public/search/1496748100-l9qHqbVF/64a6114f299b"
}
},
"status": "success"
}
{
"content": {
"data": {
"id": 20,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 14,
"search_profile": {
"name": "My USA Profile 1",
"slug": "my-usa-profile-1"
},
"filters": {
"exact_match": false,
"fuzziness": 1
},
"match_status": "potential_match",
"risk_level": "medium",
"search_term": "Hugo Jinkis",
"total_hits": 1,
"updated_at": "2015-06-16 09:58:22",
"created_at": "2015-06-11 15:02:30",
"share_url": "http://app.complyadvantage.com/public/search/1496748100-l9qHqbVF/64a6114f299b"
}
},
"status": "success"
}
{
"content": {
"data": {
"id": 20,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 14,
"search_profile": {
"name": "My USA Profile 1",
"slug": "my-usa-profile-1"
},
"filters": {
"exact_match": false,
"fuzziness": 1
},
"match_status": "potential_match",
"risk_level": "medium",
"search_term": "Hugo Jinkis",
"total_hits": 1,
"updated_at": "2015-06-16 09:58:22",
"created_at": "2015-06-11 15:02:30",
"share_url": "http://app.complyadvantage.com/public/search/1496748100-l9qHqbVF/64a6114f299b"
}
},
"status": "success"
}
Retrieve a specific search on your account. For monitored searches, the original result will be updated with the latest results from the monitor runs.
URL PARAMETERS
| FIELD | DESCRIPTION |
|---|---|
id |
Either the numeric search ID, or the search REF |
QUERY STRING PARAMETERS
| FIELD | DESCRIPTION |
|---|---|
share_url |
1 or 0 - include a shareable URL in response. |
GET /searches/[id]/certificate
Example Request
const url = 'https://api.complyadvantage.com/searches/46/certificate?api_key=YOURAPIKEY'
axios.get(url)
.then((response) => {
console.log(response.data);
});
url = "https://api.complyadvantage.com/searches/46/certificate?api_key=YOURAPIKEY"
response = requests.get(url)
print(response.json())
Retrieve a specific search certificate as a PDF file on your account.
URL PARAMETERS
| FIELD | DESCRIPTION |
|---|---|
id |
Either the numeric search ID, or the search REF |
RESPONSE
The response is a binary content stream with a content type of application/pdf.
GET /searches/[id]/details
Example Request
const url = 'https://api.complyadvantage.com/searches/46/details?api_key=YOURAPIKEY&share_url=1'
axios.get(url)
.then((response) => {
console.log(response.data);
});
url = "https://api.complyadvantage.com/searches/46/details?api_key=YOURAPIKEY&share_url=1"
response = requests.get(url)
print(response.json())
Example Response
{
"content": {
"data": {
"id": 20,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 14,
"search_profile": {
"name": "My USA Profile 1",
"slug": "my-usa-profile-1"
},
"filters": {
"exact_match": false,
"fuzziness": 1,
"content": {
"data": {
"id": 20,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 14,
"search_profile": {
"name": "My USA Profile 1",
"slug": "my-usa-profile-1"
},
"filters": {
"exact_match": false,
"fuzziness": 1
},
"match_status": "true_positive",
"risk_level": "medium",
"search_term": "Hugo Jinkis",
"total_hits": 1,
"updated_at": "2015-06-18 09:35:06",
"created_at": "2015-06-11 15:02:30",
"searcher": {
"id": 1,
"email": "teamadmin@example.com",
"name": "Team Administrator",
"phone": null,
"created_at": "2015-06-11 12:05:14"
},
"assignee": {
"id": 14,
"email": "walton41@example.com",
"name": "Jessyca Sporer",
"phone": "1-628-245-5554x7640",
"created_at": "2015-06-11 12:05:16"
},
"hits": [
{
"doc": {
"aka": [],
"associates": [
{
"association": "Business Partner",
"name": "Mariano Jinkis"
}
],
"entity_type": "person",
"fields": [
{
"name": "Countries",
"tag": "country_names",
"value": "Argentina"
},
{
"locale": "en",
"name": "Description",
"priority": "override",
"source": "complyadvantage",
"tag": "description",
"value": "Controlling principal of Full Play Group S.A., a sports marketing business based in Argentina, and its affiliates."
},
{
"locale": "en",
"name": "Crime",
"priority": "override",
"source": "complyadvantage",
"tag": "crime",
"value": "Hugo Jinkis was one of the nine FIFA officials and five corporate executives indicted for racketeering conspiracy and corruption in May 2015."
}
],
"first_name": "Hugo",
"id": "BYKUB1NQ8RPEC7T",
"last_name": "Jinkis",
"last_updated_utc": "2015-06-03T18:05:28Z",
"name": "Hugo Jinkis",
"media": [],
"sources": [
"complyadvantage"
],
"types": []
},
"match_types": [
"name_exact"
],
"score": 1.001
}
],
"share_url": "http://app.complyadvantage.com/public/search/1495711341-Tu51KL9s/64a6114f299b"
}
},
"status": "success"
}
},
"match_status": "potential_match",
"risk_level": "medium",
"search_term": "Hugo Jinkis",
"total_hits": 1,
"updated_at": "2015-06-16 09:58:22",
"created_at": "2015-06-11 15:02:30",
"share_url": "http://app.complyadvantage.com/public/search/1495711341-Tu51KL9s/64a6114f299b"
},
"status": "success"
}
{
"content": {
"data": {
"id": 20,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 14,
"search_profile": {
"name": "My USA Profile 1",
"slug": "my-usa-profile-1"
},
"filters": {
"exact_match": false,
"fuzziness": 1,
"content": {
"data": {
"id": 20,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 14,
"search_profile": {
"name": "My USA Profile 1",
"slug": "my-usa-profile-1"
},
"filters": {
"exact_match": false,
"fuzziness": 1
},
"match_status": "true_positive",
"risk_level": "medium",
"search_term": "Hugo Jinkis",
"total_hits": 1,
"updated_at": "2015-06-18 09:35:06",
"created_at": "2015-06-11 15:02:30",
"searcher": {
"id": 1,
"email": "teamadmin@example.com",
"name": "Team Administrator",
"phone": null,
"created_at": "2015-06-11 12:05:14"
},
"assignee": {
"id": 14,
"email": "walton41@example.com",
"name": "Jessyca Sporer",
"phone": "1-628-245-5554x7640",
"created_at": "2015-06-11 12:05:16"
},
"hits": [
{
"doc": {
"aka": [],
"associates": [
{
"association": "Business Partner",
"name": "Mariano Jinkis"
}
],
"entity_type": "person",
"fields": [
{
"name": "Countries",
"tag": "country_names",
"value": "Argentina"
},
{
"locale": "en",
"name": "Description",
"priority": "override",
"source": "complyadvantage",
"tag": "description",
"value": "Controlling principal of Full Play Group S.A., a sports marketing business based in Argentina, and its affiliates."
},
{
"locale": "en",
"name": "Crime",
"priority": "override",
"source": "complyadvantage",
"tag": "crime",
"value": "Hugo Jinkis was one of the nine FIFA officials and five corporate executives indicted for racketeering conspiracy and corruption in May 2015."
}
],
"first_name": "Hugo",
"id": "BYKUB1NQ8RPEC7T",
"last_name": "Jinkis",
"last_updated_utc": "2015-06-03T18:05:28Z",
"name": "Hugo Jinkis",
"media": [],
"sources": [
"complyadvantage"
],
"types": []
},
"match_types": [
"name_exact"
],
"score": 1.001
}
],
"share_url": "http://app.complyadvantage.com/public/search/1495711341-Tu51KL9s/64a6114f299b"
}
},
"status": "success"
}
},
"match_status": "potential_match",
"risk_level": "medium",
"search_term": "Hugo Jinkis",
"total_hits": 1,
"updated_at": "2015-06-16 09:58:22",
"created_at": "2015-06-11 15:02:30",
"share_url": "http://app.complyadvantage.com/public/search/1495711341-Tu51KL9s/64a6114f299b"
},
"status": "success"
}
{
"content": {
"data": {
"id": 20,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 14,
"search_profile": {
"name": "My USA Profile 1",
"slug": "my-usa-profile-1"
},
"filters": {
"exact_match": false,
"fuzziness": 1,
"content": {
"data": {
"id": 20,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 14,
"search_profile": {
"name": "My USA Profile 1",
"slug": "my-usa-profile-1"
},
"filters": {
"exact_match": false,
"fuzziness": 1
},
"match_status": "true_positive",
"risk_level": "medium",
"search_term": "Hugo Jinkis",
"total_hits": 1,
"updated_at": "2015-06-18 09:35:06",
"created_at": "2015-06-11 15:02:30",
"searcher": {
"id": 1,
"email": "teamadmin@example.com",
"name": "Team Administrator",
"phone": null,
"created_at": "2015-06-11 12:05:14"
},
"assignee": {
"id": 14,
"email": "walton41@example.com",
"name": "Jessyca Sporer",
"phone": "1-628-245-5554x7640",
"created_at": "2015-06-11 12:05:16"
},
"hits": [
{
"doc": {
"aka": [],
"associates": [
{
"association": "Business Partner",
"name": "Mariano Jinkis"
}
],
"entity_type": "person",
"fields": [
{
"name": "Countries",
"tag": "country_names",
"value": "Argentina"
},
{
"locale": "en",
"name": "Description",
"priority": "override",
"source": "complyadvantage",
"tag": "description",
"value": "Controlling principal of Full Play Group S.A., a sports marketing business based in Argentina, and its affiliates."
},
{
"locale": "en",
"name": "Crime",
"priority": "override",
"source": "complyadvantage",
"tag": "crime",
"value": "Hugo Jinkis was one of the nine FIFA officials and five corporate executives indicted for racketeering conspiracy and corruption in May 2015."
}
],
"first_name": "Hugo",
"id": "BYKUB1NQ8RPEC7T",
"last_name": "Jinkis",
"last_updated_utc": "2015-06-03T18:05:28Z",
"name": "Hugo Jinkis",
"media": [],
"sources": [
"complyadvantage"
],
"types": []
},
"match_types": [
"name_exact"
],
"score": 1.001
}
],
"share_url": "http://app.complyadvantage.com/public/search/1495711341-Tu51KL9s/64a6114f299b"
}
},
"status": "success"
}
},
"match_status": "potential_match",
"risk_level": "medium",
"search_term": "Hugo Jinkis",
"total_hits": 1,
"updated_at": "2015-06-16 09:58:22",
"created_at": "2015-06-11 15:02:30",
"share_url": "http://app.complyadvantage.com/public/search/1495711341-Tu51KL9s/64a6114f299b"
},
"status": "success"
}
Retrieve the full details and results of a specific search on your account.
URL PARAMETERS
| FIELD | DESCRIPTION |
|---|---|
id |
Either the numeric search ID, or the search REF |
QUERY STRING PARAMETERS
| FIELD | DESCRIPTION |
|---|---|
share_url |
1 or 0 - include a shareable URL in response. |
Updating Searches
PATCH /searches/[id]
Example Request
const url = 'https://api.complyadvantage.com/searches/46?api_key=YOURAPIKEY'
axios.patch(url, {
"match_status": "false_positive",
"risk_level": "low",
"assignee_id": 123,
"tags": {
"MyTagName": "MyTagValue"
}
})
.then((response) => {
console.log(response.data);
});
url = "https://api.complyadvantage.com/searches/46?api_key=YOURAPIKEY"
response = requests.patch(url, data = {
"match_status": "false_positive",
"risk_level": "low",
"assignee_id": 123,
"tags": {
"MyTagName": "MyTagValue"
}
})
print(response.json())
{
"match_status": "false_positive",
"risk_level": "low",
"assignee_id": 123,
"tags": {
"MyTagName": "MyTagValue"
}
}
Example Response - this is the overview of the newly updated search
{
"content": {
"data": {
"id": 20,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 123,
"tags": {
"MyTagName": "MyTagValue"
},
"labels": [
{
"type": "tag",
"name": "MyTagName",
"value": "MyTagValue"
}
],
"search_profile": {
"name": "My USA Profile 1",
"slug": "my-usa-profile-1"
},
"filters": {
"exact_match": false,
"fuzziness": 1
},
"match_status": "false_positive",
"risk_level": "low",
"search_term": "Hugo Jinkis",
"total_hits": 1,
"updated_at": "2015-06-18 09:35:06",
"created_at": "2015-06-11 15:02:30"
}
},
"status": "success"
}
{
"content": {
"data": {
"id": 20,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 123,
"tags": {
"MyTagName": "MyTagValue"
},
"labels": [
{
"type": "tag",
"name": "MyTagName",
"value": "MyTagValue"
}
],
"search_profile": {
"name": "My USA Profile 1",
"slug": "my-usa-profile-1"
},
"filters": {
"exact_match": false,
"fuzziness": 1
},
"match_status": "false_positive",
"risk_level": "low",
"search_term": "Hugo Jinkis",
"total_hits": 1,
"updated_at": "2015-06-18 09:35:06",
"created_at": "2015-06-11 15:02:30"
}
},
"status": "success"
}
{
"content": {
"data": {
"id": 20,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 123,
"tags": {
"MyTagName": "MyTagValue"
},
"labels": [
{
"type": "tag",
"name": "MyTagName",
"value": "MyTagValue"
}
],
"search_profile": {
"name": "My USA Profile 1",
"slug": "my-usa-profile-1"
},
"filters": {
"exact_match": false,
"fuzziness": 1
},
"match_status": "false_positive",
"risk_level": "low",
"search_term": "Hugo Jinkis",
"total_hits": 1,
"updated_at": "2015-06-18 09:35:06",
"created_at": "2015-06-11 15:02:30"
}
},
"status": "success"
}
Update the assignee, status or risk level of a search.
URL PARAMETERS
| FIELD | DESCRIPTION |
|---|---|
id |
Either the numeric search ID, or the search REF |
JSON PATCH PARAMETERS
One or more of the following fields can be specified in the PATCH request.
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
match_status |
String | One of 'unknown', 'no_match', 'potential_match', 'false_positive', 'true_positive', 'true_positive_approve', 'true_positive_reject' |
risk_level |
String | One of 'low', 'medium', 'high', 'unknown' |
assignee_id |
Integer | The ID of the user to whom the case should be assigned |
tags |
Object | Object of name => value pairs ( name must be string ) |
PATCH /searches/[id]/entities
Example Request
const url = 'https://api.complyadvantage.com/searches/46/entities?api_key=YOURAPIKEY'
axios.patch(url, {
"entities": [
"FRDG8ZC7VURPKP0",
"FRDG8ZC7VURPKP3"
],
"match_status": "false_positive",
"risk_level": "low",
"is_whitelisted": true
})
.then((response) => {
console.log(response.data);
});
url = "https://api.complyadvantage.com/searches/46/entities?api_key=YOURAPIKEY"
response = requests.patch(url, data = {
"entities": [
"FRDG8ZC7VURPKP0",
"FRDG8ZC7VURPKP3"
],
"match_status": "false_positive",
"risk_level": "low",
"is_whitelisted": true
})
print(response.json())
{
"entities": [
"FRDG8ZC7VURPKP0",
"FRDG8ZC7VURPKP3"
],
"match_status": "false_positive",
"risk_level": "low",
"is_whitelisted": true
}
Example Response - this is the overview of the newly updated search
{
"content": {
"data": {
"id": 46,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 1,
"filters": {
"entity_type": "person",
"types": [
"sanction",
"warning"
],
"birth_year": "1924",
"passport": "AD10095",
"exact_match": false,
"fuzziness": 0.6
},
"match_status": "potential_match",
"risk_level": "unknown",
"search_term": "Robert Mugabe",
"total_hits": 1,
"updated_at": "2015-06-18 16:52:42",
"created_at": "2015-06-18 16:52:42",
"tags": {
"name": "value"
},
"labels": [
{
"type": "tag",
"name": "name",
"value": "value"
}
],
"hits": [
{
"doc": {
"id": "FRDG8ZC7VURPKP0"
},
"match_status": "false_positive",
"is_whitelisted": true,
"risk_level": "high",
"match_types": [
"name_exact",
"year_of_birth"
],
"score": 3.511
},
{
"doc": {
"id": "FRDG8ZC7VURPKP3"
},
"match_status": "false_positive",
"is_whitelisted": true,
"risk_level": "high",
"match_types": [
"name_exact",
"year_of_birth"
],
"score": 3.511
}
],
"share_url": "http://app.complyadvantage.com/public/search/1496748100-l9qHqbVF/64a6114f299b"
}
},
"status": "success"
}
{
"content": {
"data": {
"id": 46,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 1,
"filters": {
"entity_type": "person",
"types": [
"sanction",
"warning"
],
"birth_year": "1924",
"passport": "AD10095",
"exact_match": false,
"fuzziness": 0.6
},
"match_status": "potential_match",
"risk_level": "unknown",
"search_term": "Robert Mugabe",
"total_hits": 1,
"updated_at": "2015-06-18 16:52:42",
"created_at": "2015-06-18 16:52:42",
"tags": {
"name": "value"
},
"labels": [
{
"type": "tag",
"name": "name",
"value": "value"
}
],
"hits": [
{
"doc": {
"id": "FRDG8ZC7VURPKP0"
},
"match_status": "false_positive",
"is_whitelisted": true,
"risk_level": "high",
"match_types": [
"name_exact",
"year_of_birth"
],
"score": 3.511
},
{
"doc": {
"id": "FRDG8ZC7VURPKP3"
},
"match_status": "false_positive",
"is_whitelisted": true,
"risk_level": "high",
"match_types": [
"name_exact",
"year_of_birth"
],
"score": 3.511
}
],
"share_url": "http://app.complyadvantage.com/public/search/1496748100-l9qHqbVF/64a6114f299b"
}
},
"status": "success"
}
{
"content": {
"data": {
"id": 46,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 1,
"filters": {
"entity_type": "person",
"types": [
"sanction",
"warning"
],
"birth_year": "1924",
"passport": "AD10095",
"exact_match": false,
"fuzziness": 0.6
},
"match_status": "potential_match",
"risk_level": "unknown",
"search_term": "Robert Mugabe",
"total_hits": 1,
"updated_at": "2015-06-18 16:52:42",
"created_at": "2015-06-18 16:52:42",
"tags": {
"name": "value"
},
"labels": [
{
"type": "tag",
"name": "name",
"value": "value"
}
],
"hits": [
{
"doc": {
"id": "FRDG8ZC7VURPKP0"
},
"match_status": "false_positive",
"is_whitelisted": true,
"risk_level": "high",
"match_types": [
"name_exact",
"year_of_birth"
],
"score": 3.511
},
{
"doc": {
"id": "FRDG8ZC7VURPKP3"
},
"match_status": "false_positive",
"is_whitelisted": true,
"risk_level": "high",
"match_types": [
"name_exact",
"year_of_birth"
],
"score": 3.511
}
],
"share_url": "http://app.complyadvantage.com/public/search/1496748100-l9qHqbVF/64a6114f299b"
}
},
"status": "success"
}
Update the match-status of entities within a search result
URL PARAMETERS
| FIELD | DESCRIPTION |
|---|---|
id |
Either the numeric search ID, or the search REF |
JSON PATCH PARAMETERS
One or more of the following fields can be specified in the PATCH request.
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
entities |
Array | Array of entity ids to be updated (list of strings) |
match_status |
String | One of 'no_match', 'false_positive', 'potential_match', 'true_positive','unknown' |
risk_level |
String | One of 'low', 'medium', 'high', 'unknown' |
is_whitelisted |
Boolean | true or false |
Monitored Searches
GET /searches/[id]/monitors
Example Request
const url = 'https://api.complyadvantage.com/searches/1/monitors?api_key=YOURAPIKEY'
axios.get(url)
.then((response) => {
console.log(response.data);
});
url = "https://api.complyadvantage.com/searches/1/monitors?api_key=YOURAPIKEY"
response = requests.get(url)
print(response.json())
Example Response - this shows the detail of the monitored search being returned:
{
"content": {
"search_id": 1,
"ref": "1495711341-Tu51KL9s",
"is_monitored": true,
"monitors": [
{
"monitored_by": 1,
"updated_at": "2015-06-18 09:35:06",
"created_at": "2015-06-11 15:02:30"
}
]
},
"status": "success"
}
{
"content": {
"search_id": 1,
"ref": "1495711341-Tu51KL9s",
"is_monitored": true,
"monitors": [
{
"monitored_by": 1,
"updated_at": "2015-06-18 09:35:06",
"created_at": "2015-06-11 15:02:30"
}
]
},
"status": "success"
}
{
"content": {
"search_id": 1,
"ref": "1495711341-Tu51KL9s",
"is_monitored": true,
"monitors": [
{
"monitored_by": 1,
"updated_at": "2015-06-18 09:35:06",
"created_at": "2015-06-11 15:02:30"
}
]
},
"status": "success"
}
Retrieve the information on the monitored search.
URL PARAMETERS
| FIELD | DESCRIPTION |
|---|---|
id |
Either the numeric search ID, or the search REF |
PATCH /searches/[id]/monitors
Request example for disabling monitor on search
const url = 'https://api.complyadvantage.com/searches/1/monitors?api_key=YOURAPIKEY'
axios.patch(url, {
"is_monitored": false,
})
.then((response) => {
console.log(response.data);
});
url = "https://api.complyadvantage.com/searches/1/monitors?api_key=YOURAPIKEY"
response = requests.patch(url, data = {
"is_monitored": False
})
print(response.json())
Response example for monitor disable
{
"content": {
"search_id": 1,
"ref": "1495711341-Tu51KL9s",
"is_monitored": false,
"monitors": []
},
"status": "success"
}
{
"content": {
"search_id": 1,
"ref": "1495711341-Tu51KL9s",
"is_monitored": false,
"monitors": []
},
"status": "success"
}
{
"content": {
"search_id": 1,
"ref": "1495711341-Tu51KL9s",
"is_monitored": false,
"monitors": []
},
"status": "success"
}
Update the search monitors.
URL PARAMETERS
| FIELD | DESCRIPTION |
|---|---|
id |
Either the numeric search ID, or the search REF |
JSON POST PARAMETERS
One or more of the following fields can be specified in the PATCH request.
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
is_monitored |
Boolean | Start on true and stop on false. For monitored searches, the original search will be updated with the latest results from monitor runs. |
monitored_by (optional) |
Integer | The ID of the user who will start/stop monitoring (please note if monitored_by is not provided all users will be affected ) |
GET /searches/[id]/monitor/differences
Example Request
const url = 'https://api.complyadvantage.com/searches/1/monitor/differences?api_key=YOURAPIKEY&date=2018-07-02'
axios.get(url)
.then((response) => {
console.log(response.data);
});
url = "https://api.complyadvantage.com/searches/1/monitor/differences?api_key=YOURAPIKEY&date=2018-07-02"
response = requests.get(url)
print(response.json())
Example Response - illustrates the return data from the request:
{
"content": [
{
"action": "added|removed|updated",
"name": "string",
"entity_id": "string",
"listing_types": [],
"sources": [],
"changes": {
"listing_types": {
"removed": [],
"added": []
},
"sources": {
"removed": [],
"added": []
}
}
}
],
"status": "success"
}
{
"content": [
{
"action": "added|removed|updated",
"name": "string",
"entity_id": "string",
"listing_types": [],
"sources": [],
"changes": {
"listing_types": {
"removed": [],
"added": []
},
"sources": {
"removed": [],
"added": []
}
}
}
],
"status": "success"
}
{
"content": [
{
"action": "added|removed|updated",
"name": "string",
"entity_id": "string",
"listing_types": [],
"sources": [],
"changes": {
"listing_types": {
"removed": [],
"added": []
},
"sources": {
"removed": [],
"added": []
}
}
}
],
"status": "success"
}
Retrieve the differences on the monitored search on a specific date.
URL PARAMETERS
| FIELD | DESCRIPTION |
|---|---|
id |
Either the numeric search ID, or the search REF |
date (optional) |
The reference date (format: yyyy-mm-dd); if missing, the current day will be used |
Other Endpoints
GET /users
Example request
const url = 'https://api.complyadvantage.com/users?api_key=YOURAPIKEY'
axios.get(url)
.then((response) => {
console.log(response.data);
});
url = "https://api.complyadvantage.com/users?api_key=YOURAPIKEY"
response = requests.get(url)
print(response.json())
Example Response - shows the list of users on the specified account being returned:
{
"content": {
"data": [
{
"id": 1,
"email": "teamadmin@example.com",
"name": "Team Administrator",
"phone": null,
"updated_at": "2015-06-15 09:15:12",
"created_at": "2015-06-11 12:05:14"
},
{
"id": 14,
"email": "walton41@example.com",
"name": "Jessyca Sporer",
"phone": "1-628-245-5554x7640",
"updated_at": "2015-06-11 12:05:16",
"created_at": "2015-06-11 12:05:16"
},
{
"id": 15,
"email": "autumn.ankunding@example.net",
"name": "Dr. Niko Eichmann DVM",
"phone": "(232)055-6006",
"updated_at": "2015-06-11 12:05:16",
"created_at": "2015-06-11 12:05:16"
}
]
},
"status": "success"
}
{
"content": {
"data": [
{
"id": 1,
"email": "teamadmin@example.com",
"name": "Team Administrator",
"phone": null,
"updated_at": "2015-06-15 09:15:12",
"created_at": "2015-06-11 12:05:14"
},
{
"id": 14,
"email": "walton41@example.com",
"name": "Jessyca Sporer",
"phone": "1-628-245-5554x7640",
"updated_at": "2015-06-11 12:05:16",
"created_at": "2015-06-11 12:05:16"
},
{
"id": 15,
"email": "autumn.ankunding@example.net",
"name": "Dr. Niko Eichmann DVM",
"phone": "(232)055-6006",
"updated_at": "2015-06-11 12:05:16",
"created_at": "2015-06-11 12:05:16"
}
]
},
"status": "success"
}
{
"content": {
"data": [
{
"id": 1,
"email": "teamadmin@example.com",
"name": "Team Administrator",
"phone": null,
"updated_at": "2015-06-15 09:15:12",
"created_at": "2015-06-11 12:05:14"
},
{
"id": 14,
"email": "walton41@example.com",
"name": "Jessyca Sporer",
"phone": "1-628-245-5554x7640",
"updated_at": "2015-06-11 12:05:16",
"created_at": "2015-06-11 12:05:16"
},
{
"id": 15,
"email": "autumn.ankunding@example.net",
"name": "Dr. Niko Eichmann DVM",
"phone": "(232)055-6006",
"updated_at": "2015-06-11 12:05:16",
"created_at": "2015-06-11 12:05:16"
}
]
},
"status": "success"
}
Retrieves all the users in your account
Deprecated Endpoints
On the 15-June-2018 we announced the deprecation of the following endpoints.
After 2 years (so 15-June-2020) these endpoints will be replaced with a status code response of '410 - Gone'
| ENDPOINT | DESCRIPTION | REPLACEMENT |
|---|---|---|
GET /entity/[entity_id] |
Retrieve an entity from the ComplyAdvantage database | Not supported |
POST /entity/search |
Create a new search | POST /searches |
PATCH /searches/[id]/entity/[eid] |
Update the match-status of an entity within a search result | PATCH /searches/[id] |
GET /entity/[entity_id]
Example Request
const url = 'https://api.complyadvantage.com/entity/GRV6TUVJXJQ0P06?api_key=YOURAPIKEY'
axios.get(url)
.then((response) => {
console.log(response.data);
});
url = "https://api.complyadvantage.com/entity/GRV6TUVJXJQ0P06?api_key=YOURAPIKEY"
response = requests.get(url)
print(response.json())
Example Response
{
"content": {
"aka": [
{
"name": "Robert Mugabe",
"first_name": "Robert",
"last_name": "Mugabe"
}
],
"entity_type": "person",
"fields": [
{
"tag": "date_of_birth",
"name": "Date of Birth",
"value": "1924-02-21",
"source": "example-1-list"
},
{
"name": "Position",
"source": "example-2-list",
"value": "President"
},
{
"name": "Passport",
"source": "example-2-list",
"value": "AD001095"
},
{
"name": "Other Information",
"source": "example-2-list",
"value": "Head of Government."
},
{
"name": "Regime",
"source": "example-2-list",
"value": "Zimbabwe"
}
],
"id": "GRV6TUVJXJQ0P06",
"last_updated_utc": "2014-11-13T15:29:30",
"name": "Robert Gabriel Mugabe",
"media": [
{
"date": "2018-09-17T00:00:00Z",
"snippet": "- Mugabe's son-in-law under probe PRESIDENT Emmerson Mnangagwa's ...",
"title": "Mugabe's son-in-law under probe – The Zimbabwe Mail",
"url": "https://www.thezimbabwemail.com/law-crime/mugabes-son-in-law-under-probe/"
}
],
"first_name": "Robert",
"middle_names": "Gabriel",
"last_name": "Mugabe",
"sources": [
"example-2-list"
],
"types": [
"sanction",
"pep"
]
},
"status": "success"
}
{
"content": {
"aka": [
{
"name": "Robert Mugabe",
"first_name": "Robert",
"last_name": "Mugabe"
}
],
"entity_type": "person",
"fields": [
{
"tag": "date_of_birth",
"name": "Date of Birth",
"value": "1924-02-21",
"source": "example-1-list"
},
{
"name": "Position",
"source": "example-2-list",
"value": "President"
},
{
"name": "Passport",
"source": "example-2-list",
"value": "AD001095"
},
{
"name": "Other Information",
"source": "example-2-list",
"value": "Head of Government."
},
{
"name": "Regime",
"source": "example-2-list",
"value": "Zimbabwe"
}
],
"id": "GRV6TUVJXJQ0P06",
"last_updated_utc": "2014-11-13T15:29:30",
"name": "Robert Gabriel Mugabe",
"media": [
{
"date": "2018-09-17T00:00:00Z",
"snippet": "- Mugabe's son-in-law under probe PRESIDENT Emmerson Mnangagwa's ...",
"title": "Mugabe's son-in-law under probe – The Zimbabwe Mail",
"url": "https://www.thezimbabwemail.com/law-crime/mugabes-son-in-law-under-probe/"
}
],
"first_name": "Robert",
"middle_names": "Gabriel",
"last_name": "Mugabe",
"sources": [
"example-2-list"
],
"types": [
"sanction",
"pep"
]
},
"status": "success"
}
{
"content": {
"aka": [
{
"name": "Robert Mugabe",
"first_name": "Robert",
"last_name": "Mugabe"
}
],
"entity_type": "person",
"fields": [
{
"tag": "date_of_birth",
"name": "Date of Birth",
"value": "1924-02-21",
"source": "example-1-list"
},
{
"name": "Position",
"source": "example-2-list",
"value": "President"
},
{
"name": "Passport",
"source": "example-2-list",
"value": "AD001095"
},
{
"name": "Other Information",
"source": "example-2-list",
"value": "Head of Government."
},
{
"name": "Regime",
"source": "example-2-list",
"value": "Zimbabwe"
}
],
"id": "GRV6TUVJXJQ0P06",
"last_updated_utc": "2014-11-13T15:29:30",
"name": "Robert Gabriel Mugabe",
"media": [
{
"date": "2018-09-17T00:00:00Z",
"snippet": "- Mugabe's son-in-law under probe PRESIDENT Emmerson Mnangagwa's ...",
"title": "Mugabe's son-in-law under probe – The Zimbabwe Mail",
"url": "https://www.thezimbabwemail.com/law-crime/mugabes-son-in-law-under-probe/"
}
],
"first_name": "Robert",
"middle_names": "Gabriel",
"last_name": "Mugabe",
"sources": [
"example-2-list"
],
"types": [
"sanction",
"pep"
]
},
"status": "success"
}
DEPRECATED
Retrieves a single entity referenced by the supplied Entity ID.
URL PARAMETERS
| FIELD | DESCRIPTION |
|---|---|
entity_id |
The alphanumeric ID of the entity within our database |
POST /entity/search
Example Request
const url = 'https://api.complyadvantage.com/entity/search?api_key=YOURAPIKEY'
axios.post(url, {
"names": [
"Robert Mugabe",
"Qari Sahab",
{
"last_name": "Mugabe"
},
{
"last_name": "Sahab"
}
],
"fuzziness": 0.6,
"offset": 0,
"limit": 10,
"filters": {
"types": [
"sanction",
"warning"
],
"birth_year": "1924"
}
})
.then((response) => {
console.log(response.data);
});
url = "https://api.complyadvantage.com/entity/search?api_key=YOURAPIKEY"
response = requests.post(url, data = {
"names": [
"Robert Mugabe",
"Qari Sahab",
{
"last_name": "Mugabe"
},
{
"last_name": "Sahab"
}
],
"fuzziness": 0.6,
"offset": 0,
"limit": 10,
"filters": {
"types": [
"sanction",
"warning"
],
"birth_year": "1924"
}
})
print(response.json())
Example Response
{
"content": {
"results": [
{
"hits": [
{
"score": 1.00047,
"match_types": [
"name_exact",
"year_of_birth"
],
"doc": "... JSON doc for entity ..."
},
{
"score": 0.10453,
"match_types": [
"aka_synonym"
],
"doc": "... JSON doc for entity ..."
}
],
"limit": 10,
"offset": 0,
"search_terms": "Robert Mugabe",
"total": 5
},
{
"hits": [
{
"score": 1.00047,
"match_types": [
"aka_exact"
],
"doc": "... JSON doc for entity ..."
},
{
"score": 0.10453,
"match_types": [
"fuzzy"
],
"doc": "... JSON doc for entity ..."
}
],
"limit": 10,
"offset": 0,
"search_terms": "Qari Sahab",
"total": 5
}
],
"search_count": 2
},
"status": "success"
}
{
"content": {
"results": [
{
"hits": [
{
"score": 1.00047,
"match_types": [
"name_exact",
"year_of_birth"
],
"doc": "... JSON doc for entity ..."
},
{
"score": 0.10453,
"match_types": [
"aka_synonym"
],
"doc": "... JSON doc for entity ..."
}
],
"limit": 10,
"offset": 0,
"search_terms": "Robert Mugabe",
"total": 5
},
{
"hits": [
{
"score": 1.00047,
"match_types": [
"aka_exact"
],
"doc": "... JSON doc for entity ..."
},
{
"score": 0.10453,
"match_types": [
"fuzzy"
],
"doc": "... JSON doc for entity ..."
}
],
"limit": 10,
"offset": 0,
"search_terms": "Qari Sahab",
"total": 5
}
],
"search_count": 2
},
"status": "success"
}
{
"content": {
"results": [
{
"hits": [
{
"score": 1.00047,
"match_types": [
"name_exact",
"year_of_birth"
],
"doc": "... JSON doc for entity ..."
},
{
"score": 0.10453,
"match_types": [
"aka_synonym"
],
"doc": "... JSON doc for entity ..."
}
],
"limit": 10,
"offset": 0,
"search_terms": "Robert Mugabe",
"total": 5
},
{
"hits": [
{
"score": 1.00047,
"match_types": [
"aka_exact"
],
"doc": "... JSON doc for entity ..."
},
{
"score": 0.10453,
"match_types": [
"fuzzy"
],
"doc": "... JSON doc for entity ..."
}
],
"limit": 10,
"offset": 0,
"search_terms": "Qari Sahab",
"total": 5
}
],
"search_count": 2
},
"status": "success"
}
DEPRECATED
Retrieves a list of entities specified according to JSON body criteria
JSON POST PARAMETERS
| OPTION | DESCRIPTION |
|---|---|
names |
Array of names to be checked (list of strings) |
fuzziness |
Fuzziness quotient from 0.0 to 1.0 inclusive decides the match fuzziness level from exact match (0.0) to loose (1.0). The default is a fuzzy match of 1.0. |
offset |
Retrieve results from a given offset |
limit |
Maximum number of results to retrieve per name. Used in conjunction with offset, allows you to "paginate" through search results. Default 10, max 100 |
filters |
A list of criteria by which the search can be restricted.
ALL PARAMETERS EXCEPT NAMES ARE OPTIONAL. |
When performing a search for one or more names, the response will contain a results array, with each object in this array corresponding to a search term.
Each of these search terms will contain a hits array. This array contains entity objects matching the search term. The format of the entity objects can be seen above in the "Entity Format" section.
Note that we include meta-data relating to the search results in the hit objects, including the following:
doc
This is the entity as referenced in the entity format section
score
The search results match and ranking is computed via a score that is included a part of the metadata. This score is not an absolute ranking of the document, and should only be used in the context of ordering search results, and give some relative indication of relevance.
match_type
Whenever we match against a document, we try to include some data as to what matched. Possible values are as follows:
name_exactmatched against the entity name exactlyname_synonymmatched against the entity name with a synonym, e.g. "Robert Mugabe" => "Bob Mugabe"aka_exactmatched against an entity AKA (also known as) entry exactlyaka_synonymmatched against an entity AKA with a synonym, e.g. "Robert Mugabe" => "Bob Mugabe"name_phoneticmatched against the entity name phoneticallyaka_phoneticmatched against an entity AKA phoneticallyfuzzymatched closely to the name or AKA name, but not exactlyyear_of_birthmatched the birth year as given in filters
PATCH /searches/[id]/entity/[eid]
Example Request
const url = 'https://api.complyadvantage.com/searches/1/entity/FRDG8ZC7VURPKP0?api_key=YOURAPIKEY'
axios.patch(url, {
'match_status': 'false_positive'
})
.then((response) => {
console.log(response.data);
});
url = "https://api.complyadvantage.com/searches/1/entity/FRDG8ZC7VURPKP0?api_key=YOURAPIKEY"
response = requests.patch(url, data = {
"match_status": "false_positive"
})
print(response.json())
Response example
{
"content": {
"entity_id": "FRDG8ZC7VURPKP0",
"match_status": "false_positive",
"client_ref": "CUST0011"
},
"status": "success"
}
{
"content": {
"entity_id": "FRDG8ZC7VURPKP0",
"match_status": "false_positive",
"client_ref": "CUST0011"
},
"status": "success"
}
{
"content": {
"entity_id": "FRDG8ZC7VURPKP0",
"match_status": "false_positive",
"client_ref": "CUST0011"
},
"status": "success"
}
DEPRECATED
Update the match-status of an entity within a search result
URL PARAMETERS
| FIELD | DESCRIPTION |
|---|---|
id |
Either the numeric search ID, or the search REF |
eid |
The alphanumeric ID of the entity |
JSON PATCH PARAMETERS
The following field should be specified in the PATCH request.
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
match_status |
String | One of 'no_match', 'false_positive', 'potential_match', 'true_positive','unknown' |
Webhooks
Source IP Addresses
Your ComplyAdvantage account can be configured so that when certain events occur on your account, a HTTP POST request containing JSON data pertaining to that event is sent to one or more URLs of your choosing. These URLs can be configured inside your account settings within the ComplyAdvantage web application. Notifications of all events are sent to all the configured URLs, allowing you to configure your application to differentiate between the individual events.
SOURCE IP ADDRESSES
Webhooks will be delivered from the following IP addresses:
54.76.153.128
52.19.50.164
18.200.42.250
3.216.162.15
3.214.3.128
52.73.76.4
LOCKING DOWN WEBHOOK ENDPOINTS
We recommend a combination of the following in order to lock down your Webhook endpoints:
- Use
httpsendpoints only - Firewall out all traffic, except from the IP addresses specified above
- Create a unique endpoint, eg
https://wh.mycompany.com/complyadvantage/sadjbrh457GHsaddjhd
POST REQUEST FORMAT (JSON)
The POST request consists of two fields:
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
event |
String | The type of event generated |
data |
Array | The payload of the event |
Details of the specific event types and payloads are included below.
Event: match_status_updated
Webhook sample
{
"event": "match_status_updated",
"data": {
"search_id": 1,
"client_ref": "CUST001",
"entity_id": "34HI34PORF23",
"entity_match_status": "false_positive",
"is_whitelisted": true,
"tags": {
"name": "value"
}
}
}
{
"event": "match_status_updated",
"data": {
"search_id": 1,
"client_ref": "CUST001",
"entity_id": "34HI34PORF23",
"entity_match_status": "false_positive",
"is_whitelisted": true,
"tags": {
"name": "value"
}
}
}
{
"event": "match_status_updated",
"data": {
"search_id": 1,
"client_ref": "CUST001",
"entity_id": "34HI34PORF23",
"entity_match_status": "false_positive",
"is_whitelisted": true,
"tags": {
"name": "value"
}
}
}
This event is fired whenever the match status of an entity or the is_whitelisted property of an entity is changed.
The data payload is as follows:
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
client_ref |
String | Your supplied reference for the search subject |
search_id |
String | The ID of the search |
entity_id |
String | The ID of the entity that has changed e.g: 34HI34PORF23 |
entity_match_status |
String | The new match status of the entity. One of 'false_positive', 'true_positive', 'potential_match', 'no_match', 'unknown'. The field is present in the payload only if the value was changed. |
is_whitelisted |
Boolean | The new value for the is_whitelisted property of the entity. The field is present in the payload only if the value was changed. |
tags |
Object | Any search allocated tags |
Event: search_status_updated
Webhook sample
{
"event": "search_status_updated",
"data": {
"changes": {
"before": {
"assigned_to": 123
},
"after": {
"assigned_to": 234
}
},
"ref": "1470903392-yS1UuFFF",
"client_ref": "12345-MY-REFERENCE",
"search_id": 1234,
"terms": [
{
"name": "Robert Mugabe",
"hits": 7
}
],
"filters": {
"exact_match": false,
"fuzziness": 0.5
}
}
}
{
"event": "search_status_updated",
"data": {
"changes": {
"before": {
"assigned_to": 123
},
"after": {
"assigned_to": 234
}
},
"ref": "1470903392-yS1UuFFF",
"client_ref": "12345-MY-REFERENCE",
"search_id": 1234,
"terms": [
{
"name": "Robert Mugabe",
"hits": 7
}
],
"filters": {
"exact_match": false,
"fuzziness": 0.5
}
}
}
{
"event": "search_status_updated",
"data": {
"changes": {
"before": {
"assigned_to": 123
},
"after": {
"assigned_to": 234
}
},
"ref": "1470903392-yS1UuFFF",
"client_ref": "12345-MY-REFERENCE",
"search_id": 1234,
"terms": [
{
"name": "Robert Mugabe",
"hits": 7
}
],
"filters": {
"exact_match": false,
"fuzziness": 0.5
}
}
}
This event is fired whenever the status of a search is changed through case management functionality (API or UI). The changes to the following fields will trigger this web hook:
assigned_torisk_levelmatch_status
The data payload is as follows:
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
changes |
Object | Contains before and after objects, detailing the changes. Please see the example below |
ref |
String | The search reference |
client_ref |
String | Your supplied reference for the search subject |
search_id |
Integer | The numeric search ID |
terms |
Array | An array of the search terms included in this request |
filters |
Array | An array of the search terms included in this request |
Event: monitored_search_updated
Webhook example
{
"event": "monitored_search_updated",
"data": {
"search_id": 10117833,
"updated": [
"8NMXF7QX4QV8LFD",
"X4525MEAZKKPX0T",
"73HBD537LCX5JT6"
],
"new": [
"Q3OX4KS0KEMCVDH",
"UCC60H79WVU94Z0"
],
"removed": [
"9D1ETD0ADTT4HDH",
"I38XC0R6Y1EQ083"
],
"is_suspended": true
}
}
{
"event": "monitored_search_updated",
"data": {
"search_id": 10117833,
"updated": [
"8NMXF7QX4QV8LFD",
"X4525MEAZKKPX0T",
"73HBD537LCX5JT6"
],
"new": [
"Q3OX4KS0KEMCVDH",
"UCC60H79WVU94Z0"
],
"removed": [
"9D1ETD0ADTT4HDH",
"I38XC0R6Y1EQ083"
],
"is_suspended": true
}
}
{
"event": "monitored_search_updated",
"data": {
"search_id": 10117833,
"updated": [
"8NMXF7QX4QV8LFD",
"X4525MEAZKKPX0T",
"73HBD537LCX5JT6"
],
"new": [
"Q3OX4KS0KEMCVDH",
"UCC60H79WVU94Z0"
],
"removed": [
"9D1ETD0ADTT4HDH",
"I38XC0R6Y1EQ083"
],
"is_suspended": true
}
}
This event is fired when a monitored search has been detected as having updated search results available, and/or the suspended state of the monitored search changes.
The data payload is as follows:
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
search_id |
Integer | The numeric ID of the search |
updated |
Array | An array of the Entity IDs in the search result which have been modified. |
new |
Array | An array of the Entity IDs which have been added to the search result. |
removed |
Array | An array of the Entity IDs which have been removed from the search result. |
is_suspended |
Boolean | Indicates whether this monitored search has been suspended or not. |