NAV
javascript python json

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 appropriate ComplyAdvantage root regional API URL (IP addresses of the API are dynamic) which can be found at:

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:

When making requests to the ComplyAdvantage API there are two methods for providing your API key:

POST /searches?api_key=ggPS2ZOe8DQlCr2scgm2SBelVpNN1B6X

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.

429 Too Many Requests errors

In order to respond quickly to API calls, we have included throttling/overload protection in the API. If you are querying a large amount of data within a short timeframe, the API's response code will indicate that you've exceeded the quota available for your API Key by returning an HTTP status code 429 and an empty body.

Customers on a standard contract will be limited to 600 API calls per minute.

Handling 429 errors

Once you start receiving 429 errors the mitigation mechanism is to include an exponential backoff retry mechanism as described below:

Where:

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)
POST /searches/{id}/comments Create a comment (comment on search or comment on entity)
GET /searches/{id}/comments Retrieve comments for a specific search
DELETE /searches/{id}/tags/{tagName} Detach tags from search
POST /kyb/v1/search Create a new corporate search based on company details
POST /kyb/v1/cases Create a new corporate case
POST /kyb/v1/case/{caseId}/company-screening Create a new corporate screening request for a given company and case

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.

By updating your account limit, you will be able to pull up to 500 results. Note: For entities beyond the first 100 use the provided endpoint to page the remaining entities.

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, json={
  "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, json={
  "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, 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
})
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, 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
})
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, max 255 characters)) 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 identifier of a search profile (depending on the search profile this is either a slug or a profile id) that can be retrieved from the UI
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), must be existing tags
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, 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
})
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:
  • sanction
  • warning
  • fitness-probity
  • pep
  • pep-class-1
  • pep-class-2
  • pep-class-3
  • pep-class-4
If you use classic Adverse Media Taxonomy:
  • adverse-media
  • adverse-media-financial-crime
  • adverse-media-violent-crime
  • adverse-media-sexual-crime
  • adverse-media-terrorism
  • adverse-media-fraud
  • adverse-media-narcotics
  • adverse-media-general
If you use FATF-aligned Adverse Media Taxonomy:
  • adverse-media-v2-property
  • adverse-media-v2-financial-aml-cft
  • adverse-media-v2-fraud-linked
  • adverse-media-v2-narcotics-aml-cft
  • adverse-media-v2-violence-aml-cft
  • adverse-media-v2-terrorism
  • adverse-media-v2-cybercrime
  • adverse-media-v2-general-aml-cft
  • adverse-media-v2-regulatory
  • adverse-media-v2-financial-difficulty
  • adverse-media-v2-violence-non-aml-cft
  • adverse-media-v2-other-financial
  • adverse-media-v2-other-serious
  • adverse-media-v2-other-minor
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:
  • Entity of type PEP only
  • Entity of type PEP with Adverse Media
  • Entity that has 1 country value or more (only one has to match)

Country code filtering does not apply to (i.e. results will still appear regardless of the country filter):
  • Entity on sanction lists will always appear regardless of other status (PEP, Adverse media)
  • Entity that has adverse media mentions only
  • Entity that does not have a country assigned
entity_type String (one of):
  • "person"
  • "company"
  • "organisation"
  • "vessel"
  • "aircraft"
 Entity type filter is not a hard filter between different entity types. It only optimizes the matching logic to the relevant entity type.
Matching:
  • Depending on the entity type, pre-fixes and suffixes will be processed differently to avoid false negatives ("Mr Robert Mugabe" matching "Robert Mugabe" for person, "Cimex Ltd" matching "Cimex" for company).
  • Equivalent names considered specifically for different entity types ("Robert" and "Bob" versus "Investment" and "Inversion").
  • Initial matching between individual ("Carl W. Litsch") versus company acronyms ("KFC").

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,
      "total_matches": 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,
      "total_matches": 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,
      "total_matches": 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:

A cleaned word from your search term

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

A secondary piece of information from your query

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
        },
        "search_profile": {
          "name": "My USA Profile 1",
          "slug": "my-usa-profile-1"
        },
        "match_status": "potential_match",
        "risk_level": "medium",
        "search_term": "Hugo Jinkis",
        "total_hits": 1,
        "total_matches": 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,
        "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,
      "total_matches": 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,
        "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,
      "total_matches": 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', 'true_positive_approve', 'true_positive_reject'). 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'
client_ref Show searches with the same client reference
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,
      "total_matches": 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,
      "total_matches": 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,
      "total_matches": 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]/entities/[entity_provider]

Retrieve the available entities of a search.

URL PARAMETERS

FIELD DESCRIPTION
id Either the numeric search ID, or the search REF
entity_provider The kind of entities you want to retrieve. This can be one of ["comply", "internal"].

QUERY STRING PARAMETERS

FIELD DESCRIPTION
per_page Number of entities to return per page.
Type: int
Default: 100
Max value: 100
page Which page to fetch.
Type: int
Default: 1

Example Request (showing retrieving paginated search entities)

const url = 'https://api.complyadvantage.com/searches/123456/entities/comply?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/123456/entities/comply?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

[
  {
    "doc": {
      "aka": [
        {
          "name": "Robert Mugabe"
        }
      ],
      "assets": [
        {
          "public_url": "http://complyadvantage-asset-development.s3.amazonaws.com/13530e09-a2c0-47b9-b72c-5bd75fccb627.pdf",
          "source": "complyadvantage",
          "type": "pdf",
          "url": "http://www.au.int/en/cpau"
        }
      ],
      "associates": [
        {
          "association": "Spouse",
          "name": "Grace Mugabe"
        }
      ],
      "entity_type": "person",
      "fields": [
        {
          "locale": "en",
          "name": "Date of Birth",
          "source": "example-1-list",
          "tag": "date_of_birth",
          "value": "1924-02-21"
        }
      ],
      "id": "N0HUXBOHUAA52RH",
      "keywords": "keyword",
      "last_updated_utc": "2020-07-27T10:38:55Z",
      "media": [
        {
          "date": "2018-09-17T00:00:00Z",
          "pdf_url": "https://www.thezimbabwemail.com/law-crime/mugabes-son-in-law-under-probe/",
          "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/"
        }
      ],
      "name": "Robert Gabriel Mugabe",
      "source_notes": {
        "property1": {
          "aml_types": [
            "sanction"
          ],
          "country_codes": [
            "BD",
            "LK"
          ],
          "listing_ended_utc": "2020-02-18T00:00:00Z",
          "listing_started_utc": "2018-09-10T00:00:00Z",
          "name": "Robert Gabriel Mugabe",
          "source_id": "example_source_id",
          "url": "example_source_url"
        },
        "property2": {
          "aml_types": [
            "sanction"
          ],
          "country_codes": [
            "BD",
            "LK"
          ],
          "listing_ended_utc": "2020-02-18T00:00:00Z",
          "listing_started_utc": "2018-09-10T00:00:00Z",
          "name": "Robert Gabriel Mugabe",
          "source_id": "example_source_id",
          "url": "example_source_url"
        }
      },
      "sources": [
        "example-1-lits",
        "example-2-list"
      ],
      "types": [
        "sanction",
        "pep-class-1"
      ]
    },
    "match_types": [
      "name_exact",
      "year_of_birth"
    ],
    "score": 3.511,
    "match_status": "false_positive",
    "is_whitelisted": false
  }
]

