NAV
Javascript

Introduction

The ComplyAdvantage API enables you to integrate your systems with our services to automate many of the functions available through the web user interface. Our API follows the REST convention and accepts and returns JSON data.

All requests should use the ComplyAdvantage root API URL (IP addresses of the API are dynamic) which can be found at:

https://api.complyadvantage.com/

All API requests must be made over HTTPS; calls made over plain HTTP will fail. API requests without authentication will also fail - see the Authentication section for information on correctly authenticating calls to the ComplyAdvantage API.

You can use any standard HTTPS client to access the web service. For simplicity and brevity we have provided code samples in this document in Javascript.

Language Suggested library
Javascript requests - https://www.npmjs.org/package/request

Authentication

                $ curl -XGET
                "
                    https://api.complyadvantage.com/users?api_key=<<.. your API key ..>>
                    "
                
            
                import json

                    import requests

url
                    =
                    "https://api.complyadvantage.com/users?api_key=<<.. your API key ..>>"
response
                    = requests.get(url
                    )
print response.json
                    ()
                
            
                var request = require
                    ('request')
                    ;var url
                    = "https://api.complyadvantage.com/users?api_key=<<.. your API key ..>>"
                    ;request(url, function
                    (error, response
                    , body)
                    {console.log(JSON.parse
                    (body))
                    ;
                    });
                
            
                   XGET -H
                       "Authorization: Token <.. your API key ..>>
                       " "
                       https://api.complyadvantage.com/users
                       "
                    
               
                import json

                    import requests

url =
                    "https://api.complyadvantage.com/users"
response
                    = requests.get(url, headers=
                    {'Authorization'
                    :
                    'Token <<.. your API key ..>>'}
                    )
print response.json()
                
            
                   var request
                       = require('request')
                       ; var options =
                       {url: "https://api.complyadvantage.com/users?api_key=<<.. your API key ..>>"
                       ,headers:
                       {'Authorization': 'Token <<.. your API key ..>>'
                       }
                       };
                        request(options, function
                       (error, response, body)
                       {console.
                       log(JSON.parse(body)
                       );
                        });

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:

The code examples illustrate the two integration methods.

Responses & errors

We use standard HTTP status codes to indicate the success or failure of a request to our API.

Successful requests to our API will have a 200 HTTP status code; the “status” and “content” key-value pairs will detail the status message and the content of the response.

{
  "status": "success",
  "content": "... API response goes here ..."
}

Unsuccessful requests to our API will have a non-200 HTTP status code and will contain "code", "message" and "status" fields. The "message" field will contain any further information about the unsucessful request.

{
  "code": 500,
  "message": "Internal Server Error",
  "status": "failure"
}

Note that the message may have more details about the error.

API Endpoints

The current list of available API endpoints on the ComplyAdvantage API is shown below. For a list of deprecated endpoints, please see the deprecated endpoints section.

Endpoint Description
GET /users Get a list of users in your account
GET /searches Get a list of your previous searches
POST /searches Create a new search
GET /searches/[id] Get an overview of one of your searches
GET /searches/[id]/details Get full search results of one of your searches
PATCH /searches/[id] Update details of one of your searches (eg, assigned user, status)
PATCH /searches/[id]/entities Update entities details (eg, is_whitelisted risk_level, match_status) of one of your searches
GET /searches/[id]/monitors Get monitored search details
PATCH /searches/[id]/monitors Update monitored search details (start/stop monitoring)

Concepts

