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:

EU: https://api.complyadvantage.com/
US: https://api.us.complyadvantage.com/
APAC: https://api.ap.complyadvantage.com/

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

You can use any standard HTTPS client to access the web service. For simplicity and brevity we have provided code samples in this document in Javascript and Python. axios library is used for JavaScript samples and requests library is used for Python samples, but any http client library can be used.

Language	Library for examples
JavaScript	`axios`
Python	`requests`

Authentication

Example

const axios = require('axios');

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

url = "https://api.complyadvantage.com/users"
response = requests.get(url, headers= {'Authorization': 'Token YOUR_API_KEY'})
print(response.json())

The ComplyAdvantage API uses API keys to authenticate requests. These API keys can be generated within the web platform and must be supplied with each request.

Your API keys can be used to perform a variety of actions against the API; whilst GET requests do not affect data in your account, the PATCH and POST requests can create, alter and reassign searches - so please ensure you follow best practice for managing API keys.

There is a raft of information about this on the web but in brief we suggest that you:

Keep the keys secure - do not share API keys or give them to parties outside your organisation
Rotate your API keys on a frequent basis
Never, ever store your API keys in publicly-accessible locations - public github repositories, client-side code, documentation files and so on

When making requests to the ComplyAdvantage API provide your API key in the Authorization header on the API request, e.g.

Token YOUR_API_KEY

The code examples illustrate this.

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.

By default, clients on a standard contract will be limited to 600 API calls per minute. Higher limits can be configured as appropriate for client volume. Sandbox accounts are limited to 300 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:

Make a request to the API.
If the request fails, wait 2 + random_number_milliseconds seconds and retry the request.
If the request fails, wait 4 + random_number_milliseconds seconds and retry the request.
If the request fails, wait 8 + random_number_milliseconds seconds and retry the request.
And so on, up to a maximum_backoff time.
Continue waiting and retrying up to some maximum number of retries, but do not increase the wait period between retries.

Where:

The wait time is min(((2^n)+random_number_milliseconds), maximum_backoff), with n incremented by 1 for each iteration (request), and starting with n=1.
random_number_milliseconds is a random number of milliseconds less than or equal to 1000.
maximum_backoff is typically 60 seconds.

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)
`PATCH /searches/{id}/search-profile`	Update the Search Profile associated to a monitored search
`POST /searches/{id}/monitor/acknowledge`	Acknowledge changes to a monitored search
`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`	Search for a company on KYB
`POST /kyb/v1/case`	Create a new KYB case
`POST /kyb/v1/case/{case_id}/tin-check`	Check a company's Tax Identification Number (TIN)

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.

Blacklisting

Internal lists (aka Blacklists) are lists that can be uploaded to our system through the UI.
These are additional lists to official sources like sanctions, and they include individuals or companies you do not want to do business with due to previous experience or other reasons.

You will see these properties in your responses such as blacklist_hits,total_blacklist_hits,blacklist_filters

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 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';
const data = {
  "search_term": "A Bad Company Ltd",
  "fuzziness": 0.6,
  "filters": {
      "types": [
          "sanction",
          "warning"
      ]
  },
  "tags": {
      "name": "value"
  },
  "share_url": 1
};
const headers= {"Authorization": "Token YOUR_API_KEY"};