[
  {
    "doc": {
      "aka": [
        {
          "name": "Robert Mugabe"
        }
      ],
      "assets": [
        {
          "public_url": "http://complyadvantage-asset-development.s3.amazonaws.com/13530e09-a2c0-47b9-b72c-5bd75fccb627.pdf",
          "source": "complyadvantage",
          "type": "pdf",
          "url": "http://www.au.int/en/cpau"
        }
      ],
      "associates": [
        {
          "association": "Spouse",
          "name": "Grace Mugabe"
        }
      ],
      "entity_type": "person",
      "fields": [
        {
          "locale": "en",
          "name": "Date of Birth",
          "source": "example-1-list",
          "tag": "date_of_birth",
          "value": "1924-02-21"
        }
      ],
      "id": "N0HUXBOHUAA52RH",
      "keywords": "keyword",
      "last_updated_utc": "2020-07-27T10:38:55Z",
      "media": [
        {
          "date": "2018-09-17T00:00:00Z",
          "pdf_url": "https://www.thezimbabwemail.com/law-crime/mugabes-son-in-law-under-probe/",
          "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/"
        }
      ],
      "name": "Robert Gabriel Mugabe",
      "source_notes": {
        "property1": {
          "aml_types": [
            "sanction"
          ],
          "country_codes": [
            "BD",
            "LK"
          ],
          "listing_ended_utc": "2020-02-18T00:00:00Z",
          "listing_started_utc": "2018-09-10T00:00:00Z",
          "name": "Robert Gabriel Mugabe",
          "source_id": "example_source_id",
          "url": "example_source_url"
        },
        "property2": {
          "aml_types": [
            "sanction"
          ],
          "country_codes": [
            "BD",
            "LK"
          ],
          "listing_ended_utc": "2020-02-18T00:00:00Z",
          "listing_started_utc": "2018-09-10T00:00:00Z",
          "name": "Robert Gabriel Mugabe",
          "source_id": "example_source_id",
          "url": "example_source_url"
        }
      },
      "sources": [
        "example-1-lits",
        "example-2-list"
      ],
      "types": [
        "sanction",
        "pep-class-1"
      ]
    },
    "match_types": [
      "name_exact",
      "year_of_birth"
    ],
    "score": 3.511,
    "match_status": "false_positive",
    "is_whitelisted": false
  }
]

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/1597743203-T7ddoU4M/details?api_key=YOURAPIKEY&share_url=1'
axios.get(url)
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches/1597743203-T7ddoU4M/details?api_key=YOURAPIKEY&share_url=1"
response = requests.get(url)
print(response.json())

Example Response

{
  "code": 200,
  "status": "success",
  "content": {
    "data": {
      "id": 362438942,
      "ref": "1597743203-T7ddoU4M",
      "searcher_id": 1234,
      "assignee_id": 1235,
      "filters": {
        "country_codes": [],
        "remove_deceased": 0,
        "types": [
          "adverse-media",
          "sanction",
          "warning",
          "adverse-media-general"
        ],
        "exact_match": false,
        "fuzziness": 0.4
      },
      "match_status": "potential_match",
      "risk_level": "unknown",
      "search_term": "hugo jinking",
      "submitted_term": "hugo jinking",
      "client_ref": "test_ref",
      "total_hits": 2,
      "total_matches": 2,
      "updated_at": "2020-08-18 09:33:23",
      "created_at": "2020-08-18 09:33:23",
      "tags": [],
      "labels": [],
      "blacklist_filters": {
        "blacklist_ids": []
      },
      "total_blacklist_hits": 0,
      "limit": 100,
      "offset": 0,
      "searcher": {
        "id": 1234,
        "email": "team@foo.com",
        "name": "Team Guy",
        "phone": "",
        "created_at": "2018-12-17 07:31:31",
        "user_is_active": true
      },
      "assignee": {
        "id": 1235,
        "email": "team-1@foo.com",
        "name": "Team Guy 1",
        "phone": "",
        "created_at": "2018-12-17 07:31:31",
        "user_is_active": true
      },
      "hits": [
        {
          "doc": {
            "aka": [
              {
                "name": "Hugo Mariano Jinkins"
              },
              {
                "name": "Hugo Mariani"
              }
            ],
            "entity_type": "person",
            "fields": [
              {
                "name": "Country",
                "source": "complyadvantage-adverse-media",
                "value": "Uruguay"
              }
            ],
            "id": "4L8FQR8KQF9TA3H",
            "keywords": [],
            "last_updated_utc": "2018-06-27T06:48:06Z",
            "media": [
              {
                "date": "2015-12-09T00:00:00Z",
                "snippet": "Some text",
                "title": "Some title",
                "url": "http://foo.biz"
              }
            ],
            "name": "Hugo Mariano Jinkins",
            "source_notes": {
              "complyadvantage-adverse-media": {
                "aml_types": [
                  "adverse-media",
                  "adverse-media-general"
                ],
                "country_codes": [
                  "UY"
                ],
                "name": "ComplyAdvantage Adverse Media",
                "url": "https:\/\/complyadvantage.com"
              }
            },
            "sources": [
              "complyadvantage-adverse-media"
            ],
            "types": [
              "adverse-media",
              "adverse-media-general"
            ]
          },
          "match_types": [
            "name_fuzzy"
          ],
          "match_types_details": {
            "Hugo Mariano Jinkins": {
              "match_types": {
                "hugo": [
                  "name_exact"
                ],
                "jinking": [
                  "name_fuzzy"
                ]
              },
              "type": "name"
            }
          },
          "score": 15.433824,
          "match_status": "true_positive",
          "is_whitelisted": true,
          "risk_level": "high"
        },
        {
          "doc": {
            "aka": [
              {
                "name": "Hugo Jinkins"
              }
            ],
            "entity_type": "person",
            "fields": [
              {
                "name": "Country",
                "source": "complyadvantage-adverse-media",
                "value": "Argentina"
              }
            ],
            "id": "5IPXAJCBYH0TYXL",
            "keywords": [],
            "last_updated_utc": "2020-08-05T13:07:36Z",
            "media": [
              {
                "date": "2016-04-05T00:00:00Z",
                "snippet": "Another text",
                "title": "Another title",
                "url": "http://biz.foo"
              }
            ],
            "name": "Hugo Jinkins",
            "source_notes": {
              "complyadvantage-adverse-media": {
                "aml_types": [
                  "adverse-media",
                  "adverse-media-general"
                ],
                "country_codes": [
                  "AR",
                  "BR"
                ],
                "name": "ComplyAdvantage Adverse Media",
                "url": "https:\/\/complyadvantage.com"
              }
            },
            "sources": [
              "complyadvantage-adverse-media"
            ],
            "types": [
              "adverse-media",
              "adverse-media-general"
            ]
          },
          "match_types": [
            "name_fuzzy"
          ],
          "match_types_details": {
            "Hugo Jinkins": {
              "match_types": {
                "hugo": [
                  "name_exact"
                ],
                "jinking": [
                  "name_fuzzy"
                ]
              },
              "type": "name"
            }
          },
          "score": 15.296134,
          "match_status": "true_positive",
          "is_whitelisted": false,
          "risk_level": "high"
        }
      ],
      "blacklist_hits": []
    }
  }
}