Entities

                   {
                        "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 iedntical 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

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

Creating Searches

POST /searches

Create a new search by POSTing search terms, parameters and filters. By default creating a search will pull the first 100 results (if that many exist) from our database. By using the offset and limit parameters, you can expand this, or create multiple searches which "paginate" through our data sources.

Example Request 1

                   {
                        "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


               	// 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


        {
        "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 Description
search_term
required		 String/
Object		 A string representing the name of the entity or an Object (see examples)
client_ref
optional		 String Your reference for this person/entity for which you are searching. Used for tracking searches and auto-whitelisting recurring results
search_profile
optional		 String (*) The slug of any of your previously created search profiles, which can be found in the main platform UI for search profiles
fuzziness
optional		 Float
(0.0 to 1.0)		 Determines how closely the returned results must match the supplied name. Overridden by exact_match (see below)
offset
(optional)		 Integer
(default 0)		 Match results from the database, starting from the offset value
limit
(optional)		 Integer
(default 100, Max 100)		 Match results from the database, taking up to this many matches each search
filters
(optional)		 Object Specify filters within the search to narrow down the results. These are specified below, and are all optional
tags
(optional)		 Object Object of name => value pairs (name must be string)
share_url
(optional)		 Integer
0 or 1		 Include a shareable URL to access search publicly
country_codes
(optional)		 Array of
ISO 3166-1 alpha-2 strings		 Results are filtered by the entity nationality or country of residence
exact_match
(optional)		 Boolean Exact match disables all standard and optional matching behaviours (Honorifics, affixes, initials, glued name, name variation, equivalent names, extra words in entity,...) 0% fuzziness disables 1 letter typo matching but keeps all other matching behaviours (standard and optional)

Filters in searches



{
    "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.

Filter 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
  • 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
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: "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

{
    "content": {
    "data": {
    "id": 46,
    "ref": "1495711341-Tu51KL9s",
    "searcher_id": 1,
    "assignee_id": 1,
    "search_profile": {
    "name": "My USA Profile 1",
    "slug": "my-usa-profile-1"
    },
    "filters": {
    "entity_type": "person",
    "types": [
    "sanction",
    "warning"
    ],
    "birth_year": "1924",
    "passport": "AD10095",
    "exact_match": false,
    "fuzziness": 0.6
    },
    "match_status": "potential_match",
    "risk_level": "unknown",
    "search_term": "Robert Mugabe",
    "total_hits": 1,
    "updated_at": "2015-06-18 16:52:42",
    "created_at": "2015-06-18 16:52:42",
    "tags": {
    "name": "value"
    },
    "hits": [
    {
    "doc": {
    "aka": [
    ],
    "associates": [
    {
    "name": "Grace Mugabe",
    "association": "Spouse"
    }
    ],
    "entity_type": "person",
    "fields": [
    {
    "locale": "en",
    "name": "Justification",
    "source": "swiss-seco-list",
    "value": "Head of Government and responsible for activities that seriously undermine democracy, respect for human rights and the rule of law."
    },
    {
    "name": "Other Information",
    "source": "swiss-seco-list",
    "value": "President."
    },
    {
    "name": "Date of Birth",
    "source": "swiss-seco-list",
    "tag": "date_of_birth",
    "value": "1924"
    }
    ],
    "first_name": "Robert",
    "id": "RU4326M8GFUAHMF",
    "last_name": "Mugabe",
    "last_updated_utc": "2015-06-16T01:11:14Z",
    "middle_names": "Gabriel",
    "media": [
    {
    ""date": "2018-09-17T00:00:00Z",
"snippet": "- Mugabe's son-in-law under probe PRESIDENT Emmerson Mnangagwa's anti-corruption unit has reportedly opened investigations into former President Robert Mugabe's son-in-law, Simba Chikore's involvement in the botched ZimAirways deal, NewsDay can reveal. BY RICHARD CHIDZA Highly-placed sources told NewsDay last week that Chikore, married to Mugabe's daughter, Bona, is the subject of an investigation over his involvement in the purchase of aircraft under a ZimAirways deal.",
"title": "Mugabe's son-in-law under probe – The Zimbabwe Mail",
"url": "https://www.thezimbabwemail.com/law-crime/mugabes-son-in-law-under-probe/""
    }
    ],
    "name": "Mugabe Robert Gabriel",
    "sources": [
    "swiss-seco-list"
    ],
    "types": [
    "sanction"
    ]
    },
    "is_whitelisted": false,
    "match_types": [
    "name_exact",
    "year_of_birth"
    ],
    "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

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"
    },
    ...
    ]
    }
    }
}

When performing a search with no tag reference, the response will contain an array of empty tags as shown in the example.

Retrieving Searches

GET /Searches

Example Request (showing sorting and pagination)

GET /searches?api_key=YOURAPIKEY&per_page=20&page=2&sort_by=id&sort_dir=asc

Retrieve the previous searches on your account. This includes many options for pagination and filtering results.

Example Request (showing filtering)

GET /searches?api_key=YOURAPIKEY&match_status=potential_match,true_positive&assignee_id=15&created_at_from=2015-03-31

Example Response

{
    "content": {
    "data": [
    {
    "id": 20,
    "ref": "1495711341-Tu51KL9s",
    "searcher_id": 1,
    "assignee_id": 14,
    "filters": {
    "exact_match": false,
    "fuzziness": 1
    },
    "match_status": "potential_match",
    "risk_level": "medium",
    "search_term": "Hugo Jinkis",
    "total_hits": 1,
    "updated_at": "2015-06-16 09:58:22",
    "created_at": "2015-06-11 15:02:30"
    },
    {
    "id": 18,
    "ref": "1495711341-TuJJDF9s",
    "searcher_id": 1,
    "assignee_id": 1,
    "filters": {
    "exact_match": false,
    "fuzziness": 1
    },
    "match_status": "potential_match",
    "risk_level": "high",
    "search_term": "Vladimir Putin",
    "total_hits": 7,
    "updated_at": "2015-06-16 17:12:50",
    "created_at": "2015-06-11 14:45:11"
    }
    ]
    },
    "status": "success"
}

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 unsantised and includes symbols and punctuation marks
match_status Show searches where the match_status is one of the specified options: ('no_match', 'false_positive', 'potential_match', 'true_positive','unknown'). Use commas to separate multiple options, eg &match_status=potential_match,true_positive
search_term Searches that match search term (3 characters min)
created_at_from Searches made from date (yyyy-mm-dd)
created_at_to Searches made to date (yyyy-mm-dd)
tags Searches registered against given tags, comma separated represented as 'name:value', eg 'internal_ref:1234' or internal_ref:1234,t_type:custom'

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

GET /searches/46?api_key=YOURAPIKEY&share_url=1

Example Response

{
    "content": {
    "data": {
    "id": 20,
    "ref": "1495711341-Tu51KL9s",
    "searcher_id": 1,
    "assignee_id": 14,
    "search_profile": {
    "name":"My USA Profile 1",
    "slug":"my-usa-profile-1"
    },
    "filters": {
    "exact_match": false,
    "fuzziness": 1
    },
    "match_status": "potential_match",
    "risk_level": "medium",
    "search_term": "Hugo Jinkis",
    "total_hits": 1,
    "updated_at": "2015-06-16 09:58:22",
    "created_at": "2015-06-11 15:02:30",
    "share_url": "http://app.complyadvantage.com/public/search/1496748100-l9qHqbVF/64a6114f299b"
    }
    },
    "status": "success"
}

Retrieve a specific search on your account. For monitored searches, the original result will be updated with the latest results from the monitor runs.

URL Parameters

Field Description
id Either the numeric search ID, or the search REF

Query String Parameters

Field Description
share_url 1 or 0 - include a shareable URL in response.

GET /Searches/[id]/certificate

Example Request

GET /searches/46/certificate?api_key=YOURAPIKEY

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

GET /searches/46/details?api_key=YOURAPIKEY&share_url=1

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": "true_positive",
    "risk_level": "medium",
    "search_term": "Hugo Jinkis",
    "total_hits": 1,
    "updated_at": "2015-06-18 09:35:06",
    "created_at": "2015-06-11 15:02:30",
    "searcher": {
    "id": 1,
    "email": "teamadmin@example.com",
    "name": "Team Administrator",
    "phone": null,
    "created_at": "2015-06-11 12:05:14"
    },
    "assignee": {
    "id": 14,
    "email": "walton41@example.com",
    "name": "Jessyca Sporer",
    "phone": "1-628-245-5554x7640",
    "created_at": "2015-06-11 12:05:16"
    },
    "hits": [
    {
    "doc": {
    "aka": [
    ],
    "associates": [
    {
    "association": "Business Partner",
    "name": "Mariano Jinkis"
    }
    ],
    "entity_type": "person",
    "fields": [
    {
    "name": "Countries",
    "tag": "country_names",
    "value": "Argentina"
    },
    {
    "locale": "en",
    "name": "Description",
    "priority": "override",
    "source": "complyadvantage",
    "tag": "description",
    "value": "Controlling principal of Full Play Group S.A., a sports marketing business based in Argentina, and its affiliates."
    },
    {
    "locale": "en",
    "name": "Crime",
    "priority": "override",
    "source": "complyadvantage",
    "tag": "crime",
    "value": "Hugo Jinkis was one of the nine FIFA officials and five corporate executives indicted for racketeering conspiracy and corruption in May 2015."
    }
    ],
    "first_name": "Hugo",
    "id": "BYKUB1NQ8RPEC7T",
    "last_name": "Jinkis",
    "last_updated_utc": "2015-06-03T18:05:28Z",
    "name": "Hugo Jinkis",
    "media": [
    ],
    "sources": [
    "complyadvantage"
    ],
    "types": [
    ]
    },
    "match_types": [
    "name_exact"
    ],
    "score": 1.001
    }
    ],
    "share_url": "http://app.complyadvantage.com/public/search/1496748100-l9qHqbVF/64a6114f299b"
    }
    },
    "status": "success"
}

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

URL Parameters

Field Description
id Either the numeric search ID, or the search REF

Query String Parameters

Field Description
share_url 1 or 0 - include a shareable URL in response.

Updating Searches

PATCH /searches/[id]

Example Request

{
    "match_status": "false_positive",
    "risk_level": "low",
    "assignee_id": 123,
    "tags": {
    "MyTagName": "MyTagValue"
    }
}

Example Response - this is the overview of the newly updated search

{
    "content": {
    "data": {
    "id": 20,
    "ref": "1495711341-Tu51KL9s",
    "searcher_id": 1,
    "assignee_id": 14,
    "search_profile": {
    "name":"My USA Profile 1",
    "slug":"my-usa-profile-1"
    },
    "filters": {
    "exact_match": false,
    "fuzziness": 1
    },
    "match_status": "true_positive",
    "risk_level": "medium",
    "search_term": "Hugo Jinkis",
    "total_hits": 1,
    "updated_at": "2015-06-18 09:35:06",
    "created_at": "2015-06-11 15:02:30"
    }
    },
    "status": "success"
}

Update the assignee, status or risk level of a search.

URL Parameters

Field Description
id Either the numeric search ID, or the search REF

JSON PATCH Parameters

One or more of the following fields can be specified in the PATCH request.

Field Type Description
match_status String One of 'unknown', 'no_match', 'potential_match', 'false_positive', 'true_positive', 'true_positive_approve', 'true_positive_reject'
risk_level String One of 'low', 'medium', 'high', 'unknown'
assignee_id Integer The ID of the user to whom the case should be assigned
tags Object Object of name => value pairs ( name must be string )

PATCH /searches/[id]/entities

Example Request

{
    "entities": ["FRDG8ZC7VURPKP0","FRDG8ZC7VURPKP3"],
    "match_status": "false_positive",
    "risk_level": "low",
    "is_whitelisted": true
}

Example Response - this is the overview of the newly updated search

{
    "content": {
    "data": {
    "id": 46,
    "ref": "1495711341-Tu51KL9s",
    "searcher_id": 1,
    "assignee_id": 1,
    "filters": {
    "entity_type": "person",
    "types": [
    "sanction",
    "warning"
    ],
    "birth_year": "1924",
    "passport": "AD10095",
    "exact_match": false,
    "fuzziness": 0.6
    },
    "match_status": "potential_match",
    "risk_level": "unknown",
    "search_term": "Robert Mugabe",
    "total_hits": 1,
    "updated_at": "2015-06-18 16:52:42",
    "created_at": "2015-06-18 16:52:42",
    "tags": {
    "name": "value"
    }
    "hits": [
    {
    "doc": {
    "id": "FRDG8ZC7VURPKP0",
    // other data
    },
    "match_status": "false_positive",
    "is_whitelisted": true,
    "risk_level": "high",
    "match_types": [
    "name_exact",
    "year_of_birth"
    ],
    "score": 3.511
    },
    {
    "doc": {
    "id": "FRDG8ZC7VURPKP3",
    // other data
    },
    "match_status": "false_positive",
    "is_whitelisted": true,
    "risk_level": "high",
    "match_types": [
    "name_exact",
    "year_of_birth"
    ],
    "score": 3.511
    }
    ],
    "share_url": "http://app.complyadvantage.com/public/search/1496748100-l9qHqbVF/64a6114f299b"
    }
    },
    "status": "success"
}

Update the match-status of entities within a search result

URL Parameters

Field Description
id Either the numeric search ID, or the search REF

JSON PATCH Parameters

One or more of the following fields can be specified in the PATCH request.

Field Type Description
entities Array Array of entity ids to be updated (list of strings)
match_status String One of 'no_match', 'false_positive', 'potential_match', 'true_positive','unknown'
risk_level String One of 'low', 'medium', 'high', 'unknown'
is_whitelisted Boolean true or false

Monitored Searches

GET /searches/[id]/monitors

Example Request

GET /searches/1/monitors?api_key=YOURAPIKEY

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"
}

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

