KYC - Create search

To run a PEPs, Sanctions and AM check against an entity, you need to create a search for that entity.

Each search is unique and a searchID is provided for that search that returns any PEPs, Sanctions or Adverse Media hits found for the searched entity. As each search is unique, if you're replicating a search that has previously been run, we would recommend you use the same SearchID. If you are trying to run a search for an entity you've searched before, but with different search parameters or filters, then please run a new search.

Requests

There are four components to creating a search:

Field	Type	Description
`searchTerm` (mandatory)	string	The string representing the entity i.e. entity name
`fuzziness` (optional)	float (0.0 – 0.1)	Determines how closely the returned results must match the supplied name. 0% fuzziness disables 1-letter typo matching but keeps all other matching behaviours (standard and optional). Overridden by `exactMatch`.
`exactMatch` (optional)	boolean	Exact match disables all standard and optional matching behaviours (Honorifics, affixes, initials, glued name, name variation, equivalent names, extra words in entity,...).
`filters` (optional)	objects	Specify filters within the search to narrow down the results. Whilst optional, adding in filter details help refine the results. e.g entityType

Filters

The filters that can be applied to search are:

Field	Type	Description
`amlType` (optional)	array of strings	These are the alerts you want to check are associated with the entity. One or more of: - sanction - warning - fitness-probity - pep - adverse-media-v2 More granular `amlTypes` for `pep` and `adverse-media-v2` can be found here
`birthYear` (optional)	integer	Optional but desirable for a ‘person’ search, as it will help narrow the search and reduce false positives. If you include a year of birth, the results will return entities with a similar name and are within +-1 year of the year of birth specified; and any entities that have a similar name and no specified year of birth.
`countryCodes` (optional)	array of ISO 3166-1 alpha-2 strings	Optional and only applies for PEPs (Politically Exposed Person), but it will help you reduce False Positives. The country filter refers to the country in which the entity took office (country of residence).
`removeDeceased`	boolean	A flag which when set, removes deceased people from search results
`entityType`	string	One of: - "person" - "company" - "organisation" - "vessel" - "aircraft"

Entity Type Filter

entityType is a filter that can be applied to the search, and whilst is not mandatory, we recommend that it is specified as it optimises the search results. The entityType filter is not a hard filter between different entity types. It only optimizes the matching logic to the relevant entity type.

entityType can be:

“person"
"company"
"organisation"
"vessel"
"aircraft"

For example:

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 are considered specifically for different entity types ("Robert" and "Bob" versus "Investment" and "Inversion").
Initial matching between individual ("Carl W. Litsch") versus company acronyms ("KFC").
If this is not set as a filter, then a default set of rules and logic will be applied

Example requests

Basic:

{  
    "criteria": {  
        "searchTerm": "Robert Mugabe"  
    }  
}

All filters utilised:

{
    "criteria": {
        "searchTerm": "Robert Mugabe",
        "fuzziness": 0.8,
        "exactMatch": false,
        "filters": {
            "amlTypes": [
                "pep",
                "sanction",
                "warning"
            ],
            "countryCodes": [
                "ZW"
            ],
            "entityType": "person",
            "birthYear": 1922,
            "removeDeceased": true
        }
    }
}

Response

The search query will provide a response with the following details:

Field	Type	Description
`criteria`	object	The search criteria specified in the request
`searchID`	string	The unique identifier related to the search. This can be used to retrieve the data surfaced for this particular search
`totalHits`	integer	The number of search hits that were identified to the entity you were searching for
`totalMatches`	integer
`created`	date-time	Date of search creation
`updated`	string
`searchHits`	array of objects	An array containing search hit objects, the score, and match type objects

Each of the entity objects returned in searchHits will show:

Field	Type	Description
`searchHit`	array of objects	This array contains entity objects matching the search term. There should be an entity object for each search hit identified.
\|_`entityType`	string	The entity type associated with this search hit
\|_`name`	string	The name associated with the search hit
\|_`amlTypes`	array of strings	An array of amlTypes that were found for this searchHit
\|_`sourceInformation`	object	An object contain the data source of the search hit
\|__`source`	array	An array of data source found for the search hit (e.g. Sanctions List)
\|____`name`	string	Name of source
\|____`key`	string	Key of source
\|____`amlType`	array of strings	amlType found from the source
\|____`url`	string	URL of the source
\|____`listingStarting`	date-time	When the source was listed
\|____`listingEnded`	date-time	When the source listed ended.
\|____`sourceNotes`	array of objects	Additional information about the source. This is an array containing: - Name - Value - Source
\|___`unlinkedSourceNotes`	array of objects	Additional information about the source. This is an array containing: - Name - Value - Source
\|_ `aka`	array of objects	Array of alternative names for the entity. Note that the "name" field is present at the minimum.
\|_`associates`	array of objects	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.
\|_`media`	array of objects	List of media entries where appropriate, with the "date", "title", "snippet" and "url" parameters.
\|_`lastUpdated`	date-time	This is the time that the entity was last updated
\|_`score`	float	The score is a computation of search results match and ranking. The score should only be used in the context of ordering search results and indicates relevance. For information on how the score is computed, check out score matching
\|_`matchTypesPrimary`	array of string	Lists the main matchTypes (as specified below) identified with documents
\|_`matchTypesAll`	array of objects	Provides additional on the matchTypes found, including the matchingName, the source, amlTypes, searchTermMatches and any additional secondaryCriteriaMatches

Match Types

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

matchType	Description
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
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:

matchType	Description
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

Example Response

{
  "criteria": {
    "exactMatch": false,
    "filters": {
      "amlTypes": ["sanction"],
      "birthYear": 1800,
      "countryCodes": [],
      "entityType": "person",
      "removeDeceased": false
    },
    "fuzziness": 0.5,
    "searchTerm": "string"
  },
  "created": "2019-08-24T14:15:22Z",
  "searchHits": [
    {
      "matchTypesAll": [
        {
          "amlTypes": ["sanction"],
          "matchingName": "string",
          "searchTermMatches": [
            {
              "matchTypes": ["exact_match"],
              "word": "string"
            }
          ],
          "secondaryCriteriaMatches": [
            {
              "criteria": "string",
              "matchTypes": ["name_variations_removal"]
            }
          ],
          "sources": ["string"]
        }
      ],
      "matchTypesPrimary": ["name_variations_removal"],
      "score": 0,
      "searchHit": {
        "aka": [
          {
            "name": "string"
          }
        ],
        "amlTypes": ["sanction"],
        "associates": [
          {
            "association": "string",
            "name": "string"
          }
        ],
        "entityType": "person",
        "lastUpdated": "2019-08-24T14:15:22Z",
        "media": [
          {
            "date": "2019-08-24T14:15:22Z",
            "snippet": "string",
            "title": "string",
            "url": "string"
          }
        ],
        "name": "string",
        "sourceInformation": {
          "sources": [
            {
              "amlTypes": ["sanction"],
              "key": "string",
              "listingEnded": "2019-08-24T14:15:22Z",
              "listingStarted": "2019-08-24T14:15:22Z",
              "name": "string",
              "sourceNotes": [
                {
                  "name": "string",
                  "source": "string",
                  "value": "string"
                }
              ],
              "url": "string"
            }
          ],
          "unlinkedSourceNotes": [
            {
              "name": "string",
              "source": "string",
              "value": "string"
            }
          ]
        }
      },
      "searchId": "9b1a67f9-9477-48e5-8a6c-11b70245e1d9",
      "totalHits": 0,
      "totalMatches": 0,
      "updated": "2019-08-24T14:15:22Z"
    }
  ]
}