{
  "code": 200,
  "status": "success",
  "content": {
    "data": {
      "id": 362438942,
      "ref": "1597743203-T7ddoU4M",
      "searcher_id": 1234,
      "assignee_id": 1235,
      "filters": {
        "country_codes": [],
        "remove_deceased": 0,
        "types": [
          "adverse-media",
          "sanction",
          "warning",
          "adverse-media-general"
        ],
        "exact_match": false,
        "fuzziness": 0.4
      },
      "match_status": "potential_match",
      "risk_level": "unknown",
      "search_term": "hugo jinking",
      "submitted_term": "hugo jinking",
      "client_ref": "test_ref",
      "total_hits": 2,
      "total_matches": 2,
      "updated_at": "2020-08-18 09:33:23",
      "created_at": "2020-08-18 09:33:23",
      "tags": [],
      "labels": [],
      "blacklist_filters": {
        "blacklist_ids": []
      },
      "total_blacklist_hits": 0,
      "limit": 100,
      "offset": 0,
      "searcher": {
        "id": 1234,
        "email": "team@foo.com",
        "name": "Team Guy",
        "phone": "",
        "created_at": "2018-12-17 07:31:31",
        "user_is_active": true
      },
      "assignee": {
        "id": 1235,
        "email": "team-1@foo.com",
        "name": "Team Guy 1",
        "phone": "",
        "created_at": "2018-12-17 07:31:31",
        "user_is_active": true
      },
      "hits": [
        {
          "doc": {
            "aka": [
              {
                "name": "Hugo Mariano Jinkins"
              },
              {
                "name": "Hugo Mariani"
              }
            ],
            "entity_type": "person",
            "fields": [
              {
                "name": "Country",
                "source": "complyadvantage-adverse-media",
                "value": "Uruguay"
              }
            ],
            "id": "4L8FQR8KQF9TA3H",
            "keywords": [],
            "last_updated_utc": "2018-06-27T06:48:06Z",
            "media": [
              {
                "date": "2015-12-09T00:00:00Z",
                "snippet": "Some text",
                "title": "Some title",
                "url": "http://foo.biz"
              }
            ],
            "name": "Hugo Mariano Jinkins",
            "source_notes": {
              "complyadvantage-adverse-media": {
                "aml_types": [
                  "adverse-media",
                  "adverse-media-general"
                ],
                "country_codes": [
                  "UY"
                ],
                "name": "ComplyAdvantage Adverse Media",
                "url": "https:\/\/complyadvantage.com"
              }
            },
            "sources": [
              "complyadvantage-adverse-media"
            ],
            "types": [
              "adverse-media",
              "adverse-media-general"
            ]
          },
          "match_types": [
            "name_fuzzy"
          ],
          "match_types_details": {
            "Hugo Mariano Jinkins": {
              "match_types": {
                "hugo": [
                  "name_exact"
                ],
                "jinking": [
                  "name_fuzzy"
                ]
              },
              "type": "name"
            }
          },
          "score": 15.433824,
          "match_status": "true_positive",
          "is_whitelisted": true,
          "risk_level": "high"
        },
        {
          "doc": {
            "aka": [
              {
                "name": "Hugo Jinkins"
              }
            ],
            "entity_type": "person",
            "fields": [
              {
                "name": "Country",
                "source": "complyadvantage-adverse-media",
                "value": "Argentina"
              }
            ],
            "id": "5IPXAJCBYH0TYXL",
            "keywords": [],
            "last_updated_utc": "2020-08-05T13:07:36Z",
            "media": [
              {
                "date": "2016-04-05T00:00:00Z",
                "snippet": "Another text",
                "title": "Another title",
                "url": "http://biz.foo"
              }
            ],
            "name": "Hugo Jinkins",
            "source_notes": {
              "complyadvantage-adverse-media": {
                "aml_types": [
                  "adverse-media",
                  "adverse-media-general"
                ],
                "country_codes": [
                  "AR",
                  "BR"
                ],
                "name": "ComplyAdvantage Adverse Media",
                "url": "https:\/\/complyadvantage.com"
              }
            },
            "sources": [
              "complyadvantage-adverse-media"
            ],
            "types": [
              "adverse-media",
              "adverse-media-general"
            ]
          },
          "match_types": [
            "name_fuzzy"
          ],
          "match_types_details": {
            "Hugo Jinkins": {
              "match_types": {
                "hugo": [
                  "name_exact"
                ],
                "jinking": [
                  "name_fuzzy"
                ]
              },
              "type": "name"
            }
          },
          "score": 15.296134,
          "match_status": "true_positive",
          "is_whitelisted": false,
          "risk_level": "high"
        }
      ],
      "blacklist_hits": []
    }
  }
}

{
  "code": 200,
  "status": "success",
  "content": {
    "data": {
      "id": 362438942,
      "ref": "1597743203-T7ddoU4M",
      "searcher_id": 1234,
      "assignee_id": 1235,
      "filters": {
        "country_codes": [],
        "remove_deceased": 0,
        "types": [
          "adverse-media",
          "sanction",
          "warning",
          "adverse-media-general"
        ],
        "exact_match": false,
        "fuzziness": 0.4
      },
      "match_status": "potential_match",
      "risk_level": "unknown",
      "search_term": "hugo jinking",
      "submitted_term": "hugo jinking",
      "client_ref": "test_ref",
      "total_hits": 2,
      "total_matches": 2,
      "updated_at": "2020-08-18 09:33:23",
      "created_at": "2020-08-18 09:33:23",
      "tags": [],
      "labels": [],
      "blacklist_filters": {
        "blacklist_ids": []
      },
      "total_blacklist_hits": 0,
      "limit": 100,
      "offset": 0,
      "searcher": {
        "id": 1234,
        "email": "team@foo.com",
        "name": "Team Guy",
        "phone": "",
        "created_at": "2018-12-17 07:31:31",
        "user_is_active": true
      },
      "assignee": {
        "id": 1235,
        "email": "team-1@foo.com",
        "name": "Team Guy 1",
        "phone": "",
        "created_at": "2018-12-17 07:31:31",
        "user_is_active": true
      },
      "hits": [
        {
          "doc": {
            "aka": [
              {
                "name": "Hugo Mariano Jinkins"
              },
              {
                "name": "Hugo Mariani"
              }
            ],
            "entity_type": "person",
            "fields": [
              {
                "name": "Country",
                "source": "complyadvantage-adverse-media",
                "value": "Uruguay"
              }
            ],
            "id": "4L8FQR8KQF9TA3H",
            "keywords": [],
            "last_updated_utc": "2018-06-27T06:48:06Z",
            "media": [
              {
                "date": "2015-12-09T00:00:00Z",
                "snippet": "Some text",
                "title": "Some title",
                "url": "http://foo.biz"
              }
            ],
            "name": "Hugo Mariano Jinkins",
            "source_notes": {
              "complyadvantage-adverse-media": {
                "aml_types": [
                  "adverse-media",
                  "adverse-media-general"
                ],
                "country_codes": [
                  "UY"
                ],
                "name": "ComplyAdvantage Adverse Media",
                "url": "https:\/\/complyadvantage.com"
              }
            },
            "sources": [
              "complyadvantage-adverse-media"
            ],
            "types": [
              "adverse-media",
              "adverse-media-general"
            ]
          },
          "match_types": [
            "name_fuzzy"
          ],
          "match_types_details": {
            "Hugo Mariano Jinkins": {
              "match_types": {
                "hugo": [
                  "name_exact"
                ],
                "jinking": [
                  "name_fuzzy"
                ]
              },
              "type": "name"
            }
          },
          "score": 15.433824,
          "match_status": "true_positive",
          "is_whitelisted": true,
          "risk_level": "high"
        },
        {
          "doc": {
            "aka": [
              {
                "name": "Hugo Jinkins"
              }
            ],
            "entity_type": "person",
            "fields": [
              {
                "name": "Country",
                "source": "complyadvantage-adverse-media",
                "value": "Argentina"
              }
            ],
            "id": "5IPXAJCBYH0TYXL",
            "keywords": [],
            "last_updated_utc": "2020-08-05T13:07:36Z",
            "media": [
              {
                "date": "2016-04-05T00:00:00Z",
                "snippet": "Another text",
                "title": "Another title",
                "url": "http://biz.foo"
              }
            ],
            "name": "Hugo Jinkins",
            "source_notes": {
              "complyadvantage-adverse-media": {
                "aml_types": [
                  "adverse-media",
                  "adverse-media-general"
                ],
                "country_codes": [
                  "AR",
                  "BR"
                ],
                "name": "ComplyAdvantage Adverse Media",
                "url": "https:\/\/complyadvantage.com"
              }
            },
            "sources": [
              "complyadvantage-adverse-media"
            ],
            "types": [
              "adverse-media",
              "adverse-media-general"
            ]
          },
          "match_types": [
            "name_fuzzy"
          ],
          "match_types_details": {
            "Hugo Jinkins": {
              "match_types": {
                "hugo": [
                  "name_exact"
                ],
                "jinking": [
                  "name_fuzzy"
                ]
              },
              "type": "name"
            }
          },
          "score": 15.296134,
          "match_status": "true_positive",
          "is_whitelisted": false,
          "risk_level": "high"
        }
      ],
      "blacklist_hits": []
    }
  }
}