{
    "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"
}

Update the search monitors.

URL Parameters

Field Description
id Either the numeric search ID, or the search REF

JSON POST Parameters

One or more of the following fields can be specified in the PATCH request.

Field Type Description
is_monitored Boolean Start on true and stop on false. For monitored searches, the original search will be updated with the latest results from monitor runs.
monitored_by
(optional)		 Integer The ID of the user who will start/stop monitoring (please note if monitored_by is not provided all users will be affected )

GET /searches/[id]/monitors/differences

Example Request

GET /searches/1/monitor/differences?api_key=YOURAPIKEY&date=2018-07-02

Example Response - illustrates the return data from the request:

{
                        "content": [
                        {
                        "action": "added|removed|updated",
                        "name": "string",
                        "entity_id": "string",
                        "listing_types": [], // optional
                        "sources": [], // optional
                        "changes": { // optional
                        "listing_types": {
                        "removed": [],
                        "added": []
                        },
                        "sources": {
                        "removed": [],
                        "added": []
                        }
                        }
                        },
                        ],
                        "status": "success"
                    }

Retrieve the differences on the monitored search on a specific date.

URL Parameters

Field Description
id Either the numeric search ID, or the search REF
date (optional) The reference date (format: yyyy-mm-dd); if missing, the current day will be used