axios.post(url, data, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches"
data = {
  "search_term": "A Bad Company Ltd",
  "fuzziness": 0.6,
  "filters": {
    "types": [
      "sanction",
      "warning"
    ]
  },
  "tags": {
    "name": "value"
  },
  "share_url": 1
}
headers = {'Authorization': 'Token YOUR_API_KEY'}

response = requests.post(url, json=data, headers=headers)
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';
const headers = {'Authorization': 'Token YOUR_API_KEY'};

// search_term format 1
const data1 = {
  "search_term": "Robert Gabriel Mugabe",
  "client_ref": "CUST000456",
  "fuzziness": 0.6,
  "search_profile": "401e33e7-77ac-4410-990f-455761bed6c8",
  "filters": {
      "birth_year": "1924",
      "entity_type": "person",
      "country_codes": ["BD", "LK"]
  },
  "share_url": 1
};
axios.post(url, data1, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

// search_term format 2
// last_name is compulsory in this format
// middle_names and first_name are optional

const data2 = {
  "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
};
axios.post(url, data2, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches"
headers = {"Authorization": "Token YOUR_API_KEY"}

# search_term format 1
data1 = {
  "search_term": "Robert Gabriel Mugabe",
  "client_ref": "CUST000456",
  "fuzziness": 0.6,
  "search_profile": "401e33e7-77ac-4410-990f-455761bed6c8",
  "filters": {
    "birth_year": "1924",
    "entity_type": "person",
    "country_codes": ["BD", "LK"]
  },
  "share_url": 1
}
response = requests.post(url, json=data1, headers=headers)
print(response.json())

# search_term format 2
# last_name is compulsory in this format
# middle_names and first_name are optional
data2 = {
  "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
}
response = requests.post(url, json=data2, headers=headers)
print(response.json())

# search_term format 1
{
  "search_term": "Robert Gabriel Mugabe",
  "client_ref": "CUST000456",
  "fuzziness": 0.6,
  "search_profile": "401e33e7-77ac-4410-990f-455761bed6c8",
  "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';
const data = {
  "search_term": "Robert Gabriel Mugabe",
  "client_ref": "CUST000456",
  "exact_match": true,
  "search_profile": "401e33e7-77ac-4410-990f-455761bed6c8",
  "filters": {
      "birth_year": "1924",
      "entity_type": "person",
      "country_codes": [
          "BD",
          "LK"
      ]
  },
  "share_url": 1
};
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.post(url, data, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches"
data = {
  "search_term": "Robert Gabriel Mugabe",
  "client_ref": "CUST000456",
  "exact_match": True,
  "search_profile": "401e33e7-77ac-4410-990f-455761bed6c8",
  "filters": {
    "birth_year": "1924",
    "entity_type": "person",
    "country_codes": [
      "BD",
      "LK"
    ]
  },
  "share_url": 1
}
headers= {"Authorization": "Token YOUR_API_KEY"}

response = requests.post(url, json=data, headers=headers)
print(response.json())

{
  "search_term": "Robert Gabriel Mugabe",
  "client_ref": "CUST000456",
  "exact_match": true,
  "search_profile": "401e33e7-77ac-4410-990f-455761bed6c8",
  "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 Profile ID of a search profile 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
`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
`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)

The full range of filters parameters available is outlined below and are all optional 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(*optional)|Array of ISO 3166-1 alpha-2 strings|Results are filtered by the entity country of operation or office.
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.

Filters in searches

Filters example

const url = 'https://api.complyadvantage.com/searches';
const data = {
  "search_term": {
      "last_name": "Mugabe",
      "middle_names": "Gabriel",
      "first_name": "Robert"
  },
  "client_ref": "CUST000456",
  "fuzziness": 0.6,
  "filters": {
      "types": [
          "sanction",
          "warning"
      ],
      "birth_year": "1924"
  },
  "share_url": 1
};
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.post(url, data, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches"
data = {
  "search_term": {
    "last_name": "Mugabe",
    "middle_names": "Gabriel",
    "first_name": "Robert"
  },
  "client_ref": "CUST000456",
  "fuzziness": 0.6,
  "filters": {
    "types": [
      "sanction",
      "warning"
    ],
    "birth_year": "1924"
  },
  "share_url": 1
}
headers= {"Authorization": "Token YOUR_API_KEY"}

response = requests.post(url, json=data, headers=headers)
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 country of operation or office. 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:

query_term

A cleaned word from your search term

match_types

A list of ways that word matched. Possible match types are: exact_match The word exactly matched a word in the matching_name

edit_distance The word was a single insertion/deletion/replacement/transposition away from a word in the matching_name

phonetic Phonetic token(s) of word matched the phonetic token(s) of a word in the matching_name

equivalent_name An equivalent name matched a word in the matching_name

word_to_initial The first letter of the word matched an initial in the matching_name

initial_to_word Initial matched the first letter of a word in the matching name

removed_spaces Concatenating this word with others in the search_term matched a word in the matching_name

word_to_digit The digit representation of this number occurs in the matching name

digit_to_word The word representation of this number occurs in the matching name

name_variations_removal The word was allowed to be missing from hit as part of name_variations behaviour

removed_personal_title The word was identified as a personal title and was stripped from the search term

removed_personal_suffix The word was identified as a personal suffix and was stripped from the search term

removed_organisation_prefix The word was identified as an organisation prefix and was stripped from the search term

removed_organisation_suffix The word was identified as a organisation suffix and was stripped from the search term

removed_clerical_mark The word was identified as a clerical mark and was stripped from the search term

secondary_matches

A breakdown of how other information (e.g. birth_year) supplied with a search matched the matching_name

query_term

A secondary piece of information from your query

match_types

A list of ways that term matched. Possible match types are:

exact_birth_year_match The supplied birth_year matched exactly with one attached to the entity

fuzzy_birth_year_match The supplied birth_year fell within the allowed range of one attached to the entity

Retrieving Searches

GET /searches

Example Request (showing filtering)

const url = 'https://api.complyadvantage.com/searches?match_status=potential_match,true_positive&assignee_id=15&created_at_from=2015-03-31';
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.get(url, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches?match_status=potential_match,true_positive&assignee_id=15&created_at_from=2015-03-31"
headers = {"Authorization": "Token YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json())

Example Request (showing token-based pagination)

const url = 'https://api.complyadvantage.com/searches?page=2\u0026per_page=10\u0026token=61f7ab64078dcb6c1b44706e_10_2_f79a3c98ef179dedc1d275e4f69d8aa6';
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.get(url, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches?page=2\u0026per_page=10\u0026token=61f7ab64078dcb6c1b44706e_10_2_f79a3c98ef179dedc1d275e4f69d8aa6"
headers = {"Authorization": "Token YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json())

Example Request (showing sorting and common pagination)

const url = 'https://api.complyadvantage.com/searches?per_page=20&page=2&sort_by=id&sort_dir=asc';
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.get(url, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches?per_page=20&page=2&sort_by=id&sort_dir=asc"
headers = {"Authorization": "Token YOUR_API_KEY"}

response = requests.get(url, headers=headers)
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"
      }
    ]
  },
  "links": {
    "next": "/searches?page=3\u0026per_page=10\u0026token=61f7ab64078dcb6c1b44706e_10_3_f79a3c98ef179dedc1d275e4f69d8aa6",
    "previous": "/searches?page=1\u0026per_page=10\u0026token=61f7ab64078dcb6c1b44706e_10_1_f79a3c98ef179dedc1d275e4f69d8aa6"
  }
  "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"
      }
    ]
  },
  "links": {
    "next": "/searches?page=3\u0026per_page=10\u0026token=61f7ab64078dcb6c1b44706e_10_3_f79a3c98ef179dedc1d275e4f69d8aa6",
    "previous": "/searches?page=1\u0026per_page=10\u0026token=61f7ab64078dcb6c1b44706e_10_1_f79a3c98ef179dedc1d275e4f69d8aa6"
  }
  "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"
      }
    ]
  },
  "links": {
    "next": "/searches?page=3\u0026per_page=10\u0026token=61f7ab64078dcb6c1b44706e_10_3_f79a3c98ef179dedc1d275e4f69d8aa6",
    "previous": "/searches?page=1\u0026per_page=10\u0026token=61f7ab64078dcb6c1b44706e_10_1_f79a3c98ef179dedc1d275e4f69d8aa6"
  }
  "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
`tags_logical_operator`	Values can be set as 'OR' or 'AND'. Used when multiple tags assigned in search. 'AND' - returns searches where all tags match. 'OR' - returns searches where at least one tag matches (default).
`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

Token-based Pagination

When retrieving searches, the response will contain a HATEOAS links object with next and previous urls. To fetch the next page of results, simply call this next url.

This will efficiently retrieve all searches from the account.

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)

Common Pagination

The following parameters can be applied to the querystring to paginate the data returned, without using the next url (i.e. just incrementing the page_number).

However this is not efficient and is restricted to 10,000 records as a result.

FIELD	DESCRIPTION
`per_page`	Number of searches to return per "page" (integer, max 100)
`page`	Which page to fetch (integer)

Notes on Token-Based and Common Pagination

There is no difference when fetching Page 1
In Token-based pagination, the previous url is returned for page 2 and above; the previous is not present when fetching page 1
In Token-based pagination, records are sorted in the order stored in the database; no sort_by parameter can be specified
Common pagination will be limited to 10,000 records and will return an error if surpassed (e.g. where per_page is 100 and page is 101)

GET /searches/{id}

Example Request

const url = 'https://api.complyadvantage.com/searches/46?share_url=1';
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.get(url, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches/46?share_url=1"
headers = {"Authorization": "Token YOUR_API_KEY"}

response = requests.get(url, headers=headers)
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/{ref}/entities/{entity_provider}

Retrieve the available entities of a search.

URL PARAMETERS

FIELD	DESCRIPTION
`ref`	The REF of the search
`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?match_status=potential_match,true_positive&assignee_id=15&created_at_from=2015-03-31';
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.get(url, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches/123456/entities/comply?match_status=potential_match,true_positive&assignee_id=15&created_at_from=2015-03-31"
headers = {"Authorization": "Token YOUR_API_KEY"}

response = requests.get(url, headers=headers)
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';
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.get(url, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches/46/certificate"
headers = {"Authorization": "Token YOUR_API_KEY"}

response = requests.get(url, headers=headers)
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?share_url=1';
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.get(url, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches/1597743203-T7ddoU4M/details?share_url=1"
headers = {"Authorization": "Token YOUR_API_KEY"}

response = requests.get(url, headers=headers)
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": {
        "TagName": "value"
      },
      "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": {
        "TagName": "value"
      },
      "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": {
        "TagName": "value"
      },
      "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';
const data = {
    "match_status": "false_positive",
    "risk_level": "low",
    "assignee_id": 123,
    "limit": 50,
    "tags": {
        "MyTagName": "MyTagValue"
    }
};
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.patch(url, data, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches/46"
data = {
  "match_status": "false_positive",
  "risk_level": "low",
  "assignee_id": 123,
  "limit": 50,
  "tags": {
    "MyTagName": "MyTagValue"
  }
}
headers = {"Authorization": "Token YOUR_API_KEY"}

response = requests.patch(url, json=data, headers=headers)
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';
const data = {
    "entities": [
        "FRDG8ZC7VURPKP0",
        "FRDG8ZC7VURPKP3"
    ],
    "match_status": "false_positive",
    "risk_level": "low",
    "is_whitelisted": true
}
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.patch(url, data, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches/46/entities"
data = {
  "entities": [
    "FRDG8ZC7VURPKP0",
    "FRDG8ZC7VURPKP3"
  ],
  "match_status": "false_positive",
  "risk_level": "low",
  "is_whitelisted": True
}
headers = {"Authorization": "Token YOUR_API_KEY"}

response = requests.patch(url, json=data, headers=headers)
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.

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';
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.delete(url, {headers: headers})
    .then((response) => {
        console.log(response.status);
    });

url = "https://api.complyadvantage.com/searches/46"

response = requests.delete(
    url,
    headers={"Authorization": "Token YOUR_API_KEY"}
)
print(response.status_code)

Example Response

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';
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.get(url, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches/1/monitors"
headers = {"Authorization": "Token YOUR_API_KEY"}

response = requests.get(url, headers=headers)
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';
const data = {
  "is_monitored": false,
};
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.patch(url, data, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches/1/monitors"
headers = {"Authorization": "Token YOUR_API_KEY"}

response = requests.patch(
  url, 
  json={"is_monitored": False},
  headers={"Authorization": "Token YOUR_API_KEY"},
)
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?date=2018-07-02';
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.get(url, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches/1/monitor/differences?date=2018-07-02"
headers = {"Authorization": "Token YOUR_API_KEY"}

response = requests.get(url, headers=headers)
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

POST /searches/{id}/monitor/acknowledge

Example Request

const url = 'https://api.complyadvantage.com/searches/1/monitor/acknowledge';
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.post(url, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches/1/monitor/acknowledge"
headers = {"Authorization": "Token YOUR_API_KEY"}

response = requests.post(url, headers=headers)
print(response.json())

Example Response - illustrates the return data from the request:

Acknowledge changes to a monitored search

URL PARAMETERS

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

PATCH /searches/{id}/search-profile

Example Request - update the search_profile.id (from a2a5f87b-cc98-4038-8a90-44b2387d9362) for search 1624979504-Hb3XZCQj to 6a6365af-e75b-42ef-ab5a-eaa3f15a03cd

const url = "https://api.complyadvantage.com/searches/1624979504-Hb3XZCQj/search-profile";
const new_search_profile_id = "6a6365af-e75b-42ef-ab5a-eaa3f15a03cd";
const data = {"search_profile": {
    "id": new_search_profile_id
}};
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.patch(url, data, {headers: headers})
    .then((response) => {
        console.log(JSON.stringify(response.data));
    });

url = "https://api.complyadvantage.com/searches/1624979504-Hb3XZCQj/search-profile"
new_search_profile_id = "6a6365af-e75b-42ef-ab5a-eaa3f15a03cd"
data = {"search_profile": {"id": new_search_profile_id}}
headers = {"Authorization": "Token YOUR_API_KEY"}

response = requests.patch(url, json=data, headers=headers)
print(response.json())

{
    "search_profile": {
        "id": "6a6365af-e75b-42ef-ab5a-eaa3f15a03cd"
    }
}

Example Response - succesfully updated search 1624979504-Hb3XZCQj to use search_profile.id 6a6365af-e75b-42ef-ab5a-eaa3f15a03cd

{
    "status": "success",
    "code": 200,
    "content": {
        "data": {
            "search_profile": {
                "id": "6a6365af-e75b-42ef-ab5a-eaa3f15a03cd",
                "version": 2
            },
            "ref": "1624979504-Hb3XZCQj"
        }
    }
}

{
    "status": "success",
    "code": 200,
    "content": {
        "data": {
            "search_profile": {
                "id": "6a6365af-e75b-42ef-ab5a-eaa3f15a03cd",
                "version": 2
            },
            "ref": "1624979504-Hb3XZCQj"
        }
    }
}

{
    "status": "success",
    "code": 200,
    "content": {
        "data": {
            "search_profile": {
                "id": "6a6365af-e75b-42ef-ab5a-eaa3f15a03cd",
                "version": 2
            },
            "ref": "1624979504-Hb3XZCQj"
        }
    }
}

Update the search profile associated to a monitored search.

Pre-requisites:

Search must be monitored
The current search profile associated to the search has not been edited in the past 48 hours

URL PARAMETERS

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

Retrieving the Search Profile Id

The (search) Profile Id is available on the Search Profile section of the UI.

If the Search Profiles displays Slug instead of the (search) Profile Id in the UI, the (search) Profile Id can be retrieved from the URL, as is shown in bold below.

https://app.complyadvantage.com/#/enhanced-search-profiles/fb4c2b61-7ec7-4d7c-8805-7e0dcf41328a/2

JSON PATCH PARAMETERS

One field is required for this PATCH request.

FIELD	TYPE	DESCRIPTION
`search_profile`	Object	Value must match schema `{"id" : "search_profile_id"}`

Error codes

Code	Status	Message	Troubleshooting
400	failure	search not found	Ensure the search ID, or the search REF is correct.
400	failure	search is not monitored	Ensure the search has `is_monitored` set to `true`.
400	failure	cannot decode JSON body of request	Ensure the body of the request is valid JSON and matches this schema `{"search_profile": {"id" : "search_profile_id"}}`
400	failure	search_profile.id invalid in JSON body of request	See Retrieving the Search Profile Id section above.
400	failure	current search profile id 'a2a5f87b-cc98-4038-8a90-44b2387d9362' associated to search '1624979504-Hb3XZCQj' was modified within 48 hours.	See when the Search Profile you want to replace was last edited in the UI via `Settings - Search Profiles`

Comments

POST /searches/{id}/comments

Example Request for comment on search

const url = 'https://api.complyadvantage.com/searches/1594889804-eVSo1JXO/comments';
const data = {"comment": "test comment on search"};
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.post(url, data, {headers: headers});

url = "https://api.complyadvantage.com/searches/1594889804-eVSo1JXO/comments"

response = requests.post(
  url,
  json={"comment": "test comment on search"},
  headers={"Authorization": "Token YOUR_API_KEY"},
)
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';
const data = {
    "comment": "test comment on entity",
    "entity_id": "NAG9ONPS86191L1"
};
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.post(url, data, {headers: headers});

url = "https://api.complyadvantage.com/searches/1594889804-eVSo1JXO/comments"

response = requests.post(
  url, 
  json={
    "comment": "test comment on entity",
    "entity_id": "NAG9ONPS86191L1"
  },
  headers={"Authorization": "Token YOUR_API_KEY"},
)
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 timestamp 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';
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.get(url, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches/1594889804-eVSo1JXO/comments"

response = requests.get(url, headers={"Authorization": "Token YOUR_API_KEY"})
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';
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.delete(url, {headers: headers})
    .then((response) => {
        console.log(response.status);
    });

url = "https://api.complyadvantage.com/searches/46/tags/MY_TAG"

response = requests.delete(
    url,
    headers={"Authorization": "Token YOUR_API_KEY"},
)
print(response.status_code)

Example Response

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.

KYB

Overview

KYB (Know your business) enables you to efficiently onboard business customers in an all-in-one solution.

The API journey has 3 steps:

Search for a company (optional)
Create a case. This triggers an asynchronous screening task.
Receive a webhook with results

An optional 4th step is available for US companies: check the Tax Identification Number

Risks tested

Screening tasks check the following rules:

Rule Code	Rule description
COSANC	Company is sanctioned
COAM	Company has adverse media
COHRI	Company is active in high risk industries
CORHRC	Company is incorporated in a high risk country
COAC	Company is not active
COINC	Company was recently incorporated
OSANC	Officer is sanctioned
OPEP	Officer is a PEP
OAM	Officer has adverse media
SHSANC	Controlling Entity is sanctioned
SHPEP	Controlling Entity is a PEP
SHAM	Controlling Entity has adverse media
SHHRC	Controlling Entity operates in a high risk country

Search for a company

Search by company name

const url = 'https://api.complyadvantage.com/kyb/v1/search';
const headers = {'Authorization': 'Token YOUR_API_KEY'};
data = {
  "name": "Example Inc",
  "incorporation_jurisdiction_code": "GB"
};

axios.post(url, data, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/kyb/v1/search"
headers = {'Authorization': 'Token YOUR_API_KEY'}
data = {
  "name": "Example Inc",
  "incorporation_jurisdiction_code": "GB"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

{
    "name": "Example Inc",
    "incorporation_jurisdiction_code": "GB"
}

Search by company id

const url = 'https://api.complyadvantage.com/kyb/v1/search';
const headers = {'Authorization': 'Token YOUR_API_KEY'};
data = {
  "company_id": "abc12345",
  "incorporation_jurisdiction_code": "GB"
};

axios.post(url, data, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/kyb/v1/search"
headers = {'Authorization': 'Token YOUR_API_KEY'}
data = {
  "company_id": "abc12345",
  "incorporation_jurisdiction_code": "GB"
}
response = requests.post(url, json=data, headers=headers)
print(response.json())

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

POST /kyb/v1/search - search for a company by id or name.

JSON POST PARAMETERS

Field	Type	Description
`name`	String	The name of the company to search for
`company_id`	String	The id of the company to search for
`incorporation_jurisdiction_code`*	String	The jurisdiction the company is incorporated in. Country level jurisdictions should be an ISO 3166-1 alpha-2 country code, e.g. `FR` for France. For the United States, please use the ISO 3166-2 code for the relevant state, e.g. `US-TX` for Texas. In Canada, please use `CA` for the Federal level, or the ISO 3166-2 code for the relevant territory e.g. `CA-ON` for Ontario See also list of country codes

* Indicates mandatory fields

Notes

Only one of name or company_id should be provided.
company_id is case-sensitive.
When searching by name, the maximum number of companies returned is 250.
Some countries have registries at the subdivision level (e.g. the US). These can only be searched by specifying the subdivision (e.g. US-TX); searching for the top level US will not search over them.

Company Search Response

{
  "data": [
    {
      "company_id": "abc12345",
      "name": "Example Inc.",
      "address": "Street, Number, City, PostalCode",
      "incorporation_jurisdiction": "United Kingdom",
      "status": "active"
    }
  ],
  "links": []
}

{
  "data": [
    {
      "company_id": "abc12345",
      "name": "Example Inc.",
      "address": "Street, Number, City, PostalCode",
      "incorporation_jurisdiction": "United Kingdom",
      "status": "active"
    }
  ],
  "links": []
}

{
  "data": [
    {
      "company_id": "abc12345",
      "name": "Example Inc.",
      "address": "Street, Number, City, PostalCode",
      "incorporation_jurisdiction": "United Kingdom",
      "status": "active"
    }
  ],
  "links": []
}

RESPONSE SCHEMA

A list of matched companies is returned.

Field	Type
`company_id`	String
`name`	String
`address`	String
`incorporation_jurisdiction`	String
`status`	String

Create a case

Create a KYB case, providing 'client_ref'

const url = 'https://api.complyadvantage.com/kyb/v1/case';
const headers = {'Authorization': 'Token YOUR_API_KEY'};
const data = {
  "company_id": "123456",
  "incorporation_jurisdiction_code": "gb",
  "client_ref": "test-client-1"
};

axios.post(url, data, {headers: headers}).then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/kyb/v1/case"
headers = {'Authorization': 'Token YOUR_API_KEY'}
data = {
  "company_id": "123456",
  "incorporation_jurisdiction_code": "gb",
  "client_ref": "test-client-1"
}

response = requests.post(url json=data, headers=headers)
print(response.json())

{
    "company_id": "123456",
    "incorporation_jurisdiction_code": "gb",
    "client_ref": "test-client-1"
}

Create a KYB case, providing a controlling entity

const url = 'https://api.complyadvantage.com/kyb/v1/case';
const headers = {'Authorization': 'Token YOUR_API_KEY'};
data = {
  "company_id": "123456",
  "incorporation_jurisdiction_code": "gb",
  "controlling_entities": [
    {
      "entity_type": "person",
      "person_name": "John Smith"
    }
  ]
};

axios.post(url, data, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/kyb/v1/case"
headers = {'Authorization': 'Token YOUR_API_KEY'}
data = {
  "company_id": "123456",
  "incorporation_jurisdiction_code": "gb",
  "controlling_entities": [
    {
      "entity_type": "person",
      "person_name": "John Smith",
    }
  ]
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

{
    "company_id": "123456",
    "incorporation_jurisdiction_code": "gb",
    "controlling_entities": [
        {
            "entity_type": "person",
            "person_name": "John Smith"
        }
    ]
}

POST /kyb/v1/case - create a KYB case for a company.

If you already know the officers and/or controlling entities (beneficial owners and shareholders), then add them to the request and they will be made part of the case and screened.

The outcome of the screening task for the case will be a webhook.

JSON POST PARAMETERS

Field	Type	Description
`company_id`*	String
`incorporation_jurisdiction_code`*	String	The jurisdiction the company is incorporated in. Country level jurisdictions should be an ISO 3166-1 alpha-2 country code, e.g. `FR` for France. For the United States, please use the ISO 3166-2 code for the relevant state, e.g. `US-TX` for Texas. In Canada, please use `CA` for the Federal level, or the ISO 3166-2 code for the relevant territory e.g. `CA-ON` for Ontario See also list of country codes
`client_ref`	String	A reference for the KYB case, used for tracking searches made on behalf of the case. May contain only alphanumeric characters, spaces, dashes and underscores.
`officers`	List[Object]	See Entity model
`controlling_entities`	List[Object]	See Entity model

* Indicates mandatory fields

'Create a case' response

{
  "data": {
    "screening_id": 321,
    "case_id": 1234,
    "created_by": {
      "user_id": 1,
      "user_name": "test"
    },
    "uploaded_entities": {
      "officers": [],
      "controlling_entities": [
        {
          "entity_id": "a0e3ec3d-d94a-49d9-9189-d82caefa0415",
          "entity_type": "person",
          "person_name": "John Smith"
        }
      ]
    }
  },
  "links": []
}

{
  "data": {
    "screening_id": 321,
    "case_id": 1234,
    "created_by": {
      "user_id": 1,
      "user_name": "test"
    },
    "uploaded_entities": {
      "officers": [],
      "controlling_entities": [
        {
          "entity_id": "a0e3ec3d-d94a-49d9-9189-d82caefa0415",
          "entity_type": "person",
          "person_name": "John Smith"
        }
      ]
    }
  },
  "links": []
}

{
  "data": {
    "screening_id": 321,
    "case_id": 1234,
    "created_by": {
      "user_id": 1,
      "user_name": "test"
    },
    "uploaded_entities": {
      "officers": [],
      "controlling_entities": [
        {
          "entity_id": "a0e3ec3d-d94a-49d9-9189-d82caefa0415",
          "entity_type": "person",
          "person_name": "John Smith"
        }
      ]
    }
  },
  "links": []
}

RESPONSE SCHEMA

The response includes case_id, which is the ID KYB assigned to the case.

Uploaded entities are echoed back with a new field entity_id. This is the key under which rule results will appear in the webhook for the uploaded entity.

Entity Model

Minimal entity model for case creation, to run all KYB Rules

Please refer to json section.

Please refer to json section.

{
  "controlling_entities": [
    {
      "entity_type": "company",
      "company_name": "COMPANY NAME TWO LIMITED",
      "relationships": [
        {
          "registered_address_country": "GB"
        }
      ]
    }
  ],
  "officers": [
    {
      "entity_type": "person",
      "person_name": "JOHN DOE",
    }
  ]
}

Complete entity model for case creation, for full UI population

Please refer to json section.

Please refer to json section.

{
  "controlling_entities": [
    {
      "entity_type": "company",
      "company_name": "COMPANY NAME TWO LIMITED",
      "relationships": [
        {
          "natures_of_control": [
            {
              "category": "ownership",
              "description": "ownership-of-shares-75-to-100-percent",
              "max_percent": 100,
              "min_percent": 75
            }
          ],
          "registered_address": "71-75 STREET NAME, MORE ADDRESS, CITY NAME",
          "registered_address_country": "US",
          "notified_date": "2017-10-01",
          "start_date": "2017-09-19"
        }
      ]
    }
  ],
  "officers": [
    {
      "entity_type": "person",
      "person_name": "JOHN DOE",
      "country_of_residence": "UNITED KINGDOM",
      "date_of_birth": "1966-07",
      "nationality": "BRITISH",
      "profession": "COMPANY DIRECTOR",
      "provenance": {
        "source": "complyadvantage"
      },
      "relationships": [
        {
          "position": "Current Director",
          "appointed_date": "2021-05-01",
          "correspondence_address": "71-75 STREET NAME, MORE ADDRESS, CITY NAME",
          "correspondence_address_country": "GB",
          "notified_date": "2021-06-01"
        }
      ]
    }
  ]
}

Entity model returned by webhook, including extra metadata

Please refer to json section.

Please refer to json section.

{
  "controlling_entities": [
    {
      "entity_id": "b9d84a25-06f1-4a9a-87c2-9c806c9f988f",
      "entity_type": "company",
      "company_name": "COMPANY NAME TWO LIMITED",
      "provenance": {
        "source": "complyadvantage"
      },
      "relationships": [
        {
          "target_entity_id": "911f8e73-a779-420e-ac34-36f0f9cf3778",
          "natures_of_control": [
            {
              "category": "ownership",
              "description": "ownership-of-shares-75-to-100-percent",
              "max_percent": 100,
              "min_percent": 75
            }
          ],
          "registered_address": "71-75 STREET NAME, MORE ADDRESS, CITY NAME",
          "registered_address_country": "United States",
          "notified_date": "2017-10-01",
          "start_date": "2017-09-19"
        }
      ]
    }
  ],
  "officers": [
    {
      "entity_id": "1281fe78-50a2-48db-8ac2-489582920697",
      "entity_type": "person",
      "person_name": "JOHN DOE",
      "country_of_residence": "UNITED KINGDOM",
      "date_of_birth": "1966-07",
      "nationality": "BRITISH",
      "profession": "COMPANY DIRECTOR",
      "provenance": {
        "source": "complyadvantage"
      },
      "relationships": [
        {
          "target_entity_id": "911f8e73-a779-420e-ac34-36f0f9cf3778",
          "position": "Current Director",
          "appointed_date": "2021-05-01",
          "correspondence_address": "71-75 STREET NAME, MORE ADDRESS, CITY NAME",
          "correspondence_address_country": "United Kingdom",
          "notified_date": "2012-06-01"
        }
      ]
    }
  ]
}

Uploading entities to a case, and viewing entities on webhooks share the same model.

Most fields are optional for case creation and do not have to be set.

`Entity` schema

The fields officers and controlling_entities contain a list of Entity objects.

Entity objects are either Company or Person, and can be resolved by reading the value of entity_type.

The relationships field lets you provide fields specific to being an officer or controlling entity, to any Company or Person.

Entity objects returned by KYB contain an entity_id; this cannot be provided during case creation.

`Company` schema

Field	Type	Description
`entity_type`*	String	Must have the value `company`
`company_name`*	String
`entity_id`	String	An ID generated by KYB
`relationships`	List[Object]	See relationship schema
`provenance`	Object	See provenance schema

`Person` schema

Field	Type	Description
`entity_type`*	String	Must have the value `person`
`person_name`*	String
`entity_id`	String	An ID generated by KYB
`country_of_residence`	String
`date_of_birth`	String
`nationality`	String
`profession`	String	The occupation of the person
`relationships`	List[Object]	See relationship schema
`provenance`	Object	See provenance schema

`Provenance` schema

Only relevant for webhook entities.

Entities provided at case creation can be distinguished from entities found by KYB by looking at provenance

Field	Type	Description
`source`	String	`client` for entities provided at case creation. `complyadvantage` for entities found by KYB

`Relationship` schema

Entity objects contain a list of Relationship objects.

Relationship objects are either Officer or Controlling Entity.

`Officer` schema

An officer of a company, such as a Director.

Field	Type	Description
`position`	String	Role of the officer. E.g. `director`
`appointed_date`	String	Date of assuming the role
`notified_date`	String	Date registry was notified of the role being assumed
`correspondence_address`	String	Address of correspondence for the officer
`correspondence_address_country` †	String	Country of correspondence address for the officer

Notes

† During case creation, ISO-3166 alpha 2 codes may be provided instead of full country name, and are preferred

`Controlling Entity` schema

An entity with control in a company.

Field	Type	Description
`natures_of_control`	List[Object]	See Nature of Control schema
`registered_address`	String	Address the controlling entity is registered at
`registered_address_country` † ‡	String	Country of registered address for the controlling entity
`notified_date`	String	Date registry was notified of the role being assumed
`start_date`	String	Date of becoming a controlling entity

Notes

† During case creation, ISO-3166 alpha 2 codes may be provided instead of full country name, and are preferred

‡ registered_address_country is required to drive the SHHRC rule

`Nature of Control` schema

Field	Type	Description
`category`*	String	One of (`ownership`, `voting_rights`, `other`)
`description`	String	Any notes about the nature of control
`min_percent`	Int	A number between 1 and 100, representing minimum percentage ownership / voting rights by the entity
`max_percent`†	Int	A number between 1 and 100, representing maximum percentage ownership / voting rights by the entity

Notes

† During case creation, to represent a single percentage of ownership/voting rights, provide a max_percent value only

Receive case updates

KYB screenings complete by emitting a webhook event. (For advice in setting up webhooks, see Webhooks).

At present there is just one KYB webhook, that triggers when the screening task completes. This can be distinguished from other ComplyAdvantage webhooks by the field "event": "kyb_screening_updated".

The webhook contains all case information. This spans:

the company being screened
officers and controlling entities of the company
risks evaluated against the company and its entities

Webhook example

Webhook payload is only available in json format. Please refer to json section.

Webhook payload is only available in json format. Please refer to json section.

{
  "event": "kyb_screening_updated",
  "data": {
    "version": "1.0",
    "case_id": 1,
    "case_status": "open",
    "screening_id": 2,
    "screening_status": "ready",
    "company_information": {
      "entity_id": "911f8e73-a779-420e-ac34-36f0f9cf3778",
      "company_id": "12345ABC",
      "company_name": "COMPANY NAME LTD",
      "company_address": "71-75 STREET NAME, MORE ADDRESS, CITY NAME",
      "company_status": "active",
      "company_type": "Public Limited Company",
      "incorporation_date": "2021-02-25",
      "incorporation_jurisdiction": "United Kingdom",
      "incorporation_jurisdiction_code": "gb",
      "industries": [
        {
          "code": "62090",
          "description": "Other information technology service activities",
          "type": "SIC"
        }
      ]
    },
    "controlling_entities": [
      {
        "entity_id": "71ec2ecd-3317-4c2a-8f5d-ca16cb17cb7c",
        "entity_type": "person",
        "person_name": "Person Name",
        "country_of_residence": "United Kingdom",
        "date_of_birth": "1989-12",
        "nationality": "American",
        "profession": "Director",
        "provenance": {
          "source": "complyadvantage"
        },
        "relationships": [
          {
            "target_entity_id": "911f8e73-a779-420e-ac34-36f0f9cf3778",
            "natures_of_control": [
              {
                "category": "voting_rights",
                "description": "voting-rights-50-to-75-percent",
                "max_percent": 75,
                "min_percent": 50
              },
              {
                "category": "other",
                "description": "right-to-appoint-and-remove-directors",
                "max_percent": null,
                "min_percent": null
              }
            ],
            "registered_address": "71-75 STREET NAME, MORE ADDRESS, CITY NAME",
            "registered_address_country": null,
            "start_date": "2021-02-25",
            "end_date": "2021-04-07",
            "notified_date": null
          }
        ]
      },
      {
        "entity_id": "b9d84a25-06f1-4a9a-87c2-9c806c9f988f",
        "entity_type": "company",
        "company_name": "COMPANY NAME TWO LIMITED",
        "provenance": {
          "source": "complyadvantage"
        },
        "relationships": [
          {
            "target_entity_id": "911f8e73-a779-420e-ac34-36f0f9cf3778",
            "natures_of_control": [
              {
                "category": "ownership",
                "description": "ownership-of-shares-75-to-100-percent",
                "max_percent": 100,
                "min_percent": 75
              }
            ],
            "registered_address": "71-75 STREET NAME, MORE ADDRESS, CITY NAME",
            "registered_address_country": null,
            "notified_date": null,
            "start_date": "2017-09-19",
            "end_date": null
          }
        ]
      }
    ],
    "officers": [
      {
        "entity_id": "1281fe78-50a2-48db-8ac2-489582920697",
        "entity_type": "person",
        "person_name": "JOHN DOE",
        "country_of_residence": "UNITED KINGDOM",
        "date_of_birth": "1966-07",
        "nationality": "BRITISH",
        "profession": "COMPANY DIRECTOR",
        "provenance": {
          "source": "complyadvantage"
        },
        "relationships": [
          {
            "target_entity_id": "911f8e73-a779-420e-ac34-36f0f9cf3778",
            "position": "Current Director",
            "appointed_date": "2021-05-01",
            "correspondence_address": "71-75 STREET NAME, MORE ADDRESS, CITY NAME",
            "correspondence_address_country": null,
            "notified_date": null
          }
        ]
      }
    ],
    "risk_assessment_results": [
      {
        "entity_id": "1281fe78-50a2-48db-8ac2-489582920697",
        "results": [
          {
            "description": "Evaluates whether an officer has potential matches for Adverse Media.",
            "manual_evaluation_status": "open",
            "name": "officer-adverse-media",
            "reason": {
              "message": "entity appeared in source list",
              "source_types": [
                "adverse-media"
              ]
            },
            "result": "FAIL",
            "rule_code": "OAM"
          }
        ]
      },
      {
        "entity_id": "71ec2ecd-3317-4c2a-8f5d-ca16cb17cb7c",
        "results": [
          {
            "description": "Evaluates whether a shareholder with significant ownership has potential matches for Adverse Media.",
            "manual_evaluation_status": "open",
            "name": "shareholder-adverse-media",
            "reason": {
              "message": "entity appeared in source list",
              "source_types": [
                "adverse-media"
              ]
            },
            "result": "FAIL",
            "rule_code": "SHAM"
          }
        ]
      },
      {
        "entity_id": "911f8e73-a779-420e-ac34-36f0f9cf3778",
        "results": [
          {
            "description": "Evaluates whether the company is active.",
            "manual_evaluation_status": "open",
            "name": "company-active",
            "reason": null,
            "result": "SUCCESS",
            "rule_code": "COAC"
          }
        ]
      }
    ],
    "risk_assessment_url": "https://app.complyadvantage.com/kyb/case/1/screening/2",
    "screening_results": [
      {
        "entity_id": "911f8e73-a779-420e-ac34-36f0f9cf3778",
        "results": [
          {
            "akas": [
              {
                "name": "Some Company Name"
              }
            ],
            "associates": [],
            "entity_type": "ORGANISATION",
            "fields": [
              {
                "name": "Country",
                "source": "company-am",
                "tag": "",
                "value": "United Kingdom"
              }
            ],
            "id": "U5YET0XPU8CM5SK",
            "match_types": [
              {
                "name": "Name Exact",
                "type": "name_exact"
              }
            ],
            "match_types_details": [
              {
                "aml_types": [
                  "adverse-media",
                  "adverse-media-general"
                ],
                "matching_name": "Some Company Name",
                "name_matches": [
                  {
                    "match_types": [
                      "exact_match"
                    ],
                    "query_term": "company"
                  }
                ],
                "secondary_matches": [],
                "sources": [
                  "company AM"
                ]
              }
            ],
            "media": [
              {
                "date": "",
                "pdf_url": "",
                "snippet": "- Some adverse information about the company.",
                "title": "Adverse media of company",
                "url": "https://www.abc.com/1/2"
              }
            ],
            "name": "The Company",
            "source_notes": {
              "company-am": {
                "aml_types": [
                  "adverse-media"
                ],
                "code": "company-am",
                "listing_ended_utc": "",
                "listing_started_utc": "",
                "name": "company AM",
                "url": ""
              }
            },
            "sources": [
              "company-am"
            ],
            "status": {
              "code": "potential_match",
              "name": "Potential Match"
            }
          }
        ]
      }
    ],
    "reviewer": {
      "account_id": 1,
      "user_id": 2,
      "username": "John Doe"
    }
  }
}

`data` schema

data contains the ID of the case, and all case information.

FIELD	TYPE	DESCRIPTION	🔗 Documentation
`version`	String	Version number of the webhook payload using semantic versioning.
`case_id`	Integer	The ID of the KYB Case.
`company_information`	Object	Our information on a company.	See `company information` schema
`controlling_entities`	List[Object]	Entities that have control over the company being screened.	See `entity` schema
`officers`	List[Object]	Entities that are officers of the company being screened.	See `entity` schema
`risk_assessment_results`	List[Object]	Risk assessment outcomes for the case.	See `risk assessment` schema
`risk_assessment_url`	String	The URL to access the case with the KYB Frontend.
`screening_results`	List[Object]	The full details of searches of all the entities of the company.	See `screening_results` schema
`reviewer`	Object	The user who created the KYB case.

`company_information` schema

company_information contains core information about the company that's being screened.

FIELD	TYPE	DESCRIPTION
`entity_id`	String	KYB id for the company. Used to see rules and search results against the company
`company_id`	String
`company_name`	String
`company_address`	String
`company_status`	String
`company_type`	String
`incorporation_date`	String	ISO-8601 date of incorporation (YYYY-MM-DD)
`incorporation_jurisdiction`	String
`incorporation_jurisdiction_code`	String
`industries`	List[Object]	A list of industries of the company. Describes the code, description, and standard (such as `SIC`)

`risk_assessment_results` schema

This reports the screening outcomes.

The entity_id field matches the entity_id field from an entity within one of:

company_information
officers
controlling_entities

FIELD	TYPE	DESCRIPTION
`entity_id`	String	The ID of an Entity.
`results`	List[Object]	See RiskAssessmentResult

`RiskAssessmentResult` schema

The outcome of a KYB rule that applied against an Entity.

FIELD	TYPE	DESCRIPTION
`rule_code`	String	The ID of the rule. See Risks tested
`name`	String
`description`	String
`manual_evaluation_status`	String	Status of the rule. Defaults to `open` May also be `open` `in_progress` `accepted` `rejected` `request_info` `insufficient_info`
`result`	String	One of `SUCCESS` `WARNING` `ERROR` `FAIL` `UNDEFINED_RESULT_TYPE`
`reason`	Object	See `Reason` schema

`Reason` schema

FIELD	TYPE	DESCRIPTION
`message`	String	The reason of evaluation result.
`source_types`	List[String]	A list of source types evaluated.

`screening_results` schema

Reports the search results for entities, that underpinned the KYB rule evaluations.

FIELD	TYPE	DESCRIPTION
`entity_id`	String	The ID of an Entity.
`results`	List[Object]	A list of screening results returned by performing a search on the Entity. Each object in the list is equivalent to a `hit` in the search result of the search details endpoint.

TIN matching

Check a TIN number for a company

const url = 'https://api.complyadvantage.com/kyb/v1/case/1/tin-check';
const headers = {'Authorization': 'Token YOUR_API_KEY'};
data = {
  "tin": "987654321"
};

axios.post(url, data, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/kyb/v1/case/1/tin-check"
headers = {'Authorization': 'Token YOUR_API_KEY'}
data = {
  "tin": "987654321"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

{
    "tin": "987654321"
}

POST /kyb/v1/case/{case_id}/tin-check - check a US company's Tax Identification Number (TIN), specifically their Employer Identification Number (EIN).

TIN matching can be done after a KYB case has been created.

URL PARAMETERS

Field	Type	Description
`case_id`	Integer	The ID of the KYB Case.

JSON POST PARAMETERS

Field	Type	Description
`tin`*	String	The nine-digit TIN number

* Indicates mandatory fields

Notes

A maximum of 5 requests can be made for every 24 hours for each Case. Exceeding this limit will return a 429 error.
Requesting a TIN match on non-US companies will return a 403 error.

TIN Matching Response

{
    "case_id": 1,
    "created_at": "2023-06-19T14:37:18.436513Z",
    "response_code": "0",
    "response_desc": "TIN and Name combination matches.",
    "tin": "987654321"
}

{
    "case_id": 1,
    "created_at": "2023-06-19T14:37:18.436513Z",
    "response_code": "0",
    "response_desc": "TIN and Name combination matches.",
    "tin": "987654321"
}

{
    "case_id": 1,
    "created_at": "2023-06-19T14:37:18.436513Z",
    "response_code": "0",
    "response_desc": "TIN and Name combination matches.",
    "tin": "987654321"
}

RESPONSE SCHEMA

The TIN match result is returned.

Field	Type	Description
`case_id`	Integer	The ID of the KYB Case
`created_at`	String	TIN check creation time in ISO 8601 format
`response_code`	String	See TIN Codes
`response_desc`	String	See TIN Codes
`tin`	String	The TIN from the request

TIN Codes

A list of TIN match response code and description.

response_code	response_desc
`0`	TIN and Name combination matches.
`1`	TIN was missing or TIN not 9-digit numeric.
`2`	TIN entered is not currently issued.
`3`	TIN and Name combination does not match.
`4`	Invalid TIN Matching request.
`5`	Duplicate TIN Matching request.
`6`	TIN and Name combination matches SSN records.
`7`	TIN and Name combination matches EIN records.
`8`	TIN and Name combination matches SSN and EIN records.
`-1`	TIN check failed.

Other Endpoints

GET /users

Example request

const url = 'https://api.complyadvantage.com/users';
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.get(url, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/users"
response = requests.get(
  url,
  headers={"Authorization": "Token YOUR_API_KEY"},
)
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';
const data = {
    "search_term": "Burger world",
    "client_ref": "clientRef",
    "search_profile": "d9d050bb-0e6a-4a93-b9bc-83f51a9503db"
};
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.post(url, data, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = 'https://api.complyadvantage.com/searches/references'
data = {
    "search_term": "Burger world",
    "client_ref": "clientRef",
    "search_profile": "d9d050bb-0e6a-4a93-b9bc-83f51a9503db",
}
headers = {"Authorization": "Token YOUR_API_KEY"}

response = requests.post(url, json=data, headers=headers)
print(response.json())

{
    "search_term": "Burger world",
    "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",
              "name_type": "aka",
              "source_name": "VLADIMIR",
              "substring": " Vladimir",
              "substring_index": [
                33,
                42
              ]
              },
            {
              "matching_term": "vladidimir",
              "matching_reason": "exact_match",
              "name_type": "hypocorism",
              "source_name": "VLADIMIR",
              "substring": " Vladimir",
              "substring_index": [
                33,
                42
              ]
            },
            {
              "matching_term": "vladimiriv",
              "matching_reason": "exact_match",
              "name_type": "abbreviation",
              "source_name": "VLADIMIR",
              "substring": " Vladimir",
              "substring_index": [
                33,
                42
              ]
            }
          ],
          "score": 29.926937
        },
        ....
      ],
      "blacklist_hits": [
        {
          "doc": {
            "account_ids": [
              200014
            ],
            "aka": [
              {
                "name": "crime"
              }
            ],
            "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": "crime",
            "scraper_ids": [],
            "sources": [
              "erictest"
            ],
            "types": []
          },
          "match_types": [
            "ngram"
          ],
          "match_details": [
            {
              "matching_term": "crime",
              "matching_reason": "exact_match",
              "name_type": "aka",
              "source_name": "crime",
              "substring": " crime ",
              "substring_index": [
                15,
                24
              ]
            }
          ],
          "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",
              "name_type": "aka",
              "source_name": "VLADIMIR",
              "substring": " Vladimir",
              "substring_index": [
                33,
                42
              ]
              },
            {
              "matching_term": "vladidimir",
              "matching_reason": "exact_match",
              "name_type": "hypocorism",
              "source_name": "VLADIMIR",
              "substring": " Vladimir",
              "substring_index": [
                33,
                42
              ]
            },
            {
              "matching_term": "vladimiriv",
              "matching_reason": "exact_match",
              "name_type": "abbreviation",
              "source_name": "VLADIMIR",
              "substring": " Vladimir",
              "substring_index": [
                33,
                42
              ]
            }
          ],
          "score": 29.926937
        },
        ....
      ],
      "blacklist_hits": [
        {
          "doc": {
            "account_ids": [
              200014
            ],
            "aka": [
              {
                "name": "crime"
              }
            ],
            "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": "crime",
            "scraper_ids": [],
            "sources": [
              "erictest"
            ],
            "types": []
          },
          "match_types": [
            "ngram"
          ],
          "match_details": [
            {
              "matching_term": "crime",
              "matching_reason": "exact_match",
              "name_type": "aka",
              "source_name": "crime",
              "substring": " crime ",
              "substring_index": [
                15,
                24
              ]
            }
          ],
          "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",
              "name_type": "aka",
              "source_name": "VLADIMIR",
              "substring": " Vladimir",
              "substring_index": [
                33,
                42
              ]
              },
            {
              "matching_term": "vladidimir",
              "matching_reason": "exact_match",
              "name_type": "hypocorism",
              "source_name": "VLADIMIR",
              "substring": " Vladimir",
              "substring_index": [
                33,
                42
              ]
            },
            {
              "matching_term": "vladimiriv",
              "matching_reason": "exact_match",
              "name_type": "abbreviation",
              "source_name": "VLADIMIR",
              "substring": " Vladimir",
              "substring_index": [
                33,
                42
              ]
            }
          ],
          "score": 29.926937
        },
        ....
      ],
      "blacklist_hits": [
        {
          "doc": {
            "account_ids": [
              200014
            ],
            "aka": [
              {
                "name": "crime"
              }
            ],
            "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": "crime",
            "scraper_ids": [],
            "sources": [
              "erictest"
            ],
            "types": []
          },
          "match_types": [
            "ngram"
          ],
          "match_details": [
            {
              "matching_term": "crime",
              "matching_reason": "exact_match",
              "name_type": "aka",
              "source_name": "crime",
              "substring": " crime ",
              "substring_index": [
                15,
                24
              ]
            }
          ],
          "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 and 290 characters for APSE api users)	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';
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.get(url, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/entity/GRV6TUVJXJQ0P06"
headers = {"Authorization": "Token YOUR_API_KEY"}

response = requests.get(url, headers=headers)
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';
const 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"
  }
};
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.post(url, data, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/entity/search"
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"
  }
}
headers = {"Authorization": "Token YOUR_API_KEY"}

response = requests.post(url, data=data, headers=headers)
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

match_type

Whenever we match against a document, we try to include some data as to what matched. Possible values are as follows:

name_exact matched against the entity name exactly
name_synonym matched against the entity name with a synonym, e.g. "Robert Mugabe" => "Bob Mugabe"
aka_exact matched against an entity AKA (also known as) entry exactly
aka_synonym matched against an entity AKA with a synonym, e.g. "Robert Mugabe" => "Bob Mugabe"
name_phonetic matched against the entity name phonetically
aka_phonetic matched against an entity AKA phonetically
fuzzy matched closely to the name or AKA name, but not exactly
year_of_birth matched the birth year as given in filters

PATCH /searches/[id]/entity/[eid]

Example Request

const url = 'https://api.complyadvantage.com/searches/1/entity/FRDG8ZC7VURPKP0';
const headers = {'Authorization': 'Token YOUR_API_KEY'};

axios.patch(url, {
        'match_status': 'false_positive'
    }, {headers: headers})
    .then((response) => {
        console.log(response.data);
    });

url = "https://api.complyadvantage.com/searches/1/entity/FRDG8ZC7VURPKP0"
headers = {"Authorization": "Token YOUR_API_KEY"}

response = requests.patch(
  url, 
  data={"match_status": "false_positive"}
  headers={"Authorization": "Token YOUR_API_KEY"},
)
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:

Region	IP addresses
EU	54.76.153.128
EU	52.19.50.164
EU	18.200.42.250
US	3.216.162.15
US	3.214.3.128
US	52.73.76.4
Australia	3.105.135.152
Australia	54.79.153.96
Australia	52.63.190.126
US (Ohio)	18.217.114.218
US (Ohio)	18.223.31.187
US (Ohio)	18.220.222.49
Canada	3.99.25.80
Canada	15.156.98.111
Canada	15.156.108.51
UK	18.169.169.169
UK	18.133.4.174
UK	18.169.86.169

LOCKING DOWN WEBHOOK ENDPOINTS

We recommend a combination of the following in order to lock down your Webhook endpoints:

Use https endpoints only
Firewall out all traffic, except from the IP addresses specified above for the region you are subscribed to
Create a unique endpoint, eg https://wh.mycompany.com/complyadvantage/sadjbrh457GHsaddjhd

POST REQUEST FORMAT (JSON)

The POST request consists of two fields:

FIELD	TYPE	DESCRIPTION
`event`	String	The type of event generated
`data`	Array	The payload of the event

Details of the specific event types and payloads are included below.

Event: match_status_updated

Webhook sample

{
  "event": "match_status_updated",
  "data": {
    "search_id": 1,
    "client_ref": "CUST001",
    "entity_id": "34HI34PORF23",
    "entity_match_status": "false_positive",
    "is_whitelisted": true,
    "tags": {
      "name": "value"
    }
  }
}

{
  "event": "match_status_updated",
  "data": {
    "search_id": 1,
    "client_ref": "CUST001",
    "entity_id": "34HI34PORF23",
    "entity_match_status": "false_positive",
    "is_whitelisted": true,
    "tags": {
      "name": "value"
    }
  }
}

{
  "event": "match_status_updated",
  "data": {
    "search_id": 1,
    "client_ref": "CUST001",
    "entity_id": "34HI34PORF23",
    "entity_match_status": "false_positive",
    "is_whitelisted": true,
    "tags": {
      "name": "value"
    }
  }
}

This event is fired whenever the match status of an entity or the is_whitelisted property of an entity is changed.

The data payload is as follows:

FIELD	TYPE	DESCRIPTION
`client_ref`	String	Your supplied reference for the search subject
`search_id`	String	The ID of the search
`entity_id`	String	The ID of the entity that has changed e.g: 34HI34PORF23
`entity_match_status`	String	The new match status of the entity. One of 'false_positive', 'true_positive', 'potential_match', 'no_match', 'unknown'. The field is present in the payload only if the value was changed.
`is_whitelisted`	Boolean	The new value for the `is_whitelisted` property of the entity. The field is present in the payload only if the value was changed.
`tags`	Object	Any search allocated tags

Event: search_status_updated

Webhook sample

{
  "event": "search_status_updated",
  "data": {
    "changes": {
      "before": {
        "assigned_to": 123
      },
      "after": {
        "assigned_to": 234
      }
    },
    "ref": "1470903392-yS1UuFFF",
    "client_ref": "12345-MY-REFERENCE",
    "search_id": 1234,
    "terms": [
      {
        "name": "Robert Mugabe",
        "hits": 7
      }
    ],
    "filters": {
      "exact_match": false,
      "fuzziness": 0.5
    }
  }
}

{
  "event": "search_status_updated",
  "data": {
    "changes": {
      "before": {
        "assigned_to": 123
      },
      "after": {
        "assigned_to": 234
      }
    },
    "ref": "1470903392-yS1UuFFF",
    "client_ref": "12345-MY-REFERENCE",
    "search_id": 1234,
    "terms": [
      {
        "name": "Robert Mugabe",
        "hits": 7
      }
    ],
    "filters": {
      "exact_match": false,
      "fuzziness": 0.5
    }
  }
}

{
  "event": "search_status_updated",
  "data": {
    "changes": {
      "before": {
        "assigned_to": 123
      },
      "after": {
        "assigned_to": 234
      }
    },
    "ref": "1470903392-yS1UuFFF",
    "client_ref": "12345-MY-REFERENCE",
    "search_id": 1234,
    "terms": [
      {
        "name": "Robert Mugabe",
        "hits": 7
      }
    ],
    "filters": {
      "exact_match": false,
      "fuzziness": 0.5
    }
  }
}

This event is fired whenever the status of a search is changed through case management functionality (API or UI). The changes to the following fields will trigger this web hook:

assigned_to
risk_level
match_status

The data payload is as follows:

FIELD	TYPE	DESCRIPTION
`changes`	Object	Contains `before` and `after` objects, detailing the changes. Please see the example below
`ref`	String	The search reference
`client_ref`	String	Your supplied reference for the search subject
`search_id`	Integer	The numeric search ID
`terms`	Array	An array of the search terms included in this request
`filters`	Array	An array of the search terms included in this request

Event: monitored_search_updated

Webhook example

{
  "event": "monitored_search_updated",
  "data": {
    "search_id": 10117833,
    "updated": [
      "8NMXF7QX4QV8LFD",
      "X4525MEAZKKPX0T",
      "73HBD537LCX5JT6"
    ],
    "new": [
      "Q3OX4KS0KEMCVDH",
      "UCC60H79WVU94Z0"
    ],
    "removed": [
      "9D1ETD0ADTT4HDH",
      "I38XC0R6Y1EQ083"
    ],
    "is_suspended": true
  }
}

{
  "event": "monitored_search_updated",
  "data": {
    "search_id": 10117833,
    "updated": [
      "8NMXF7QX4QV8LFD",
      "X4525MEAZKKPX0T",
      "73HBD537LCX5JT6"
    ],
    "new": [
      "Q3OX4KS0KEMCVDH",
      "UCC60H79WVU94Z0"
    ],
    "removed": [
      "9D1ETD0ADTT4HDH",
      "I38XC0R6Y1EQ083"
    ],
    "is_suspended": true
  }
}

{
  "event": "monitored_search_updated",
  "data": {
    "search_id": 10117833,
    "updated": [
      "8NMXF7QX4QV8LFD",
      "X4525MEAZKKPX0T",
      "73HBD537LCX5JT6"
    ],
    "new": [
      "Q3OX4KS0KEMCVDH",
      "UCC60H79WVU94Z0"
    ],
    "removed": [
      "9D1ETD0ADTT4HDH",
      "I38XC0R6Y1EQ083"
    ],
    "is_suspended": true
  }
}

This event is fired when a monitored search has been detected as having updated search results available, and/or the suspended state of the monitored search changes.

The data payload is as follows:

FIELD	TYPE	DESCRIPTION
`search_id`	Integer	The numeric ID of the search
`updated`	Array	An array of the Entity IDs in the search result which have been modified.
`new`	Array	An array of the Entity IDs which have been added to the search result.
`removed`	Array	An array of the Entity IDs which have been removed from the search result.
`is_suspended`	Boolean	Indicates whether this monitored search has been suspended or not.