Retrieve the full details and results of a specific search on your account.

By default creating a search will pull the first 100 entities (if that many exist) from our database. By updating your account limit, you can expand this. Note: For entities beyond the first 100 use the provided endpoint to page the remaining entities.

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,
        "limit": 50,
        "tags": {
            "MyTagName": "MyTagValue"
        }
    })
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches/46?api_key=YOURAPIKEY"
response = requests.patch(url, json={
  "match_status": "false_positive",
  "risk_level": "low",
  "assignee_id": 123,
  "limit": 50,
  "tags": {
    "MyTagName": "MyTagValue"
  }
})
print(response.json())

{
  "match_status": "false_positive",
  "risk_level": "low",
  "assignee_id": 123,
  "limit": 50,
  "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,
      "total_matches": 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,
      "total_matches": 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,
      "total_matches": 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
limit Integer The number of matches retrieved (max. 100)
tags Object Object of name => value pairs ( name must be string ), must be existing tags

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, json={
  "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": {
      "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,
      "total_matches": 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": {
      "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,
      "total_matches": 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": {
      "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,
      "total_matches": 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.

By default creating a search will pull the first 100 entities (if that many exist) from our database. By updating your account limit, you can expand this. Note: For entities beyond the first 100 use the provided endpoint to page the remaining entities.

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

Deleting Searches

DELETE /searches/[id]

Example Request

const url = 'https://api.complyadvantage.com/searches/46?api_key=YOURAPIKEY'
axios.delete(url)
    .then((response) => {
        console.log(response.status);
    });

url = "https://api.complyadvantage.com/searches/46?api_key=YOURAPIKEY"
response = requests.delete(url)
print(response.status_code)

Example Response 

204

204

Delete a search. Disclaimer: We cannot guarantee that all data is removed from our backups or our system after executing this call.

URL PARAMETERS

FIELD DESCRIPTION
id Either the numeric search ID, or the search REF

Status codes

STATUS CODE DESCRIPTION
204 Search deleted.
400 Invalid input.
404 Search not found.

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, json={
  "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.

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

Comments

POST /searches/{id}/comments

Example Request for comment on search

const url = 'https://api.complyadvantage.com/searches/1594889804-eVSo1JXO/comments?api_key=<<.. your API key ..>>'
axios.post(url, {
    "comment": "test comment on search"
});

url = "https://api.complyadvantage.com/searches/1594889804-eVSo1JXO/comments?api_key=<<.. your API key ..>>"
response = requests.post(url, json={
    "comment": "test comment on search"
})
print(response.status_code)

Example Response 

204 no content

Example Request for comment on entity

const url = 'https://api.complyadvantage.com/searches/1594889804-eVSo1JXO/comments?api_key=<<.. your API key ..>>'
axios.post(url, {
    "comment": "test comment on entity",
    "entity_id": "NAG9ONPS86191L1"
});

url = "https://api.complyadvantage.com/searches/1594889804-eVSo1JXO/comments?api_key=<<.. your API key ..>>"
response = requests.post(url, json={
    "comment": "test comment on entity",
    "entity_id": "NAG9ONPS86191L1"
})
print(response.status_code)

Example Response 

204 no content

Create comment on search or create comment on entity.

The user that the API Key used was created with will be the assigned user for the comment and the timesatamp will be the time the endpoint is called

URL PARAMETERS

FIELD DESCRIPTION
id Either the numeric search ID, or the search REF

JSON POST PARAMETERS

FIELD TYPE DESCRIPTION
comment String The comment that will be added
entity_id String The entity id (required for adding comment on entity)

GET /searches/{id}/comments

Example Request

const url = 'https://api.complyadvantage.com/searches/1594889804-eVSo1JXO/comments?api_key=YOURAPIKEY'
axios.get(url)
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches/1594889804-eVSo1JXO/comments?api_key=YOURAPIKEY"
response = requests.get(url)
print(response.json())

Example Response 

{
  "code": 200,
  "status": "success",
  "content": [
        {
          "id": "5e172aee7de6cbd5a93f80b5",
          "created_at": "2020-01-09T13:30:22.973000",
          "message": "test comment on search",
          "user_id": 1
        },
        {
          "id": "5e172b2f7de6cbd5a93f80b8",
          "created_at": "2020-01-09T13:31:27.658000",
          "message": "test comment on entity",
          "entity_id": "NAG9ONPS86191L1",
          "user_id": 1
        }
]
}

{
  "code": 200,
  "status": "success",
  "content": [
        {
          "id": "5e172aee7de6cbd5a93f80b5",
          "created_at": "2020-01-09T13:30:22.973000",
          "message": "test comment on search",
          "user_id": 1
        },
        {
          "id": "5e172b2f7de6cbd5a93f80b8",
          "created_at": "2020-01-09T13:31:27.658000",
          "message": "test comment on entity",
          "entity_id": "NAG9ONPS86191L1",
          "user_id": 1
        }
]
}

{
  "code": 200,
  "status": "success",
  "content": [
        {
          "id": "5e172aee7de6cbd5a93f80b5",
          "created_at": "2020-01-09T13:30:22.973000",
          "message": "test comment on search",
          "user_id": 1
        },
        {
          "id": "5e172b2f7de6cbd5a93f80b8",
          "created_at": "2020-01-09T13:31:27.658000",
          "message": "test comment on entity",
          "entity_id": "NAG9ONPS86191L1",
          "user_id": 1
        }
]
}

Retrieve comments for a specific search

URL PARAMETERS

FIELD DESCRIPTION
id Either the numeric search ID, or the search REF

Detaching Tags

DELETE /searches/{id}/tags/{tag_name}

Example Request

const url = 'https://api.complyadvantage.com/searches/46/tags/MY_TAG?api_key=YOURAPIKEY'
axios.delete(url)
    .then((response) => {
        console.log(response.status);
    });

url = "https://api.complyadvantage.com/searches/46/tags/MY_TAG?api_key=YOURAPIKEY"
response = requests.delete(url)
print(response.status_code)

Example Response 

204

204

Detaches a tag and the value for the tag associated to a search.

Note: if you assigned the same tag with multiple values to the search, it will detach all of them.

URL PARAMETERS

FIELD DESCRIPTION
id numeric search ID
tag_name the name of the tag

Status codes

STATUS CODE DESCRIPTION
204 Tags was detached.
400 Invalid input. Verify if that search and tag attached to it exist.

Creating KYB requests

POST /kyb/v1/search

Create a new corporate search based on company details (name, country or company id).

Example Request 1

Example request 1

const url = 'https://api.complyadvantage.com/kyb/v1/search'
axios.post(url, {
        "name": "Example Inc",
        "incorporation_country_code": "GB",
        "company_id": ""
    }, {
        headers: {
          "Authorization": "Token <<.. your API key ..>>"
        }
    })
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/kyb/v1/search"
response = requests.post(url, json={
    "name": "Example Inc",
    "incorporation_country_code": "GB",
    "company_id": ""
}, headers={
    "Authorization": "Token <<.. your API key ..>>"
})
print(response.json())

{
    "name": "Example Inc",
    "incorporation_country_code": "GB",
    "company_id": ""
}

This illustrates a corporate search request based on company name and company country.

Example Request 2

Example request 2

const url = 'https://api.complyadvantage.com/kyb/v1/search'
axios.post(url, {
        "name": "",
        "incorporation_country_code": "",
        "company_id": "abc12345"
    }, {
        headers: {
          "Authorization": "Token <<.. your API key ..>>"
        }
    })
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/kyb/v1/search"
response = requests.post(url, json={
    "name": "",
    "incorporation_country_code": "",
    "company_id": "abc12345"
}, headers={
    "Authorization": "Token <<.. your API key ..>>"
})
print(response.json())

{
    "name": "",
    "incorporation_country_code": "",
    "company_id": "abc12345"
}

This illustrates a corporate search request based on company id.

JSON POST PARAMETERS

FIELD TYPE TYPE DESCRIPTION
name(optional) String A string representing the name of the searched company. This is required when company_id is not provided.
incorporation_country_code (required) String An ISO-3166-1 alpha2 code or an ISO-3166-2 code representing the country of incorporation.
company_id (optional) String (default is empty) A string representing the id of the searched company. If company_id is provided, the name is ignored if it is provided.

Company search response

Response sample

{
  "data": [
    {
      "companyId": "abc12345",
      "name": "Example Inc.",
      "address": "Street, Number, City, PostalCode",
      "status": "active"
    }
  ],
  "links": [
    {
      "self": "/v1/search"
    }
  ]
}

{
  "data": [
    {
      "companyId": "abc12345",
      "name": "Example Inc.",
      "address": "Street, Number, City, PostalCode",
      "status": "active"
    }
  ],
  "links": [
    {
      "self": "/v1/search"
    }
  ]
}

{
  "data": [
    {
      "companyId": "abc12345",
      "name": "Example Inc.",
      "address": "Street, Number, City, PostalCode",
      "status": "active"
    }
  ],
  "links": [
    {
      "self": "/v1/search"
    }
  ]
}

The returned data contains an array with the found companies and it also contains an array with contextual canonical links.

POST /kyb/v1/cases

Create a new corporate case which can have a client reference.

Example Request 1

Example request 1

const url = 'https://api.complyadvantage.com/kyb/v1/cases'
axios.post(url, {}, {
        headers: {
        "Authorization": "Token <<.. your API key ..>>"
        }
    })
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/kyb/v1/cases"
response = requests.post(url, json={}, headers={
    "Authorization": "Token <<.. your API key ..>>"
})
print(response.json())

{}

This illustrates a case creation without a client reference.

Example Request 2

Example request 2

const url = 'https://api.complyadvantage.com/kyb/v1/cases'
axios.post(url, {
        "client_ref": "test-client-1"
    }, {
        headers: {
        "Authorization": "Token <<.. your API key ..>>"
        }
    })
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/kyb/v1/cases"
response = requests.post(url, json={
    "client_ref": "test-client-1"
}, headers={
    "Authorization": "Token <<.. your API key ..>>"
})
print(response.json())

{
    "client_ref": "test-client-1"
}

This illustrates a case creation with a client reference.

JSON POST PARAMETERS

FIELD TYPE TYPE DESCRIPTION
client_ref (optional) String A string representing the client reference. This must contain only alphanumeric characters, spaces, dashes and underscores.

Create a new case response

Response sample

{
  "data": {
    "created_by": {
      "user_id": 1,
      "user_name": "test"
    }
  },
  "links": [
      {
          "self": "/v1/case/1"
      }
  ]
}

{
  "data": {
    "created_by": {
      "user_id": 1,
      "user_name": "test"
    }
  },
  "links": [
      {
          "self": "/v1/case/1"
      }
  ]
}

{
  "data": {
    "created_by": {
      "user_id": 1,
      "user_name": "test"
    }
  },
  "links": [
      {
          "self": "/v1/case/1"
      }
  ]
}

The returned links contains a canonical url to the created case and the returned data contains information about the user (user id and username) that created the case.

POST /kyb/v1/case/{caseId}/company-screening

Create a new corporate screening request for a given company and case.

Example Request 1

Example request 1

const url = 'https://api.complyadvantage.com/kyb/v1/case/1/company-screening'
axios.post(url, {
        "company_id": "abc12345",
        "incorporation_country_code": "GB"
    }, {
        headers: {
          "Authorization": "Token <<.. your API key ..>>"
        }
    })
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/kyb/v1/case/1/company-screening"
response = requests.post(url, json={
    "company_id": "abc12345",
    "incorporation_country_code": "GB"
}, headers={
    "Authorization": "Token <<.. your API key ..>>"
})
print(response.json())

{
    "company_id": "abc12345",
    "incorporation_country_code": "GB"
}

This illustrates a corporate screening request based on company id and company incorporation country code.

JSON POST PARAMETERS

FIELD TYPE TYPE DESCRIPTION
company_id (required) String A string representing the id of the screened company.
incorporation_country_code (required) String An ISO-3166-1 alpha2 code or an ISO-3166-2 code representing the country of incorporation.

Start a company screening response

Response sample

{
  "data": {
    "created_by": {
      "user_id": 1,
      "user_name": "test"
    },
    "screeningId": 1
  },
  "links": [
    {
      "self": "/v1/case/1/company-screening/1"
    }
  ]
}

{
  "data": {
    "created_by": {
      "user_id": 1,
      "user_name": "test"
    },
    "screeningId": 1
  },
  "links": [
    {
      "self": "/v1/case/1/company-screening/1"
    }
  ]
}

{
  "data": {
    "created_by": {
      "user_id": 1,
      "user_name": "test"
    },
    "screeningId": 1
  },
  "links": [
    {
      "self": "/v1/case/1/company-screening/1"
    }
  ]
}

The returned data contains and screening id used to identity this new created corporate screening request and it also contains information about the user that created the screening (user id and username). The response also cotains an array with contextual canonical links.

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

POST /searches/references

Example request

const url = 'https://api.complyadvantage.com/searches/references?api_key=YOURAPIKEY'
axios.post(url, {
    "search_term": "Thanks for the party Kim Jong-un",
    "client_ref": "clientRef",
    "search_profile": "d9d050bb-0e6a-4a93-b9bc-83f51a9503db"
    })
    .then((response) => {
        console.log(response.data);
    });

const url = 'https://api.complyadvantage.com/searches/references?api_key=YOURAPIKEY'
response = requests.post(url, json={
    "search_term": "Thanks for the party Kim Jong-un",
    "client_ref": "clientRef",
    "search_profile": "d9d050bb-0e6a-4a93-b9bc-83f51a9503db"})
print(response.json())

{
    "search_term": "Thanks for the party Kim Jong-un",
    "client_ref": "clientRef",
    "search_profile": "d9d050bb-0e6a-4a93-b9bc-83f51a9503db"
}

Example Response - shows the search response for the submitted search term:

{
  "code": 200,
  "status": "success",
  "content": {
    "data": {
      "id": 8181704,
      "ref": "1626950002-gVuLKYdI",
      "searcher_id": 200088,
      "assignee_id": 200088,
      "fuzziness": 0.8,
      "search_term": "RequestSearchTerm",
      "submitted_term": "RequestSearchTerm",
      "client_ref": "clientRef",
      "total_hits": 10,
      "created_at": "2021-07-22 10:33:22",
      "labels": [],
      "total_matches": 11,
      "search_profile": {
        "name": "SearchProfileName",
        "slug": "d9d050bb-0e6a-4a93-b9bc-83f51a9503db"
      },
      "blacklist_filters": {
        "blacklist_ids": [
          "60f932d5ab93bb962f0a6a72"
        ]
      },
      "total_blacklist_hits": 1,
      "searcher": {
        "id": 200088,
        "email": "username@complyadvantage.com",
        "name": "Username",
        "phone": "",
        "created_at": "2021-07-22 08:17:43",
        "user_is_active": true
      },
      "assignee": {
        "id": 200088,
        "email": "username@complyadvantage.com",
        "name": "Username",
        "phone": "",
        "created_at": "2021-07-22 08:17:43",
        "user_is_active": true
      },
      "hits": [
        {
          "doc": {
            "aka": [
              {
                "name": "Culma Sunz Bladimir"
              },
              {
                "name": "VLADIMIR"
              },
              {
                "name": "Culman Sanz Bladimir"
              }
            ],
            "entity_type": "person",
            "fields": [
              {
                "name": "Nationality",
                "source": "ofac-sdn-list",
                "value": "Colombia"
              },
              {
                "name": "Country",
                "source": "ofac-sdn-list",
                "value": "Colombia"
              },
            ],
            "id": "BP9UT32NJLE8S8T",
            "keywords": [],
            "last_updated_utc": "2020-06-22T09:33:02Z",
            "name": "Culma Sunz Bladimir",
            "source_notes": {
              "ofac-sdn-list": {
                "aml_types": [
                  "sanction"
                ],
                "country_codes": [
                  "CO"
                ],
                "listing_started_utc": "2008-07-31T00:00:00Z",
                "name": "OFAC SDN List",
                "url": "http://www.treasury.gov/resource-center/sanctions/SDN-List/Pages/default.aspx"
              }
            },
            "sources": [
              "ofac-sdn-list"
            ],
            "types": [
              "sanction"
            ]
          },
          "match_types": [
            "ngram"
          ],
          "match_details": [
            {
              "matching_term": "VLADIMIR",
              "matching_reason": "exact_match",
              "substring": "r Vladimir Putin",
              "substring_index": [
                44,
                59
              ]
              },
            {
              "matching_term": "vladidimir",
              "matching_reason": "not_available",
              "substring": "r Vladimir Putin. So",
              "substring_index": [
                44,
                63
              ]
            },
            {
              "matching_term": "vladimiriv",
              "matching_reason": "not_available",
              "substring": "r Vladimir Putin. So",
              "substring_index": [
                44,
                63
              ]
            }
          ],
          "score": 29.926937
        },
        ....
      ],
      "blacklist_hits": [
        {
          "doc": {
            "account_ids": [
              200014
            ],
            "aka": [
              {
                "name": "cocaine"
              }
            ],
            "blacklist_ids": [
              "60f932d5ab93bb962f0a6a72"
            ],
            "created_utc": "2021-07-22T09:06:38Z",
            "entity_type": "person",
            "fields": [
              {
                "name": "Notes",
                "tag": "notes",
                "value": "Blacklisted for ID Fraud on 2016-03-04"
              },
              {
                "name": "User-defined ID",
                "tag": "user_defined_id",
                "value": "003-A-2019"
              }
            ],
            "id": "ce1f3823da743f2a8c5d36a1119570dd",
            "keywords": [],
            "last_updated_utc": "2021-07-22T09:06:38Z",
            "name": "cocaine",
            "scraper_ids": [],
            "sources": [
              "erictest"
            ],
            "types": []
          },
          "match_types": [
            "ngram"
          ],
          "match_details": [
            {
              "matching_term": "cocaine",
              "matching_reason": "exact_match",
              "substring": "e cocaine and ",
              "substring_index": [
                14,
                27
              ]
            }
          ],
          "score": 49.624763
        }
      ]
    }
  }
}




{
  "code": 200,
  "status": "success",
  "content": {
    "data": {
      "id": 8181704,
      "ref": "1626950002-gVuLKYdI",
      "searcher_id": 200088,
      "assignee_id": 200088,
      "fuzziness": 0.8,
      "search_term": "RequestSearchTerm",
      "submitted_term": "RequestSearchTerm",
      "client_ref": "clientRef",
      "total_hits": 10,
      "created_at": "2021-07-22 10:33:22",
      "labels": [],
      "total_matches": 11,
      "search_profile": {
        "name": "SearchProfileName",
        "slug": "d9d050bb-0e6a-4a93-b9bc-83f51a9503db"
      },
      "blacklist_filters": {
        "blacklist_ids": [
          "60f932d5ab93bb962f0a6a72"
        ]
      },
      "total_blacklist_hits": 1,
      "searcher": {
        "id": 200088,
        "email": "username@complyadvantage.com",
        "name": "Username",
        "phone": "",
        "created_at": "2021-07-22 08:17:43",
        "user_is_active": true
      },
      "assignee": {
        "id": 200088,
        "email": "username@complyadvantage.com",
        "name": "Username",
        "phone": "",
        "created_at": "2021-07-22 08:17:43",
        "user_is_active": true
      },
      "hits": [
        {
          "doc": {
            "aka": [
              {
                "name": "Culma Sunz Bladimir"
              },
              {
                "name": "VLADIMIR"
              },
              {
                "name": "Culman Sanz Bladimir"
              }
            ],
            "entity_type": "person",
            "fields": [
              {
                "name": "Nationality",
                "source": "ofac-sdn-list",
                "value": "Colombia"
              },
              {
                "name": "Country",
                "source": "ofac-sdn-list",
                "value": "Colombia"
              },
            ],
            "id": "BP9UT32NJLE8S8T",
            "keywords": [],
            "last_updated_utc": "2020-06-22T09:33:02Z",
            "name": "Culma Sunz Bladimir",
            "source_notes": {
              "ofac-sdn-list": {
                "aml_types": [
                  "sanction"
                ],
                "country_codes": [
                  "CO"
                ],
                "listing_started_utc": "2008-07-31T00:00:00Z",
                "name": "OFAC SDN List",
                "url": "http://www.treasury.gov/resource-center/sanctions/SDN-List/Pages/default.aspx"
              }
            },
            "sources": [
              "ofac-sdn-list"
            ],
            "types": [
              "sanction"
            ]
          },
          "match_types": [
            "ngram"
          ],
          "match_details": [
            {
              "matching_term": "VLADIMIR",
              "matching_reason": "exact_match",
              "substring": "r Vladimir Putin",
              "substring_index": [
                44,
                59
              ]
              },
            {
              "matching_term": "vladidimir",
              "matching_reason": "not_available",
              "substring": "r Vladimir Putin. So",
              "substring_index": [
                44,
                63
              ]
            },
            {
              "matching_term": "vladimiriv",
              "matching_reason": "not_available",
              "substring": "r Vladimir Putin. So",
              "substring_index": [
                44,
                63
              ]
            }
          ],
          "score": 29.926937
        },
        ....
      ],
      "blacklist_hits": [
        {
          "doc": {
            "account_ids": [
              200014
            ],
            "aka": [
              {
                "name": "cocaine"
              }
            ],
            "blacklist_ids": [
              "60f932d5ab93bb962f0a6a72"
            ],
            "created_utc": "2021-07-22T09:06:38Z",
            "entity_type": "person",
            "fields": [
              {
                "name": "Notes",
                "tag": "notes",
                "value": "Blacklisted for ID Fraud on 2016-03-04"
              },
              {
                "name": "User-defined ID",
                "tag": "user_defined_id",
                "value": "003-A-2019"
              }
            ],
            "id": "ce1f3823da743f2a8c5d36a1119570dd",
            "keywords": [],
            "last_updated_utc": "2021-07-22T09:06:38Z",
            "name": "cocaine",
            "scraper_ids": [],
            "sources": [
              "erictest"
            ],
            "types": []
          },
          "match_types": [
            "ngram"
          ],
          "match_details": [
            {
              "matching_term": "cocaine",
              "matching_reason": "exact_match",
              "substring": "e cocaine and ",
              "substring_index": [
                14,
                27
              ]
            }
          ],
          "score": 49.624763
        }
      ]
    }
  }
}

{
  "code": 200,
  "status": "success",
  "content": {
    "data": {
      "id": 8181704,
      "ref": "1626950002-gVuLKYdI",
      "searcher_id": 200088,
      "assignee_id": 200088,
      "fuzziness": 0.8,
      "search_term": "RequestSearchTerm",
      "submitted_term": "RequestSearchTerm",
      "client_ref": "clientRef",
      "total_hits": 10,
      "created_at": "2021-07-22 10:33:22",
      "labels": [],
      "total_matches": 11,
      "search_profile": {
        "name": "SearchProfileName",
        "slug": "d9d050bb-0e6a-4a93-b9bc-83f51a9503db"
      },
      "blacklist_filters": {
        "blacklist_ids": [
          "60f932d5ab93bb962f0a6a72"
        ]
      },
      "total_blacklist_hits": 1,
      "searcher": {
        "id": 200088,
        "email": "username@complyadvantage.com",
        "name": "Username",
        "phone": "",
        "created_at": "2021-07-22 08:17:43",
        "user_is_active": true
      },
      "assignee": {
        "id": 200088,
        "email": "username@complyadvantage.com",
        "name": "Username",
        "phone": "",
        "created_at": "2021-07-22 08:17:43",
        "user_is_active": true
      },
      "hits": [
        {
          "doc": {
            "aka": [
              {
                "name": "Culma Sunz Bladimir"
              },
              {
                "name": "VLADIMIR"
              },
              {
                "name": "Culman Sanz Bladimir"
              }
            ],
            "entity_type": "person",
            "fields": [
              {
                "name": "Nationality",
                "source": "ofac-sdn-list",
                "value": "Colombia"
              },
              {
                "name": "Country",
                "source": "ofac-sdn-list",
                "value": "Colombia"
              },
            ],
            "id": "BP9UT32NJLE8S8T",
            "keywords": [],
            "last_updated_utc": "2020-06-22T09:33:02Z",
            "name": "Culma Sunz Bladimir",
            "source_notes": {
              "ofac-sdn-list": {
                "aml_types": [
                  "sanction"
                ],
                "country_codes": [
                  "CO"
                ],
                "listing_started_utc": "2008-07-31T00:00:00Z",
                "name": "OFAC SDN List",
                "url": "http://www.treasury.gov/resource-center/sanctions/SDN-List/Pages/default.aspx"
              }
            },
            "sources": [
              "ofac-sdn-list"
            ],
            "types": [
              "sanction"
            ]
          },
          "match_types": [
            "ngram"
          ],
          "match_details": [
            {
              "matching_term": "VLADIMIR",
              "matching_reason": "exact_match",
              "substring": "r Vladimir Putin",
              "substring_index": [
                44,
                59
              ]
              },
            {
              "matching_term": "vladidimir",
              "matching_reason": "not_available",
              "substring": "r Vladimir Putin. So",
              "substring_index": [
                44,
                63
              ]
            },
            {
              "matching_term": "vladimiriv",
              "matching_reason": "not_available",
              "substring": "r Vladimir Putin. So",
              "substring_index": [
                44,
                63
              ]
            }
          ],
          "score": 29.926937
        },
        ....
      ],
      "blacklist_hits": [
        {
          "doc": {
            "account_ids": [
              200014
            ],
            "aka": [
              {
                "name": "cocaine"
              }
            ],
            "blacklist_ids": [
              "60f932d5ab93bb962f0a6a72"
            ],
            "created_utc": "2021-07-22T09:06:38Z",
            "entity_type": "person",
            "fields": [
              {
                "name": "Notes",
                "tag": "notes",
                "value": "Blacklisted for ID Fraud on 2016-03-04"
              },
              {
                "name": "User-defined ID",
                "tag": "user_defined_id",
                "value": "003-A-2019"
              }
            ],
            "id": "ce1f3823da743f2a8c5d36a1119570dd",
            "keywords": [],
            "last_updated_utc": "2021-07-22T09:06:38Z",
            "name": "cocaine",
            "scraper_ids": [],
            "sources": [
              "erictest"
            ],
            "types": []
          },
          "match_types": [
            "ngram"
          ],
          "match_details": [
            {
              "matching_term": "cocaine",
              "matching_reason": "exact_match",
              "substring": "e cocaine and ",
              "substring_index": [
                14,
                27
              ]
            }
          ],
          "score": 49.624763
        }
      ]
    }
  }
}

Create a search to screen the reference of a payment

JSON POST PARAMETERS

FIELD TYPE TYPE DESCRIPTION
search_term (required, max 255 characters) String A string representing the payment reference
client_ref (required, max 255 characters)) String Your reference for the payment from which this reference originates. This is used to link your transactions to the searches in our system.
search_profile (required) String The identifier of a search profile (depending on the search profile this is either a slug or a profile id) that can be retrieved from the UI
fuzziness (optional) Float(0.0 to 1.0) Determines how closely the returned results must match the supplied name.

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.
  • types - listing types to include in search (array of "sanction", "warning", "pep" ( all pep classes), "pep-class-1", "pep-class-2", "pep-class-3", "pep-class-4","adverse-media" ( all crimes), "adverse-media-financial-crime" "adverse-media-violent-crime" "adverse-media-sexual-crime" "adverse-media-terrorism", "adverse-media-general")
  • birth_year - Year of birth for entity (note, this is a string)
  • remove_deceased - Removes deceased people when set to "1".

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:

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:

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:

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.

Event: kyb_screening_updated

Webhook example

{
  "event": "kyb_screening_updated",
  "data": {
    "id": "c7ab68e7",
    "companyInformation": {
      "id": "b5a6-d788b441d093",
      "provenance_id": "12345ABC",
      "provenance_uri": "http://complyadvantage.com/123456789abcdef",
      "name": "COMPANY NAME LTD",
      "address": "71-75 STREET NAME, MORE ADDRESS, CITY NAME",
      "status": "active",
      "incorporation_date": "2019-07-09",
      "name_of_registry": "Companies House",
      "country_of_registry": "United Kingdom",
      "type": "Private Limited Company",
      "industries": [
        {
          "type": "SIC2007",
          "code": "47410",
          "description": "Retail sale of computers, peripheral units and software in specialised stores"
        }
      ]
    },
    "shareholders": [
      {
        "level": 1,
        "owned": {
          "company": {
            "id": "9feed5d4",
            "name": "COMPANY NAME LIMITED"
          },
          "ownership": "25-50",
          "voting_rights": "25-50"
        },
        "person": {
          "date_of_birth": "1973-07",
          "id": "35a69680-5210-4b66",
          "name": "Person Name",
          "notified_on_date": "2016-04-06",
          "provenance_uri": "http://complyadvantage.com/123456789abcdef",
          "rights_percentage": {
            "max": 50,
            "min": 25
          },
          "share_percentage": {
            "max": 50,
            "min": 25
          }
        }
      }
    ],
    "officers": [
      {
        "id": "6f576366",
        "provenance_uri": "http://complyadvantage.com/123456789abcdef",
        "name": "John Doe",
        "nationality": "Serbian",
        "country_of_residence": "Serbia",
        "date_of_birth": "1992-01",
        "occupation": "Director"
      }
    ],
    "results": {
      "9feed5d4": {
        "results": [
          {
            "rule_id": "COSANC",
            "result": "FAIL",
            "description": "Evaluates whether the company has potential matches on Sanctions lists.",
            "context": [
              "some context string"
            ],
            "name": "company-sanctions"
          }
        ]
      }
    }
  }
}

{
  "event": "kyb_screening_updated",
  "data": {
    "id": "c7ab68e7",
    "companyInformation": {
      "id": "b5a6-d788b441d093",
      "provenance_id": "12345ABC",
      "provenance_uri": "http://complyadvantage.com/123456789abcdef",
      "name": "COMPANY NAME LTD",
      "address": "71-75 STREET NAME, MORE ADDRESS, CITY NAME",
      "status": "active",
      "incorporation_date": "2019-07-09",
      "name_of_registry": "Companies House",
      "country_of_registry": "United Kingdom",
      "type": "Private Limited Company",
      "industries": [
        {
          "type": "SIC2007",
          "code": "47410",
          "description": "Retail sale of computers, peripheral units and software in specialised stores"
        }
      ]
    },
    "shareholders": [
      {
        "level": 1,
        "owned": {
          "company": {
            "id": "9feed5d4",
            "name": "COMPANY NAME LIMITED"
          },
          "ownership": "25-50",
          "voting_rights": "25-50"
        },
        "person": {
          "date_of_birth": "1973-07",
          "id": "35a69680-5210-4b66",
          "name": "Person Name",
          "notified_on_date": "2016-04-06",
          "provenance_uri": "http://complyadvantage.com/123456789abcdef",
          "rights_percentage": {
            "max": 50,
            "min": 25
          },
          "share_percentage": {
            "max": 50,
            "min": 25
          }
        }
      }
    ],
    "officers": [
      {
        "id": "6f576366",
        "provenance_uri": "http://complyadvantage.com/123456789abcdef",
        "name": "John Doe",
        "nationality": "Serbian",
        "country_of_residence": "Serbia",
        "date_of_birth": "1992-01",
        "occupation": "Director"
      }
    ],
    "results": {
      "9feed5d4": {
        "results": [
          {
            "rule_id": "COSANC",
            "result": "FAIL",
            "description": "Evaluates whether the company has potential matches on Sanctions lists.",
            "context": [
              "some context string"
            ],
            "name": "company-sanctions"
          }
        ]
      }
    }
  }
}

{
  "event": "kyb_screening_updated",
  "data": {
    "id": "c7ab68e7",
    "companyInformation": {
      "id": "b5a6-d788b441d093",
      "provenance_id": "12345ABC",
      "provenance_uri": "http://complyadvantage.com/123456789abcdef",
      "name": "COMPANY NAME LTD",
      "address": "71-75 STREET NAME, MORE ADDRESS, CITY NAME",
      "status": "active",
      "incorporation_date": "2019-07-09",
      "name_of_registry": "Companies House",
      "country_of_registry": "United Kingdom",
      "type": "Private Limited Company",
      "industries": [
        {
          "type": "SIC2007",
          "code": "47410",
          "description": "Retail sale of computers, peripheral units and software in specialised stores"
        }
      ]
    },
    "shareholders": [
      {
        "level": 1,
        "owned": {
          "company": {
            "id": "9feed5d4",
            "name": "COMPANY NAME LIMITED"
          },
          "ownership": "25-50",
          "voting_rights": "25-50"
        },
        "person": {
          "date_of_birth": "1973-07",
          "id": "35a69680-5210-4b66",
          "name": "Person Name",
          "notified_on_date": "2016-04-06",
          "provenance_uri": "http://complyadvantage.com/123456789abcdef",
          "rights_percentage": {
            "max": 50,
            "min": 25
          },
          "share_percentage": {
            "max": 50,
            "min": 25
          }
        }
      }
    ],
    "officers": [
      {
        "id": "6f576366",
        "provenance_uri": "http://complyadvantage.com/123456789abcdef",
        "name": "John Doe",
        "nationality": "Serbian",
        "country_of_residence": "Serbia",
        "date_of_birth": "1992-01",
        "occupation": "Director"
      }
    ],
    "results": {
      "9feed5d4": {
        "results": [
          {
            "rule_id": "COSANC",
            "result": "FAIL",
            "description": "Evaluates whether the company has potential matches on Sanctions lists.",
            "context": [
              "some context string"
            ],
            "name": "company-sanctions"
          }
        ]
      }
    }
  }
}

This event is fired when a KYB screening has finished and has the results available.

The data payload is as follows:

FIELD TYPE DESCRIPTION
id String The ID of the KYB screening request.
companyInformation Dictionary The information about the company requested for screenig.
shareholders Array The shareholders for the screened company.
officers Array The officers for the screened company.
results Dictionary The results of the rules for the screened company.
javascript python json