Other Endpoints

GET /users

Example 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"
                        }

Retrieves all the users in your account

Deprecated Endpoints

Deprecated Endpoints

The following endpoints have been deprecated but will remain available for the foreseeable future. Documentation and sample code for these endpoints is shown below for the sake of completeness only.

Endpoint Description
GET /entity/[entity_id] Retrieve an entity from the ComplyAdvantage database
POST /entity/search Create a new search
PATCH /searches/[id]/entity/[eid] Update the match-status of an entity within a search result

GET /entity/[entity_id]

DEPRECATED

Example Request

$ curl -XGET "https://api.complyadvantage.com/entity/KCVZXTP179KK5KY?api_key=<<.. your API 
                                                                                                                                                    
import json
    import requests

    url = "https://api.complyadvantage.com/entity/KCVZXTP179KK5KY?api_key=<<.. your API key ..>>"
    response = requests.get(url)
    print response.json()

var request = require('request');
                        var url = "https://api.complyadvantage.com/entity/KCVZXTP179KK5KY?api_key=<<.. your API key ..>>";
                        request(url, function (error, response, body) {
                        console.log(JSON.parse(body));
                    });

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 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/""
                        }
                        ],
                        "first_name": "Robert",
                        "middle_names": "Gabriel",
                        "last_name": "Mugabe",
                        "sources": [
                        "example-2-list"
                        ],
                        "types": [
                        "sanction",
                        "pep"
                        ]
                        },
                        "status": "success"
                    }

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

DEPRECATED

Example Request 1

{
                        "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"
                        }
}

Example Request 2

$ curl -XPOST "https://api.complyadvantage.com/entity/search?api_key=<<... your API key ...>>" -d '
                        {
                            "names": ["Robert Mugabe", "Qari Sahab"],
                            "fuzziness": 0
                        }'
import json
                        import requests

                        url = "https://api.complyadvantage.com/entity/search?api_key=<<.. your API key ..>>"
                        query = {
                        "names": ["Robert Mugabe", "Qari Sahab"],
                        "fuzziness": 0
                        }
                        response = requests.post(url, data=query)
                        print response.json()
                    
var request = require('request');
                        request(
                        {
                        url: "https://api.complyadvantage.com/entity/search?api_key=<<.. your API key ..>>",
                        method: "POST",
                        json: true,
                        body: {
                        names: ["Robert Mugabe", "Qari Sahab"],
                        fuzziness: 0
                        }
                        },
                        function (error, response, jsonBody) {
                        console.log(jsonBody);
                        });

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"
                }

Retrieves a list of entities specified according to JSON body criteria

JSON POST Parameters

The example shows that when POSTing to the /entity/search endpoint, there are multiple options available:

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]

DEPRECATED

{
    "content": {
    "entity_id": "FRDG8ZC7VURPKP0",
    "match_status": "false_positive",
    "client_ref": "CUST0011"
    },
    "status": "success"
}

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:

52.51.2.160
52.212.236.102
52.210.125.73
52.16.199.44

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

{
                    "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

{
                    "event": "search_status_updated",
                    "data": {
                    "changes": {
                    "before": {
                    "assigned_user": 123
                    },
                    "after": {
                    "assigned_user": 234
                    }
                    },
                    "ref": "1470903392-yS1UuFFF",
                    "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
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

Example Post

                
                    {
                    "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.
























Javascript