Skip to content
ClearDil Docs

ClearDil API 1.0

Updated 2022-02-21

This document is a detailed reference for our REST API.

The ClearDil API offers a framework and functionality for businesses that want to automate their Know Your Customer (KYC) and Anti-Money Laundering (AML) processes. The API is built using REST endpoints - it has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. JSON is returned by all API responses, including errors.

As a general guideline, if a property has an empty or null value, we drop it from the JSON unless there’s a strong semantic reason for its existence.

We’ve designed our documentation to be easy to use. It is grouped by feature sets and offers practical examples.

API endpoint

Terminal window
    https://api.cleardil.com (live)


    https://api.cleardil.com (sandbox)

Examples in this documentation are generated using Postman.

Sandbox environment.
Please note that data in the sandbox environment is deleted periodically.

Try Now

Try the ClearDil API in seconds. Create your first customer, perform screening checks, and more by following the steps below.

Access your test token

To make our API as explorable as possible, accounts have sandbox and live API keys. Just use the appropriate key along with the corresponding ClearDil domain to perform a live call to api.cleardil.com, or test call to api.cleardil.com. Requests made to the sandbox environment will not incur a cost.

Register an account with us to immediately access your live and sandbox token from your Dashboard.

 
  curl --location --request POST 'https://api.cleardil.com/v1/oauth2/token' \
       --header 'Content-Type: application/x-www-form-urlencoded' \
       --header 'Authorization: Basic dXNlcjpwYXNzd29yZA==' \
       --data ''

Create customer

As a first step, a customer must be created to facilitate all further checks. Let’s create the customer John Doe using your token. Copy the curl request on the right, replace test_api_token with your given test token, and run it in your terminal to create a customer. You should see the created customer object in the response. Note down the `id` attribute of the customer as it is required for the next step.

 
  curl --location 'https://api.cleardil.com/v1/customers' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer api_token' \
  --data-raw '{
      "type" : "INDIVIDUAL",
      "email" : "jon@doe.com",
      "telephone" : "+91-9337888808",
      "mobile" : "+91-9337888808",
      "addresses" : [
              {
              "property_number": "10",
              "property_name": "Custom House",
              "line": "Main Street",
              "city": "Aldgate",
              "state_or_province": "London",
              "postal_code": "E99 0ZZ",
              "country": "GBR",
              "from_date": "2010-01-01"
          }
      ],
      "title" : "MRS",
      "first_name" : "Jon",
      "middle_name" : "Martin",
      "last_name" : "Doe",
      "maiden_name" : "Kiriku",
      "alternative_first_name" : "Jonathan",
      "alternative_middle_name" : "Martinero",
      "alternative_last_name" : "Patel",
      "dob" : "1971-04-06",
      "gender": "MALE",
      "nationality" : "IND",
      "birth_country" : "IND"
  }'

Screen customer

Now that we created a customer, you are ready to run a screening check against ClearDil’s global watchlist and Politically Exposed Persons (PEP) database. Copy the curl request on the right, replace customer_id with the customer id generated previously, and run it in your terminal to start screening.

You should see the created screening object in the response. In this case, the check has completed and the result is a clear. Please note that this is a result based on a simulated run, as screenings are not actually run against real-life databases in the sandbox environment.

Now that we created a customer, you are ready to run a screening check against ClearDil’s global watchlist and Politically Exposed Persons (PEP) database. Copy the curl request on the right, replace customer_id with the customer id generated previously, and run it in your terminal to start screening. You should see the created screening object in the response. In this case, the check has completed and the result is a clear. Please note that this is a result based on a simulated run, as screenings are not actually run against real-life databases in the sandbox environmen**t.

 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/screenings' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer api_token' \
      --data '[
              "pep",
              "watchlist",
              "disqualified_entities",
              "adverse_media"
      ]'

Topics

Authentication and headers

To make a REST API call, you must include request headers including the Authorization header with an OAuth 2.0 access token. To get an access token, you must first create an account, then ClearDil will generate a set of OAuth client_id and secret keys for your app for both the sandbox and live environments. Then, you pass the client_id:secret credentials in the Authorization header to acquire an access token.

The authorisation server issues an access token in exchange for your client ID and secret credentials. You use the access token for authentication when you make REST API requests.

Access token. The issued access token is valid for 60 minutes. On expiry, please ensure that you obtain a new access token using your credentials as specified above. All API requests must be made over HTTPS. Any requests made over HTTP will fail.

All API requests must be made over HTTPS. Any requests made over HTTP will fail.

 
  curl --location --request POST 'https://api.cleardil.com/v1/oauth2/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic dXNlcjpwYXNzd29yZA==' \
  --data ''

Request Headers

NameDescription
Authorization
*required		To request an access token, send your clientid and secret values as the HTTP basic authentication credentials.
If you use cURL, specify -u _client_id
. When you call APIs, send the value as the OAuth 2.0 access token with the authentication type set as Bearer. For example: Authorization: Bearer.

Errors

ClearDil uses standard HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g. a required parameter was omitted, etc.), and codes in the 5xx range indicate an error with ClearDil’s servers.

An error does not indicate whether a check has passed or failed.
HTTP status code summary
Response codeMeaning
200
OK		Everything worked as expected.
201
Created		New resource created.
204
No Content		Resource is deleted.
400
Bad Request		Request has missing arguments or is malformed.
401
Unauthorized		Invalid authorisation credentials.
403
Forbidden		Request is authenticated but has insufficient permissions.
404
Not Found		The endpoint requested does not exist.
405
Not Found		Method not found.
409
Conflict		The request conflicts with another request (perhaps due to using the same idempotent key).
410
Gone		Resource no longer available.
500
Server Error		Something is wrong on our end.
503
Server Unavailable		Service is unavailable (perhaps due to a planned upgrade).
Error Object
PropertyDescription
id
string		A unique identifier for the error. This can be used as a reference when you contact our support team.
type
string		The type of error returned.
message
string		A user-friendly message providing more details about the error.
errors
hash		The list of attributes which have errors associated with them. Only applies to validation errors. This will include the validation code.
Example Error Object
  {
    "id": "7e2e3fe2-4ae8-4bff-a1b5-d0b84a964e02",
    "type": "invalid_request",
    "message": "Error message",
    "errors": [
      {
        "field": "nationality",
        "type": "invalid_country_code",
        "message": "No country found for specified code"
      }
    ]
  }
Error Types
TypeDescription
invalid_requestRequest has malformed or missing fields.
invalid_sorting_requestNo property “{sort_term}” found.
invalid_patch_requestSpecified patch has invalid path or operation.
malformed_contentContent of the request does not conform to specification.
invalid_operationOperation is not supported. {reason}.
invalid_tokenProvided token is invalid or expired.
access_deniedAccess to this resource is denied.
insufficient_permissionsYou don’t have sufficient permissions to perform this action.
resource_not_foundCannot find a resource {resource}.
duplicateSuch resource already exists.
conflictResource cannot be modified because of conflicting request.
resource_deletedThe requested resource was deleted.
internal_errorOperation execution was failed.
not_implementedRequested operation isn’t implemented yet.
service_maintenanceA service is under planned maintenance.
Validation Error Codes

The following validation error codes only apply to invalid_request errors.

CodeDescription
mandatory_field_missingThis field is required.
incorrect_email_formatThe format of the email is incorrect.
past_date_expectedThe date value for this field is expected to be in the past.
date_out_of_bounds1. Date is expected to be earlier than {x}. 2. Date is expected to be later than {x}. 3. Date is expected to be between {x} and {y}.
incorrect_phone_number_formatPhone number does not meet international format.
invalid_country_codeNo country found for specified code.
invalid_pattern1. For search terms: %, ^,* and @ are not allowed. 2. For incorporation number: Only numbers, digits, _ and - are allowed.
wrong_value_lengthSize must be between {x} and {y}.
invalid_valueThe value provided does not conform to specification.
invalid_date_formatInvalid date format or value, expected YYYY-MM-DD.
invalid_mrz_formatThe format of MRZ line is invalid, only A-Z, 0-9 and < are expected.
invalid_constant_valueThe value provided does not conform to specification.

Pagination

All top-level API resources have support for bulk fetches via “list” API methods. For instance you can list customers and documents. These requests will be paginated to 20 items by default.

You can specify further pages using the page parameter and specify page size. Other parameters include the sort, which will expect a string based attribute name, followed by asc or desc.

Request Arguments

ParameterDescription
page
optional		Specifies the page number to retrieve. Value must be between 0 and 100.
size
optional		Indicates how many records each page should contain. Value must be greater than or equal to 1.
sort
optional		Sorts the records in the response by the specified attribute. Optionally, you can specify whether the records are returned in ascending or descending order.
 
curl --location 'https://api.cleardil.com/v1/customers?page=0&size=2&sort=last_name%2CDESC' \
    --header 'Authorization: Bearer api_token'

Patch object

A JSON patch object can be used across several of our endpoints to apply partial updates to resources.

ParameterDescription
op
string		The operation to perform. Valid values are: add,remove,replace,move,copy and test.
path
string		A JSON pointer that references a location in the target document where the operation is performed.
value
see description		The value to apply based on the operation. The remove operation does not require a value. Possible types: number, integer, string, boolean, null, array, object.
from
string		A JSON pointer that references the location in the target document from which to move the value. Required for the move operation.

Resources

Customers

A customer represents the individual or company the various checks are being performed on. To initiate a check, a customer must be created first. The API allows you to create, retrieve, update, and delete your customers. You can retrieve specific customers as well as a list of all your customers.

A customer must first be created to facilitate all further checks. Once a customer is created, we will automatically generate a risk profile.

The customer object

Attributes

ParameterDescription
id
string Individual and Company
The unique identifier for the customer.
created_at
Individual and Company
datetime		The date and time when the customer was created.
updated_at
Individual and Company
datetime		The date and time when the customer was updated.
type
Individual and Company
string		The customer type. Valid values are INDIVIDUALorCOMPANY.
joined_at
Individual and Company
datetime		The date and time when the customer was registered with you. This is relevant for users that migrate existing customers.
email
Individual and Company
string		The customer’s email address.
telephone
Individual and Company
string		The customer’s telephone number.
mobile
Individual and Company
string		The customer’s mobile number.
addresses
Individual and Company
list address		A list of addresses associated with customer.
title
Individual
string		The customer’s title. Valid values are MR, MRS, MISS, or MS.
first_name
Individual
string		The customer’s first name.
middle_name
Individual
string		The customer’s middle name.
last_name
Individual
string		The customer’s last name.
maiden_name
Individual
string		The customer’s maiden name.
alternative_first_name
Individual
string		The customer’s alternative or new first name.
alternative_middle_name
Individual
string		The customer’s alternative or new middle name.
alternative_last_name
Individual
string		The customer’s alternative or new last name.
dob
Individual
date		The customer’s date of birth. The format is YYYY-MM-DD.
gender
Individual
string		The customer’s gender. Valid values are MALE, FEMALE, or OTHER.
nationality
Individual
string		The customer’s nationality. This will be the three-letter country .
birth_country
Individual
string		The customer’s country of birth. This will be the three-letter country .
special_occupation
Individual
string		The customer’s occupation. Valid values can be any of the occupation categories we support.
company_name
Company
string		The company name.
alternative_company_name
Company
string		The company’s alternative or new name.
incorporation_number
Company
string		The company’s incorporation number.
incorporation_type
Company
string		The company’s incorporation type. Valid values are:
1.SOLE_TRADER
2.PRIVATE_LIMITED
3.LIMITED_LIABILITY_PARTNERSHIP
4.PUBLIC_LIMITED
incorporation_country
Company
string		The company’s country of incorporation. This will be the three-letter country .
business_purpose
Company
string		The company’s business purpose. Valid values are:
1.REGULATED_ENTITY
2.PRIVATE_ENTITY
3.UNREGULATED_FUND
4.TRUST
5.FOUNDATION
6.RELIGIOUS_BODY
7.GOVERNMENT_ENTITY
8.CHARITY
9.CLUB
10.SOCIETY
primary_contact_name
Company
string		The company’s primary contact full name.
primary_contact_email
Company
string		The company’s primary contact email address.
ADDRESS

Attributes

ParameterDescription
type
string		The address type. Valid values are PRIMARY, ALTERNATIVE, or OTHER.
property_number
string		The property number for this address.
property_name
string		The property name for this address.
line
string		The first line of the customer’s address.
extra_line
string		The second line of the customer’s address.
city
string		The city or town of the customer’s address.
state_or_province
string		The county, state or province of the customer’s address. If US customer, the US states must use the USPS abbreviation (refer to ISO 3166-2), for example NY, MI, or CA.
postal_code
string		The post or zip code of the customer’s address. This is a required field.
country
string		The country of the customer’s address. This will be the three-letter country ISO code.
from_date
string		The date the customer moved in to this address. The format is YYYY-MM-DD.
to_date
string		The date the customer moved out of this address. The format is YYYY-MM-DD. Leave as null if currently residing in address.

line, city, postal_code and country are the minimum required attributes for a valid address . Where the address breakdown is available, please ensure they are supplied into the correct attributes. For example, use property_number and property_name if known, rather than storing them into line or extra_line.

As part of the match object, only the available address attributes will be returned - for example the postal_code will not be returned when not available for a given watchlist entity.

Example Response
{
    "id": "{CUSTOMER_ID}",
    "created_at": "2017-01-17T23:46:26Z",
    "updated_at": "2017-01-17T23:46:26Z",
    "type" : "INDIVIDUAL",
    "title" : "MR",
    "first_name" : "John",
    "middle_name": "A.",
    "last_name" : "Doe",
    "email" : "john.doe@example.com",
    "dob" : "1980-01-01",
    "gender": "MALE",
    "addresses" : [
        {
            "type": "PRIMARY",
            "property_name": "Custom House",
            "line": "Main Street",
            "extra_line": "City Square",
            "city": "Aldgate",
            "state_or_province": "London",
            "postal_code": "E99 0ZZ",
            "country": "GBR",
            "from_date": "2010-01-01"
        }
    ]
}

Create Customer

Attributes

ParameterDescription
type
Individual and Company
required		The customer type. Valid values are INDIVIDUAL or COMPANY.
joined_at
Individual and Company
optional		The date and time when the customer was registered with you. This is relevant for users that migrate existing customers.
email
Individual and Company
required		The customer’s email address.
telephone
Individual and Company
optional		The customer’s telephone number.
mobile
Individual and Company
optional		The customer’s mobile number.
addresses
Individual and Company
optional		A list of addresses associated with customer.
title
Individual
optional		The customer’s title. Valid values are MR, MRS, MISS, or MS.
first_name
Individual
required		The customer’s first name.
middle_name
Individual
optional		The customer’s middle name
last_name
Individual
required		The customer’s last name.
maiden_name
Individual
optional		The customer’s maiden.
alternative_first_name
Individual
optional		The customer’s alternative or new first name.
alternative_middle_name
Individual
optional		The customer’s alternative or new middle name.
alternative_last_name
Individual
optional		The customer’s alternative or new last name.
dob
Individual
optional		The customer’s date of birth. The format is YYYY-MM-DD.
gender
Individual
optional		The customer’s gender. Valid values are MALE, FEMALE, or OTHER.
nationality
Individual
optional		The customer’s nationality. This will be the three-letter country .
birth_country
Individual
optional		The customer’s country of birth. This will be the three-letter country .
special_occupation
Individual
string		The customer’s occupation. Valid values can be any of the occupation categories we support.
company_name
Company
required		The company name.
alternative_company_name
Company
string		The company’s alternative or new name.
incorporation_number
Company
optional		The company’s incorporation number.
incorporation_type
Company
optional		The company’s incorporation type. Valid values are:
1.SOLE_TRADER
2.PRIVATE_LIMITED
3.LIMITED_LIABILITY_PARTNERSHIP
4.PUBLIC_LIMITED
business_purpose
Company
optional		The company’s business purpose. Valid values are:
1.REGULATED_ENTITY
2.PRIVATE_ENTITY
3.UNREGULATED_FUND
4.TRUST
5.FOUNDATION
6.RELIGIOUS_BODY
7.GOVERNMENT_ENTITY
8.CHARITY
9.CLUB
10.SOCIETY
incorporation_country
Company
optional		The company’s country of incorporation. This will be the three-letter country .
primary_contact_name
Company
optional		The company’s primary contact full name.
primary_contact_email
Company
optional		The company’s primary contact email address.
  POST /v1/customers
 
  curl --location 'https://api.cleardil.com/v1/customers' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer api_token' \
  --data-raw '{
      "type" : "INDIVIDUAL",
      "email" : "jon@doe.com",
      "telephone" : "+91-9337888808",
      "mobile" : "+91-9337888808",
      "addresses" : [
              {
              "property_number": "10",
              "property_name": "Custom House",
              "line": "Main Street",
              "city": "Aldgate",
              "state_or_province": "London",
              "postal_code": "E99 0ZZ",
              "country": "GBR",
              "from_date": "2010-01-01"
          }
      ],
      "title" : "MRS",
      "first_name" : "Jon",
      "middle_name" : "Martin",
      "last_name" : "Doe",
      "maiden_name" : "Kiriku",
      "alternative_first_name" : "Jonathan",
      "alternative_middle_name" : "Martinero",
      "alternative_last_name" : "Patel",
      "dob" : "1971-04-06",
      "gender": "MALE",
      "nationality" : "IND",
      "birth_country" : "IND"
  }'
Example Response
{
  "id": "{CUSTOMER_ID}",
  "created_at": "2017-01-17T23:46:26Z",
  "updated_at": "2017-01-17T23:46:26Z",
  "type": "INDIVIDUAL",
  "title": "MR",
  "first_name": "John",
  "middle_name": "A.",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "dob": "1980-01-01",
  "gender": "MALE",
  "addresses": [
    {
      "type": "PRIMARY",
      "property_name": "Custom House",
      "line": "Main Street",
      "extra_line": "City Square",
      "city": "Aldgate",
      "state_or_province": "London",
      "postal_code": "E99 0ZZ",
      "country": "GBR",
      "from_date": "2010-01-01"
    }
  ]
}

Retrieve a Customer

ParameterDescription
customer_id
required		The unique identifier for the customer.
  GET /v1/customers/{customer_id}
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}' \
      --header 'Authorization: Bearer api_token'
Example Response
{
    "id": "{CUSTOMER_ID}",
    "created_at": "2017-01-24T12:30:10Z",
    "updated_at": "2017-01-24T12:30:10Z",
    "type": "COMPANY",
    "company_name": "John Doe's Bakery",
    "incorporation_type": "PRIVATE_LIMITED",
    "incorporation_country": "GBR",
    "business_purpose": "PRIVATE_ENTITY",
    "email": "company@example.com",
    "primary_contact_name": "John Doe",
    "primary_contact_email": "john.doe@example.com",
    "addresses":[
        {
            "type": "PRIMARY",
            "property_number": "10",
            "property_name": "Atrium House",
            "line": "Main Business Park",
            "city": "Knutsford",
            "state_or_province": "Cheshire",
            "postal_code": "W99 6ZZ",
            "country": "GBR",
            "from_date": "2015-01-01"
       }
    ]
}

Update a Customer

Updates the details of an existing customer. This is an idempotent method and will require all fields you have on the customer to be provided as part of request. This will ensure customer details held in your system are in line with the details held by ClearDil.

Please note, the customer type will not be editable once set. Additionally, certain fields will not be editable once the customer has undergone a check:

  • For individuals - first_name, middle_name, last_name and dob.
  • For companies - company_name.

Attributes

ParameterDescription
customer_id
required		The unique identifier for the customer.
joined_at
Individual and Company		The date and time when the customer was registered with you. This is relevant for users that migrate existing customers.
email
Individual and Company		The customer’s email address.
telephone
Individual and Company		The customer’s telephone number.
mobile
Individual and Company		The customer’s mobile number.
addresses
Individual and Company		A list of addresses associated with customer.
title
Individual		The customer’s title. Valid values are MR, MRS, MISS, or MS.
first_name
Individual		The customer’s first name.
middle_name
Individual		The customer’s middle name.
last_name
Individual		The customer’s last name.
maiden_name
Individual		The customer’s maiden.
alternative_first_name
Individual		The customer’s alternative or new first name.
alternative_middle_name
Individual		The customer’s alternative or new middle name.
alternative_last_name
Individual		The customer’s alternative or new last name.
dob
Individual		The customer’s date of birth. The format is YYYY-MM-DD.
gender
Individual		The customer’s gender. Valid values are MALE, FEMALE, or OTHER.
nationality
Individual		The customer’s nationality. This will be the three-letter country .
birth_country
Individual		The customer’s country of birth. This will be the three-letter country .
special_occupation
Individual
string		The customer’s occupation. Valid values can be any of the occupation categories we support.
company_name
Company		The company name.
alternative_company_name
Company		The company’s alternative or new name.
incorporation_number
Company		The company’s incorporation number.
incorporation_type
Company		The company’s incorporation type. Valid values are:
1.SOLE_TRADER
2.PRIVATE_LIMITED
3.LIMITED_LIABILITY_PARTNERSHIP
4.PUBLIC_LIMITED
business_purpose
Company		The company’s business purpose. Valid values are:
1.REGULATED_ENTITY
2.PRIVATE_ENTITY
3.UNREGULATED_FUND
4.TRUST
5.FOUNDATION
6.RELIGIOUS_BODY
7.GOVERNMENT_ENTITY
8.CHARITY
9.CLUB
10.SOCIETY
incorporation_country
Company		The company’s country of incorporation. This will be the three-letter country .
primary_contact_name
Company		The company’s primary contact full name.
primary_contact_email
Company		The company’s primary contact email address.
  PUT /v1/customers/{customer_id}
 
  curl --location --globoff --request PUT 'https://api.cleardil.com/v1/customers/{customer_id}' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer api_token' \
      --data-raw '{
          "type" : "INDIVIDUAL",
          "email" : "jon@doe.com",
          "telephone" : "+91-9337888811",
          "mobile" : "+91-9337888811",
          "addresses" : [
                  {
                  "property_number": "11",
                  "property_name": "Custom House update",
                  "line": "Main Street update",
                  "city": "Aldgate update",
                  "state_or_province": "London update",
                  "postal_code": "E99 011",
                  "country": "GBR",
                  "from_date": "2010-01-01"
              }
          ],
          "title" : "MRS",
          "first_name" : "Jony",
          "middle_name" : "Martini",
          "last_name" : "Doe",
          "maiden_name" : "Kiriku",
          "alternative_first_name" : "Jonathan",
          "alternative_middle_name" : "Martinero",
          "alternative_last_name" : "Patello",
          "dob" : "1971-04-06",
          "gender": "MALE",
          "nationality" : "IND",
          "birth_country" : "IND"
      }'
Example Response
  {
      "id": "{CUSTOMER_ID}",
      "created_at": "2017-01-17T23:46:26Z",
      "updated_at": "2017-02-01T12:10:11Z",
      "type" : "INDIVIDUAL",
      "title" : "MR",
      "first_name" : "John",
      "middle_name": "Smith",
      "last_name" : "Doe",
      "email" : "john.doe@example.com",
      "dob" : "1980-01-01",
      "gender": "MALE",
      "addresses": [
          {
              "type": "PRIMARY",
              "property_name": "Custom House",
              "line": "Main Street",
              "extra_line": "City Square",
              "city": "Aldgate",
              "state_or_province": "London",
              "postal_code": "E99 0ZZ",
              "country": "GBR",
              "from_date": "2010-01-01"
          }
      ]
  }

Partially Update a Customer

Partially updates the details of an existing customer.

Please note the update customer constraints apply here too. Only fields to be updated should be provided in the request as a JSON patch object.

 
  PATCH /v1/customers/{customer_id}
 
  curl --location --globoff --request PATCH 'https://api.cleardil.com/v1/customers/{customer_id}' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {{accessTokenUserB}}' \

Delete a Customer

Deletes an existing customer. You need only supply the unique customer identifier that was returned upon customer creation. Also deletes any documents and notes on the customer.

 
  DELETE /v1/customers/{customer_id}
 
  curl --location --globoff --request DELETE 'https://api.cleardil.com/v1/customers/{customer_id}' \
    --header 'Authorization: Bearer api_token' \
    --data ''

Attributes

ParameterDescription
customer_id
required		The unique identifier for the customer.

List all Customers

Lists all existing customers. The customers are returned sorted by creation date, with the most recent customers appearing first. In addition to the attributes listed on the pagination section, the following optional parameters can be used to refine the response.

 
  GET /v1/customers
 
  curl --location 'https://api.cleardil.com/v1/customers?page=0&size=2&sort=last_name%2CDESC' \
      --header 'Authorization: Bearer api_token'
ParameterDescription
created_after
optional		A “greater than” filter on the list based on the object created_at field.
created_before
optional		A “less than” filter on the list based on the object created_at field.
updated_after
optional		A “greater than” filter on the list based on the object updated_at field.
updated_before
optional		A “less than” filter on the list based on the object updated_at field.
email
optional		A “contains” filter on the list based on the object email field.
first_name
optional		A “contains” filter on the list based on the object first_name field.
middle_name
optional		A “contains” filter on the list based on the object middle_name field.
last_name
optional		A “contains” filter on the list based on the object last_name field.
company_name
optional		A “contains” filter on the list based on the object company_name field.
joined_after
optional		A “greater than” filter on the list based on the object joined_at field.
joined_before
optional		A “less than” filter on the list based on the object joined_at field.
postal_code
optional		An “equal” filter on the list based on the object postal_code field.
country
optional		An “equal” filter on the list based on the object country field.
type
optional		An “equal” filter on the list based on the object type field.

Risk profile

The risk profile is designed to provide you with a high-level snapshot of the key customer attributes and risk indicators that will assist you in shaping your ongoing customer relationship. It facilitates a risk-based framework for Client Due Diligence (CDD) and Enhanced Due Diligence (EDD).
The values of the risk profile are calculated by ClearDil’s proprietary risk engine and cannot be overridden.

The risk attributes are indicative. Therefore, we recommend you exercise the necessary due diligence and controls in line with your risk-based approach.

The API allows you to retrieve your customer’s risk profile.

The Risk Profile Object

ParameterDescription
profile
hash, profile object		Represents a set of attributes key to customer on-boarding. The attributes are automatically derived from the various checks and operations conducted on your customers.
risk
hash, risk object		Represents a set of key risk factors associated with your customer, to assist you with on-boarding and due diligence.
last_trigger
string		The trigger that caused the latest update. Valid values are:
1.CUSTOMER_CREATED
2.PERSONAL_DETAILS_UPDATE“
3.CUSTOMER_SCREENING
4.ODD_SCREENING
5.COUNTRY_SCORE_UPDATE
6.OCCUPATION_SCORE_UPDATE
last_updated
datetime		The date and time when the risk profile was last updated.
Example Response
  {
    "profile": {
        "politically_exposed": false,
        "disqualified_entity": false,
        "watchlist_entity": false,
        "relative_or_close_associate": false,
        "adverse_media_exposed": null,
    },
    "risk": {
        "political_exposure": "LOW",
        "occupation": "LOW",
        "country": "LOW",
        "watchlist": null,
        "relationship": null,
        "overall": "LOW"
    },
    "last_trigger": "PERSONAL_DETAILS_UPDATE",
    "last_updated": "2017-06-26T12:09:34Z"
}
PROFILE

Attributes

ParameterDescription
watchlist_entity
boolean		This will be set to true if a customer is found to be in a global sanctions and watchlists, or false if no watchlist relation is found. Default value is null if no relevant checks or operations have been conducted.
politically_exposed
boolean		This will be set to true if a customer is found to be politically exposed, or false if no political exposure is found. Default value is null if no relevant checks or operations have been conducted.
disqualified_entity
boolean		This will be set to true if a customer is found to be a disqualified entity, or false if no disqualification is found. Default value is null if no relevant checks or operations have been conducted.
relative_or_close_associate
boolean		This will be set to true if a customer is found to be related to a politically exposed or watchlist entity (company or individual), or false if no relation is found. Default value is null if no relevant checks or operations have been conducted.
adverse_media_exposed
boolean		This will be set to true if a customer is found to be associated with adverse media, or false if no adverse media relation is found. Default value is null if no relevant checks or operations have been conducted.
RISK

Attributes

ParameterDescription
watchlist
string		This indicates watchlist risk level, which is automatically calculated by ClearDil upon the completion of a screening request with watchlist in its scope. Valid values are HIGH when set, or null when not set.
political_exposure
string		This indicates political exposure level, which is automatically calculated by ClearDil upon the completion of a screening request with PEP in its scope. Valid values are HIGH, MEDIUM and LOW when set, or null when not set.
relationship
string		This indicates relationship risk level, which is automatically calculated by ClearDil upon the completion of a screening request. Valid values are HIGH, MEDIUM and LOW when set, or null when not set.
occupation
string		This represents the occupation risk level, which is automatically calculated by ClearDil upon the completion of a screening request with PEP in its scope. This is only applicable to customers with political exposure. Valid values are HIGH, MEDIUM and LOW when set, or null when not set.
country
string		This represents the country risk level, which is automatically calculated by ClearDil based on customer country details, which include the address, nationality, and incorporation_country. Valid values are HIGH, MEDIUM and LOW when set, or null when not set.
overall
string		Overall risk score based on all available risk scores. Valid values are HIGH, MEDIUM and LOW when set, or null when not set.

Retrieve a Risk Profile

Retrieves the risk profile of an existing customer.

Attributes

ParameterDescription
text
required		The text of the note.
 
  GET /v1/customers/{customer_id}/risk_profile
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/risk_profile' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer api_token'
Example Response
  {
  "profile": {
      "politically_exposed": false,
      "disqualified_entity": false,
      "watchlist_entity": false,
      "relative_or_close_associate": false,
      "adverse_media_exposed": null,
  },
  "risk": {
      "political_exposure": "LOW",
      "occupation": "LOW",
      "country": "LOW",
      "watchlist": null,
      "relationship": null,
      "overall": "LOW"
  },
  "last_trigger": "PERSONAL_DETAILS_UPDATE",
  "last_updated": "2017-06-26T12:09:34Z"
 }

Documents

Documents can be created for a given customer for the following purposes:

  • Secure and centralised document storage.
  • Perform certain checks such as authenticity and integrity analysis for ID documents e.g passport

The documents API allows you to create, update, and delete documents. It also provide you with ability to upload relevant attachments to our global document delivery infrastructure.

A document can be created without any attachments as they are optional. This means the document object can used to capture your customer’s document details without the need of uploading any attachments. These can be uploaded at a later time.

The Document Object

Attributes

ParameterDescription
id
string		The unique identifier for the document.
created_at
datetime		The date and time when the document was created.
updated_at
datetime		The date and time when the document was updated.
type
string		The type of document. Valid values are:
1. PASSPORT
2. DRIVING_LICENSE
3. NATIONAL_INSURANCE_NUMBER
4. SOCIAL_SECURITY_NUMBER
5. TAX_ID_NUMBER
6. NATIONAL_ID_CARD
7. VISA
8. POLLING_CARD
9. RESIDENCE_PERMIT
10. OTHER
issuing_country
string		The country that issued the document. This will be the three-letter country ISO code.
issuing_authority
string		The authority or organisation that issued the document.
document_number
string		The unique number associated with document e.g. passport number for a document of type PASSPORT.
document_name
string		The name of the document e.g. Bank Letter.
document_description
string		The description of the document e.g. Bank letter confirming John Doe’s address history.
mrz_line1
string		The first line of MRZ string.
mrz_line2
string		The second line of MRZ string.
mrz_line3
string		The third line of MRZ string.
front_side
hash, file attachments object		The list of attributes pertaining to the front side file attachment of the document.
back_side
hash, file attachments object		The list of attributes pertaining to the back side file attachment of the document.
issue_date
date		The issue date of the document. The format is YYYY-MM-DD.
expiry_date
date		The expiry date of the document. The format is YYYY-MM-DD.
Example Response
 {
   "id": "{DOCUMENT_ID}",
   "type": "PASSPORT",
   "document_name": "Customer passport",
   "document_description": "Primary ID document",
   "document_number": "N1234567890",
   "issuing_country": "GBR",
   "issue_date": "2010-01-01",
   "expiry_date": "2020-01-01",
   "created_at": "2017-06-28T08:04:32Z",
   "updated_at": "2017-06-28T08:04:32Z",
   "front_side": {
       "id": "{FILE_ID}",
       "created_at": "2017-06-28T08:04:32Z",
       "updated_at": "2017-06-28T08:04:32Z",
       "filename": "foo.jpg",
       "content_type": "image/jpeg",
       "size": 15,
       "locked" : false
   },
   "back_side": {
       "id": "{FILE_ID}",
       "created_at": "2017-06-28T08:04:32Z",
       "updated_at": "2017-06-28T08:04:32Z",
       "filename": "bar.jpg",
       "content_type": "image/jpeg",
       "size": 15,
       "locked" : false
   },
   "mrz_line1": "IDFRABERTHIER<<<<<<<<<<<<<<<<<<<<<<<",
   "mrz_line2": "N1234567890JOHN<<<<<<<<<<<<6512068F4"
 }

Create and Upload a document

Creates a new document object. Optionally, attachments can be uploaded as part of the document creation. Attachments must be uploaded as a multi-part form and the file size must not exceed 4MB. We recommend using files less than 2MB.

In order to upload the back side of a document, the front side must be provided too.

Attributes
ParameterDescription
type
required		The type of document. Valid values are:
1. PASSPORT
2. DRIVING_LICENSE
3. NATIONAL_INSURANCE_NUMBER
4. SOCIAL_SECURITY_NUMBER
5. TAX_ID_NUMBER
6. NATIONAL_ID_CARD
7. VISA
8. POLLING_CARD
9. RESIDENCE_PERMIT
10. OTHER
issuing_country
optional		The country that issued the document. This will be the three-letter country ISO code.
issuing_authority
optional		The authority or organisation that issued the document.
document_number
optional		The unique number associated with document e.g. passport number for a document of type PASSPORT.
document_name
optional		The name of the document e.g. Bank Letter.
document_description
optional		The description of the document e.g. Bank letter confirming John Doe’s address history.
mrz_line1
optional		The first line of MRZ string.
mrz_line2
optional		The second line of MRZ string.
mrz_line3
optional		The third line of MRZ string.
front_side
optional		The list of attributes pertaining to the front side file attachment of the document.
back_side
optional		The list of attributes pertaining to the back side file attachment of the document.
issue_date
optional		The issue date of the document. The format is YYYY-MM-DD.
expiry_date
optional		The expiry date of the document. The format is YYYY-MM-DD.
 
  POST /v1/customers/{customer_id}/document
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/documents' \
      --header 'Authorization: Bearer 85b36cf1-fa53-4f55-bd1a-2b66d139e5f3' \
      --header 'Content-Type: multipart-formdata' \
      --form 'front_side=@"/path/to/file"' \
      --form 'type="DRIVING_LICENSE"' \
      --form 'document_name="driving licence "' \
      --form 'document_description="driving licence"' \
      --form 'document_number="N1234567890"' \
      --form 'issuing_country="USA"' \
      --form 'issue_date="2017-01-01"' \
      --form 'expiry_date="2027-01-01"'
Example Response
{
  "id": "{DOCUMENT_ID}",
  "type": "PASSPORT",
  "document_name": "Customer passport",
  "document_description": "Primary ID document",
  "document_number": "N1234567890",
  "issuing_country": "GBR",
  "issue_date": "2010-01-01",
  "expiry_date": "2020-01-01",
  "created_at": "2017-06-28T08:04:32Z",
  "updated_at": "2017-06-28T08:04:32Z",
  "front_side": {
      "id": "{FILE_ID}",
      "created_at": "2017-06-28T08:04:32Z",
      "updated_at": "2017-06-28T08:04:32Z",
      "filename": "foo.jpg",
      "content_type": "image/jpeg",
      "size": 15,
      "locked" : false
  },
  "back_side": {
      "id": "{FILE_ID}",
      "created_at": "2017-06-28T08:04:32Z",
      "updated_at": "2017-06-28T08:04:32Z",
      "filename": "bar.jpg",
      "content_type": "image/jpeg",
      "size": 15,
      "locked" : false
  },
  "mrz_line1": "IDFRABERTHIER<<<<<<<<<<<<<<<<<<<<<<<",
  "mrz_line2": "N1234567890JOHN<<<<<<<<<<<<6512068F4"
}

Retrieve a Document

Retrieves the details of an existing document. You need to supply the unique customer and document identifier.

Attributes
ParameterDescription
customer_id
required		The unique identifier for the customer.
document_id
required		The unique identifier for the document.
 
  GET /v1/customers/{customer_id}/documents/{document_id}
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/documents/{document_id}' \
       --header 'Authorization: Bearer 85b36cf1-fa53-4f55-bd1a-2b66d139e5f3'
Example Response
  {
    "id": "{DOCUMENT_ID}",
    "type": "PASSPORT",
    "document_name": "Customer passport",
    "document_description": "Primary ID document",
    "document_number": "N1234567890",
    "issuing_country": "GBR",
    "issue_date": "2010-01-01",
    "expiry_date": "2020-01-01",
    "created_at": "2017-06-28T08:04:32Z",
    "updated_at": "2017-06-28T08:04:32Z",
    "front_side": {
        "id": "{FILE_ID}",
        "created_at": "2017-06-28T08:04:32Z",
        "updated_at": "2017-06-28T08:04:32Z",
        "filename": "foo.jpg",
        "content_type": "image/jpeg",
        "size": 15,
        "locked" : false
    },
    "back_side": {
        "id": "{FILE_ID}",
        "created_at": "2017-06-28T08:04:32Z",
        "updated_at": "2017-06-28T08:04:32Z",
        "filename": "bar.jpg",
        "content_type": "image/jpeg",
        "size": 15,
        "locked" : false
    },
    "mrz_line1": "IDFRABERTHIER<<<<<<<<<<<<<<<<<<<<<<<",
    "mrz_line2": "N1234567890JOHN<<<<<<<<<<<<6512068F4"
  }

Download a Document

Downloads a previously uploaded document. You need to supply the unique customer and document identifier. Optionally, you can specify which side of a document to download by specifying the side parameter, with front or back as the value. When the side parameter is not explicitly specified, the front side will be downloaded by default.

Attributes

Parameter                      		Description
customer_id
required		The unique identifier for the customer.
document_id
required		The unique identifier for the document.
side
optional		The side of the document to download. Valid values are front or back. When not specified, the front side will be downloaded.
 
  GET /v1/customers/{customer_id}/documents/{document_id}/download
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/documents/{document_id}/download' \
  --header 'Authorization: Bearer 85b36cf1-fa53-4f55-bd1a-2b66d139e5f3'

Update a Document

Updates the details of an existing document. This is an idempotent method and will require all fields you have on the document (including attachments if applicable) to be provided as part of request. This will ensure document details held in your system are in line with the details held by ClearDil.

Please note, a document attachment will not be editable once it had undergone a image verification check. Similarly, the MRZ lines will not be editable once an MRZ verification check had been made.

Attributes
ParameterDescription
customer_id
required		The unique identifier for the customer.
document_id
required		The unique identifier for the document.
type
The type of document. Valid values are:
1. PASSPORT
2. DRIVING_LICENSE
3. NATIONAL_INSURANCE_NUMBER
4. SOCIAL_SECURITY_NUMBER
5. TAX_ID_NUMBER
6. NATIONAL_ID_CARD
7. VISA
8. POLLING_CARD
9. RESIDENCE_PERMIT
10. OTHER
issuing_country
The country that issued the document. This will be the three-letter country ISO code.
issuing_authority
The authority or organisation that issued the document.
document_number
The unique number associated with document e.g. passport number for a document of type PASSPORT.
document_name
The name of the document e.g. Bank Letter.
document_description
The description of the document e.g. Bank letter confirming John Doe’s address history.
mrz_line1
The first line of MRZ string.
mrz_line2
The second line of MRZ string.
mrz_line3
The third line of MRZ string.
front_side
The list of attributes pertaining to the front side file attachment of the document.
back_side
The list of attributes pertaining to the back side file attachment of the document.
issue_date
The issue date of the document. The format is YYYY-MM-DD.
expiry_date
The expiry date of the document. The format is YYYY-MM-DD.
 
  PUT /v1/customers/{customer_id}/documents/{document_id}
 
  curl --location --globoff --request PUT 'https://api.cleardil.com/v1/customers/{customer_id}/documents/{document_id}' \
      --header 'Authorization: Bearer 85b36cf1-fa53-4f55-bd1a-2b66d139e5f3' \
      --form 'type="NATIONAL_ID_CARD"' \
      --form 'document_name="NIC"' \
      --form 'document_description="National Id Card"' \
      --form 'document_number="N1234567890"' \
      --form 'issuing_country="USA"' \
      --form 'issue_date="2010-01-01"' \
      --form 'expiry_date="2020-01-01"' \
      --form 'front_side=@"/path/to/file"' \
      --form 'back_side=@"/path/to/file"'
Example Response
  {
    "id": "{document_id}",
    "type": "DRIVING_LICENSE",
    "document_name": "Customer driving license",
    "document_description": "Primary ID document",
    "document_number": "N1234567890",
    "issuing_country": "GBR",
    "issue_date": "2010-01-01",
    "expiry_date": "2020-01-01",
    "created_at": "2017-06-28T08:04:32Z",
    "updated_at": "2017-06-28T12:01:06Z",
    "front_side": {
        "id": "{FILE_ID}",
        "created_at": "2017-06-28T08:04:32Z",
        "updated_at": "2017-06-28T08:04:32Z",
        "filename": "foo.jpg",
        "content_type": "image/jpeg",
        "size": 15,
        "locked" : false
    },
    "back_side": {
        "id": "{FILE_ID}",
        "created_at": "2017-06-28T08:04:32Z",
        "updated_at": "2017-06-28T08:04:32Z",
        "filename": "bar.jpg",
        "content_type": "image/jpeg",
        "size": 15,
        "locked" : false
    }
  }

Partially update a document

Partially updates the details of an existing document. Please note the update document constraints apply here too. Only fields to be updated should be provided in the request as a JSON patch object.

 
  PATCH /v1/customers/{customer_id}/documents/{document_id}
 
 curl --location --globoff --request PATCH 'https://api.cleardil.com/v1/customers/{customer_id}/documents/{document_id}' \
      --header 'Authorization: Bearer 85b36cf1-fa53-4f55-bd1a-2b66d139e5f3' \
      --header 'Content-Type: application/json' \
      --data '[
          {
              "op": "replace",
              "path": "/type",
              "value": "DRIVING_LICENSE"
          }
        ]'

List all Documents

Lists all existing documents associated with a given customer. The documents are returned sorted by creation date, with the most recent documents appearing first. In addition to the attributes listed on the pagination section, the following optional parameters can be used to refine the response.

Attributes
ParameterDescription
created_after
optional		A “greater than” filter on the list based on the object created_at field.
created_before
optional		A “less than” filter on the list based on the object created_at field.
updated_after
optional		A “greater than” filter on the list based on the object updated_at field.
updated_before
optional		A “less than” filter on the list based on the object updated_at field.
type
optional		An “equal” filter on the list based on the object type field.
 
  GET /v1/customers/{customer_id}/documents
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/documents' \
        --header 'Authorization: Bearer 85b36cf1-fa53-4f55-bd1a-2b66d139e5f3'

Screenings

ClearDil enables you to meet your AML screening commitments through the application of our proprietary scorecard and fuzzy logic to screen your customer against our comprehensive database.

The API allows you to create and retrieve screening requests. Depending on the scope, a request can include the following screening types : global watchlists (including CIA Watchlists, Government Sanctions, Anti-Terrorism and AML Watchlists), Politically Exposed Persons (PEPs), adverse media and disqualified entities.

The Screening object

Attributes
ParameterDescription
id
string		The unique identifier for the screening.
customer_id
string		The unique identifier for the customer.
report_id
string		The unique identifier for the report. This is generated once a screening status is DONE.
entity_name
string		The concatenated first_name and last_name of the customer if an individual, or company_name if a company.
created_at
datetime		The date and time when the screening was created.
updated_at
datetime		The date and time when the screening or related matches were updated.
scope
list screening type		The list of screening types to be performed.
outcome
hash		Provides summary of screening result, in line with the selected screening scope. The format will be a list of key-value pairs where each of the keys is the screening scope and the value is the screening result.
status
string		The overall status of the screening for the entire scope. Values can be:
1. CREATED - indicates screening request is created.
2. PENDING - indicates one or more of the screenings in scope are either IN_PROGRESS or AWAITING_VALIDATION.
3. DONE - indicates all the screenings in scope have been completed by ClearDil and matches validated via the matches API where applicable. This means, all the screenings in scope have a status of CONFIRMED, DISMISSED or CLEAR.
Example Response
  {
    "id": "{SCREENING_ID}",
    "customer_id": "{CUSTOMER_ID}",
    "entity_name": "Jane Doe",
    "created_at": "2017-01-21T13:00:16Z",
    "updated_at": "2017-01-21T13:00:16Z",
    "scope": ["PEP","WATCHLIST","DISQUALIFIED_ENTITIES"],
    "status": "PENDING",
    "outcome": {
        "PEP": "CLEAR",
        "WATCHLIST": "AWAITING_VALIDATION",
        "DISQUALIFIED_ENTITIES": "CLEAR"
    }
 }
Screening Type

The following table outlines the various screening types available and their respective country coverage.

ScopeDescriptionCoverage
WATCHLISTWe will search your customer against our global watchlists. We will also highlight if your customer is Related or a Close Associate (RCA) of a watchlist or sanctioned entity, be it an individual or an organisation.Global
PEPWe will search your customer against our politically exposed persons (PEP) database. We will also highlight if your customer is Related or a Close Associate (RCA) of a PEP entity.Global
DISQUALIFIED_ENTITIESWe will search your customer against our disqualified entities database which also includes disqualified , banned and barred individuals and companies.Global
ADVERSE_MEDIAWe will search your customer against our adverse media database of hand-picked articles from trusted news outlets.Global
Screening Result
Screening Result and Description
ResultDescription
IN_PROGRESSIndicates the screening is still being processed by ClearDil.
AWAITING_VALIDATIONIndicates ClearDil has found one or more potential matches against your customer. These matches will require manual validation using the Matches endpoint.
CONFIRMEDIndicates at least one match has been confirmed using the Matches endpoint.
DISMISSEDIndicates that all the screening matches have been dismissed by you as they were not deemed to be genuine matches (i.e. false positives).
CLEARIndicates ClearDil has not found your customer or any potential matches in the relevant databases, as per the scope you specified. Potential matches are determined by ClearDil’s fuzzy scorecard logic and the pre-defined sensitivity thresholds.

Create a screening

Creates a new screening object.

Attributes
ParameterDescription
scope
required		A list of the screenings to be performed.
 
   POST /v1/customers/{customer_id}/screenings
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/screenings' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer 85b36cf1-fa53-4f55-bd1a-2b66d139e5f3' \
        --data '[
          "pep",
          "watchlist",
          "disqualified_entities",
          "adverse_media"
        ]'
Example Response
  {
    "id": "{SCREENING_ID}",
    "customer_id": "{CUSTOMER_ID}",
    "entity_name": "Jane Doe",
    "created_at": "2017-01-21T13:00:16Z",
    "updated_at": "2017-01-21T13:00:16Z",
    "scope": ["PEP","WATCHLIST","DISQUALIFIED_ENTITIES"],
    "status": "PENDING",
    "outcome": {
        "PEP": "CLEAR",
        "WATCHLIST": "AWAITING_VALIDATION",
        "DISQUALIFIED_ENTITIES": "CLEAR"
    }
 }

Retrieve a screening

Retrieves the details of an existing screening. You need to supply the unique customer and screening identifier.

Attributes
ParameterDescription
customer_id
required		The unique identifier for the customer.
screening_id
required		The unique identifier for the screening.
 
   GET /v1/customers/{customer_id}/screenings/{screening_id}
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer 85b36cf1-fa53-4f55-bd1a-2b66d139e5f3'
Example Response
  {
    "id": "{SCREENING_ID}",
    "customer_id": "{CUSTOMER_ID}",
    "entity_name": "Jane Doe",
    "created_at": "2017-01-21T13:00:16Z",
    "updated_at": "2017-01-21T13:00:16Z",
    "scope": ["PEP","WATCHLIST","DISQUALIFIED_ENTITIES"],
    "status": "PENDING",
    "outcome": {
        "PEP": "CLEAR",
        "WATCHLIST": "AWAITING_VALIDATION",
        "DISQUALIFIED_ENTITIES": "CLEAR"
    }
 }

List all screenings for customer

Lists all existing screenings for a given customer. The screenings are returned sorted by creation date, with the most recent screenings appearing first. In addition to the attributes listed on the pagination section, the following optional parameters can be used to refine the response.

Attributes
ParameterDescription
created_after
optional		A “greater than” filter on the list based on the object created_at field.
created_before
optional		A “less than” filter on the list based on the object created_at field.
updated_after
optional		A “greater than” filter on the list based on the object updated_at field.
updated_before
optional		A “less than” filter on the list based on the object updated_at field.
scope
optional		An “equal” filter on the list based on the object scope field.
status
optional		An “equal” filter on the list based on the object status field.
 
   GET /v1/customers/{customer_id}/screenings
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/screenings' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer 85b36cf1-fa53-4f55-bd1a-2b66d139e5f3'

Search screenings

Search for screenings across all existing customers. The screenings are returned sorted by creation date, with the most recent screenings appearing first. The following optional parameters can be used to refine the response.

Attributes
ParameterDescription
created_after
optional		A “greater than” filter on the list based on the object created_at field.
created_before
optional		A “less than” filter on the list based on the object created_at field.
updated_after
optional		A “greater than” filter on the list based on the object updated_at field.
updated_before
optional		A “less than” filter on the list based on the object updated_at field.
customer_ids
optional		A “equal’ filter on the list based on the customer object id field. This can be a list.
scope
optional		An “equal” filter on the list based on the object scope field.
status
optional		An “equal” filter on the list based on the object status field.
 
   GET /v1/search/screenings
 
  curl --location 'https://api.cleardil.com/v1/search/screenings' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer 85b36cf1-fa53-4f55-bd1a-2b66d139e5f3'

Matches

A screening request may result in one or multiple matches. A match object represents a potential match as determined by ClearDil’s fuzzy scorecard logic and pre-defined thresholds.

The matches API allows you to retrieve and validate matches relating to a given screening request. The validation of a potential match refers to either confirmation or dismissal of the match once you have reviewed the details at hand.

The Match object

Attributes
ParameterDescription
id
Individual and Company string		The unique identifier for the match.
created_at
Individual and Company datetime		The date and time when the match was created.
updated_at
Individual and Company datetime		The date and time when the match was last updated.
entity_type
Individual and Company string		The type of the matched entity. Values can be INDIVIDUAL or COMPANY.
validation_result
Individual and Company string		The result of the matches confirmation or dismissal process. Values can be AWAITING_VALIDATION, CONFIRMED, or DISMISSED.
match_type
Individual and Company list		The type of the match. Values can be:
1. SPECIAL_INTEREST_PERSON
2. SPECIAL_INTEREST_ENTITY
3. POLITICALLY_EXPOSED_PERSON
4. RELATIVE_OR_CLOSE_ASSOCIATE
5. BANNED_OR_DISQUALIFIED_PERSON
6. BANNED_OR_DISQUALIFIED_ENTITY
7. ADVERSE_MEDIA_PERSON
8. ADVERSE_MEDIA_ENTITY
names
Individual and Company list name		The matched individual or company names.
note
Individual and Company string		Additional notes if available on matched individual or company. When none available, this will be null.
documents
Individual and Company list document		The documents associated with matched individual or company. When not available, this will be null.
addresses
Individual and Company list address		The addresses associated with the matched individual or company. When not available, this will be null.
scorecard
Individual and Company hash, scorecard object_		Provides breakdown of scorecard results for potential matches.
references
Individual and Company list reference		The reference of listed information. When not available, this will be null.
associated_countries
Individual and Company list		The matched individual country of association. This will be the three-letter standard or non-standard country ISO code. When not available, this will be null.
jurisdiction
Individual and Company list		The matched individual associated jurisdiction. This will be the three-letter standard or non-standard country ISO code. When not available, this will be null.
countries_of_reported_allegation
Individual and Company list		The matched individual country of allegation. This will be the three-letter standard or non-standard country ISO code. When not available, this will be null.
countries_of_citizenship
Individual list		The matched individual country of citizenship. This will be the three-letter standard or non-standard country ISO code. When not available, this will be null.
countries_of_registration
Company list		The matched company country of registration. This will be the three-letter standard or non-standard country ISO code. When not available, this will be null.
countries_of_ownership
Company list		The matched company country of ownership. This will be the three-letter standard or non-standard country ISO code. When not available, this will be null.
countries_of_affiliation
Company list		The matched company country of affiliation. This will be the three-letter standard or non-standard country ISO code. When not available, this will be null.
countries_of_residence
Individual list		The matched individual country of residence. This will be the three-letter standard or non-standard country ISO code. When not available, this will be null.
dobs
Individual list structured date		The recorded date of births of matched individual. When not available, this will be null.
gender
Individual string		The matched individual gender. Values can be MALE, FEMALE, UNKNOWN, or OTHER.
birth_places
Individual list		The matched individual potential birth places. When not available, this will be null.
occupations
Individual list occupation		The matched individual occupation history. When not available, this will be null.
image_uri
Individual string		The URI to the image of the matched individual. When not available, this will be null.
deceased
Individual boolean		This will be set to true if the matched individual is deceased, false when alive, or null when unknown.
incorporation_number
Company string		The matched company incorporation number. When not available, this will be null.
NAME
Attributes
ParameterDescription
name_type
Individual and Company string		The name type, values can be:
1. PRIMARY_NAME
2. ALSO_KNOWN_AS
3. FORMERLY_KNOWN_AS
4. MAIDEN_NAME
5. SPELLING_VARIATION
6. EXPANDED_LANGUAGE_VARIATION
7. LOW_QUALITY_ALIAS
first_name
Individual string		The first name of the matched individual.
middle_name
Individual string		The middle name of the matched individual.
last_name
Individual string		The last name of the matched individual.
maiden_name
Individual string		The maiden name of the matched individual.
company_name
Company string		The name of the matched company.
original_script_name
Individual and Company string		The name of the matched individual or company, in original script.
DOCUMENT
Attributes
ParameterDescription
type
string		The type of document. Valid values are:
1. PASSPORT
2. DRIVING_LICENSE
3. NATIONAL_INSURANCE_NUMBER
4. SOCIAL_SECURITY_NUMBER
number
string		The unique number associated with a document e.g. passport number for a document of type PASSPORT.
note
string		A note associated with the document. When none available, this will be null.
STRUCTURED DATE
Attributes
ParameterDescription
day
integer		The day of birth. This will be null when not available. Format is DD.
month
integer		The month of birth. This will be null when not available. Format is MM.
year
integer		The year of birth. This will be null when not available. Format is YYYY.
OCCUPATION
Attributes
ParameterDescription
title
string		The title of the occupation.
type
string		The type of occupation. Values can be PRIMARY_OCCUPATION, PREVIOUS_ROLE, or OTHER_ROLE.
category
string		The category of occupation. Values can be:
1. HEADS_AND_DEPUTIES_STATE_OR_NATIONAL_GOVERNMENT
2. NATIONAL_GOVERNMENT_MINISTERS
3. MEMBERS_OF_THE_NATIONAL_LEGISLATURE
4. SENIOR_CIVIL_SERVANTS_NATIONAL_GOVERNMENT
5. SENIOR_CIVIL_SERVANTS_REGIONAL_GOVERNMENT
6. EMBASSY_AND_CONSULAR_STAFF
7. SENIOR_MEMBERS_OF_THE_ARMED_FORCES
8. SENIOR_MEMBERS_OF_THE_POLICE_SERVICES
9. SENIOR_MEMBERS_OF_THE_SECRET_SERVICES
10. SENIOR_MEMBERS_OF_THE_JUDICIARY
11. STATE_CORPORATION_EXECUTIVES
12. STATE_AGENCY_OFFICIALS
13. HEADS_AND_DEPUTY_HEADS_OF_REGIONAL_GOVERNMENT
14. REGIONAL_GOVERNMENT_MINISTERS
15. RELIGIOUS_LEADERS
16. POLITICAL_PARTY_OFFICIALS
17. INTERNATIONAL_ORGANISATION_OFFICIALS
18. CITY_MAYORS
19. LOCAL_PUBLIC_OFFICIALS
20. INTERNATIONAL_SPORTING_ORGANISATION_OFFICIALS
21. OTHER
from_date
structured date object		The date the individual commenced the occupation..
to_date
structured date object		The date the individual terminated occupation. This will be null if the the occupation is current.
REFERENCE
Attributes
ParameterDescription
name stringThe name of the reference.
from_date
structured date object		The date the reference information is effective from. This will be null if no date is applicable.
to_date
structured date object		The date the reference information is effective to. This will be null if no date is applicable.
status stringCurrent status of the reference. Possible values are CURRENT or SUSPENDED.
SCORECARD
Attributes
ParameterDescription
overall_score stringThe calculated match percentage, based on our ClearDil’s proprietary fuzzy matching engine. 100 indicates a perfect match. Only matches with scores breaching the pre-defined thresholds will be returned.
breakdown hash, breakdown objectThe breakdown of the scorecard.
BREAKDOWN

The breakdown consists of nested object following the convention below:

Attributes
ParameterDescription
field_name
string		Will specify the field assessed by the scorecard. For individual customers, the values are:
1. name
2. document
3. address
4. dob
5. gender
6. nationality

For companies, the values are:
1. name
2. document
3. address
4. incorporation_number
6. incorporation_country
field_value
string		The value of the field. Where more than one value exists, for example a matched individual has more than one name, the closest match will be returned.
score
number		The match percentage score we calculate for a field. 100 indicates a perfect match.
risk_weight
number		The weight of the risk associated with a given field. The higher the weight, in relation to other fields, the more impact it has on the overall_score.
risk_weighted_score
number		The risk weighted score of the field defined as the product of (score x risk_weight) / 100.
normalised_score
number		The normalised score of the field in relation to the overall_score. When this attribute is aggregated across the various fields, for a given match, it should equate the overall_score.
NON-STANDARD COUNTRY ISO CODE

The following table lists all non-standard country ISO codes used by ClearDil.

Attributes
ISO CodeDescription
000Unknown.
111International.
222Abkhazia.
333Kosovo.
444Curaçao.
555None.
666St. Maarten.
777South Ossetia.
888Turkish Republic of Northern Cyprus.
Example Response
  {
    "id": "{MATCH_ID}",
    "created_at": "2017-01-21T15:00:16Z",
    "updated_at": "2017-01-21T15:00:16Z",
    "entity_type": "INDIVIDUAL",
    "match_type": ["SPECIAL_INTEREST_PERSON"],
    "validation_result": "AWAITING_VALIDATION",
    "names": [
        {
            "name_type": "PRIMARY_NAME",
            "first_name": "John",
            "last_name": "Doe"
        },
        {
            "name_type": "ALSO_KNOWN_AS",
            "first_name": "Jo",
            "last_name": "Doe"
        }
    ],
    "documents": [
        {
            "type": "PASSPORT",
            "number": "A123456789"
        },
        {
            "type": "DRIVING_LICENSE",
            "number": "B987654321",
            "note": "Registered by Customs Office"
        }
    ],
    "addresses": [
        {
            "line": "Middle house",
            "city": "Forest Hill",
            "Country": "GBR"
        },
        {
            "line": "Old house, main street",
            "city": "Aldgate",
            "Country": "GBR"
        }
    ],
    "references": [
        {
            "name": "OFAC Specially Designated National",
            "status": "CURRENT",
            "from_date": {
                "month": "02",
                "year": "2015"
            }
        }
    ],
    "countries_of_reported_allegation": [
        "GBR",
        "DEU"
    ],
    "countries_of_citizenship": [
        "GBR"
    ],
    "dobs": [
        {
            "month": "01",
            "year": "1980"
        }
    ],
    "gender": "MALE",
    "image_uri": [
        "http://example.example/images/sample1.jpg",
        "http://example.example/images/sample2.jpg"
    ],
    "deceased": false,
    "scorecard": {
        "overall_score": 91.85,
        "breakdown": [
            {
                "field_name": "name",
                "field_value": "John Doe",
                "score": 100,
                "risk_weight": 45,
                "risk_weighted_score": 45,
                "normalised_score": 33.33
            },
            {
                "field_name": "dob",
                "field_value": "01/1980",
                "score": 90,
                "risk_weight": 20,
                "risk_weighted_score": 18,
                "normalised_score": 13.33
            },
            {
                "field_name": "gender",
                "field_value": "MALE",
                "score": 100,
                "risk_weight": 10,
                "risk_weighted_score": 10,
                "normalised_score": 7.41
            },
            {
                "field_name": "address",
                "field_value": "Old house st., Aldgate, GBR",
                "score": 85,
                "risk_weight": 60,
                "risk_weighted_score": 51,
                "normalised_score": 37.78,
                "breakdown": [
                    {
                        "field_name": "country",
                        "field_value": "GBR",
                        "score": 100,
                        "risk_weight": 15,
                        "risk_weighted_score": 15,
                        "normalised_score": 25


                    },
                    {
                        "field_name": "city",
                        "field_value": "Aldgate",
                        "score": 100,
                        "risk_weight": 15,
                        "risk_weighted_score": 15,
                        "normalised_score": 25


                    },
                    {
                        "field_name": "line",
                        "field_value": "Old house st.",
                        "score": 70,
                        "risk_weight": 30,
                        "risk_weighted_score": 21,
                        "normalised_score": 35
                    }
                ]}
            ]}
        }
  }

Retrieve a match

Retrieves the details of an existing match. You need to supply the unique customer, screening and match identifier.

Attributes
ParameterDescription
customer_id
required		The unique identifier for the customer.
screening_id
required		The unique identifier for the screening.
match_id
required		The unique identifier for the match.
 
   GET /v1/customers/{customer_id}/screenings/{screening_id}/matches/{match_id}
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches/{match_id}' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer 85b36cf1-fa53-4f55-bd1a-2b66d139e5f3'
Example Response
  {
    "id": "{MATCH_ID}",
    "created_at": "2017-01-21T15:00:16Z",
    "updated_at": "2017-01-21T15:00:16Z",
    "entity_type": "INDIVIDUAL",
    "match_type": ["SPECIAL_INTEREST_PERSON"],
    "validation_result": "AWAITING_VALIDATION",
    "names": [
        {
            "name_type": "PRIMARY_NAME",
            "first_name": "John",
            "last_name": "Doe"
        },
        {
            "name_type": "ALSO_KNOWN_AS",
            "first_name": "Jo",
            "last_name": "Doe"
        }
    ],
    "documents": [
        {
            "type": "PASSPORT",
            "number": "A123456789"
        },
        {
            "type": "DRIVING_LICENSE",
            "number": "B987654321",
            "note": "Registered by Customs Office"
        }
    ],
    "addresses": [
        {
            "line": "Middle house",
            "city": "Forest Hill",
            "Country": "GBR"
        },
        {
            "line": "Old house, main street",
            "city": "Aldgate",
            "Country": "GBR"
        }
    ],
    "references": [
        {
            "name": "OFAC Specially Designated National",
            "status": "CURRENT",
            "from_date": {
                "month": "02",
                "year": "2015"
            }
        }
    ],
    "countries_of_reported_allegation": [
        "GBR",
        "DEU"
    ],
    "countries_of_citizenship": [
        "GBR"
    ],
    "dobs": [
        {
            "month": "01",
            "year": "1980"
        }
    ],
    "gender": "MALE",
    "image_uri": [
        "http://example.example/images/sample1.jpg",
        "http://example.example/images/sample2.jpg"
    ],
    "deceased": false,
    "scorecard": {
        "overall_score": 91.85,
        "breakdown": [
            {
                "field_name": "name",
                "field_value": "John Doe",
                "score": 100,
                "risk_weight": 45,
                "risk_weighted_score": 45,
                "normalised_score": 33.33
            },
            {
                "field_name": "dob",
                "field_value": "01/1980",
                "score": 90,
                "risk_weight": 20,
                "risk_weighted_score": 18,
                "normalised_score": 13.33
            },
            {
                "field_name": "gender",
                "field_value": "MALE",
                "score": 100,
                "risk_weight": 10,
                "risk_weighted_score": 10,
                "normalised_score": 7.41
            },
            {
                "field_name": "address",
                "field_value": "Old house st., Aldgate, GBR",
                "score": 85,
                "risk_weight": 60,
                "risk_weighted_score": 51,
                "normalised_score": 37.78,
                "breakdown": [
                    {
                        "field_name": "country",
                        "field_value": "GBR",
                        "score": 100,
                        "risk_weight": 15,
                        "risk_weighted_score": 15,
                        "normalised_score": 25


                    },
                    {
                        "field_name": "city",
                        "field_value": "Aldgate",
                        "score": 100,
                        "risk_weight": 15,
                        "risk_weighted_score": 15,
                        "normalised_score": 25


                    },
                    {
                        "field_name": "line",
                        "field_value": "Old house st.",
                        "score": 70,
                        "risk_weight": 30,
                        "risk_weighted_score": 21,
                        "normalised_score": 35
                    }
                ]
            }
        ]
    }
  }

List all matches

Lists all existing matches. The matches are returned sorted by overall score, with the highest scoring matches appearing first. In addition to the attributes listed on the pagination section, the following optional parameters can be used to refine the response.

Attributes
ParameterDescription
match_type
optional		An “equal” filter on the list based on the object match_type field.
validation_result
optional		An “equal” filter on the list based on the object validation_result field.
 
   GET /v1/customers/{customer_id}/screenings/{screening_id}/matches
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer 85b36cf1-fa53-4f55-bd1a-2b66d139e5f3'

Confirm a match

Confirms a customer match. You need to supply the unique customer, screening and match identifier.

Attributes
ParameterDescription
customer_id
required		The unique identifier for the customer.
screening_id
required		The unique identifier for the screening.
match_id
required		The unique identifier for the match.
 
   POST /v1/customers/{customer_id}/screenings/{screening_id}/matches/{match_id}/confirm
 
  curl --location --globoff --request POST 'https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches/{match_id}/confirm' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer 85b36cf1-fa53-4f55-bd1a-2b66d139e5f3' \
        --data ''

Dismiss a match

Dismisses a customer match. You need to supply the unique customer, screening and match identifier.

Attributes
ParameterDescription
customer_id
required		The unique identifier for the customer.
screening_id
required		The unique identifier for the screening.
match_id
required		The unique identifier for the match.
 
   POST /v1/customers/{{customer_b_id}}/screenings/{{screening_b_id}}/matches/{{match_2_id}}/dismiss
 
  curl --location --globoff --request POST 'https://api.cleardil.com/v1/customers/{{customer_b_id}}/screenings/{{screening_b_id}}/matches/{{match_2_id}}/dismiss' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {accessTokenUser}' \
        --data ''

Confirm multiple matches

Bulk confirms multiple customer matches. You need to supply the unique customer, screening and match identifiers.

Attributes
ParameterDescription
customer_id
required		The unique identifier for the customer.
screening_id
required		The unique identifier for the screening.
match_ids
required		The list of match IDs to be confirmed in bulk.
 
   POST /v1/customers/{{customer_b_id}}/screenings/{{screening_b_id}}/matches/dismiss
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{{customer_b_id}}/screenings/{{screening_b_id}}/matches/dismiss' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {accessTokenUser}' \
        --data '[
          {{matches2confirm}}
        ]'

Dismiss multiple matches

Bulk dismisses multiple customer matches. You need to supply the unique customer, screening and match identifiers.

Attributes
ParameterDescription
customer_id
required		The unique identifier for the customer.
screening_id
required		The unique identifier for the screening.
match_ids
required		The list of match IDs to be confirmed in bulk.
 
   POST /v1/customers/{{customer_b_id}}/screenings/{{screening_b_id}}/matches/dismiss
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{{customer_b_id}}/screenings/{{screening_b_id}}/matches/dismiss' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {accessTokenUser}' \
        --data '[
          {{matches2dismiss}}
        ]'

Associations

The API allows you to retrieve entities associated with a given match. The associated entities can be other individuals or companies.

The association object

Attributes
ParameterDescription
id
Individual and Company
string		The unique identifier for the associated individual or company.
created_at
Individual and Company
datetime		The date and time when the associated entity was created.
updated_at
Individual and Company
datetime		The date and time when the associated entity was updated.
entity_type
Individual and Company
string		The type of the associated entity. Values can be “INDIVIDUAL or COMPANY.
match_type
Individual and Company
list		The type of the match. Values can be:
1. SPECIAL_INTEREST_PERSON
2. SPECIAL_INTEREST_ENTITY
3. POLITICALLY_EXPOSED_PERSON
4. RELATIVE_OR_CLOSE_ASSOCIATE
5. BANNED_OR_DISQUALIFIED_PERSON
6. BANNED_OR_DISQUALIFIED_ENTITY
7. ADVERSE_MEDIA_PERSON
8. ADVERSE_MEDIA_ENTITY
association_type
Individual and Company
string		The type of association. Value can be:
1. WIFE
2. HUSBAND
3. BROTHER
4. SISTER
5. SON
6. DAUGHTER
7. MOTHER
8. FATHER
9. COUSIN
10. STEP_SON
11. STEP_DAUGHTER
12. BROTHER_IN_LAW
13. SISTER_IN_LAW
14. UNCLE
15. AUNT
16. MOTHER_IN_LAW
17. FATHER_IN_LAW
18. GRANDFATHER
19. GRANDMOTHER
20. SON_IN_LAW
21. DAUGHTER_IN_LAW
22. NIECE
23. NEPHEW
24. GRANDSON
25. GRANDDAUGHTER
26. STEPFATHER
27. STEPMOTHER
28. BUSINESS_ASSOCIATE
29. FRIEND
30. FINANCIAL_ADVISER
31. LEGAL_ADVISER
32. COLLEAGUE
33. AGENT_OR_REPRESENTATIVE
34. EMPLOYEE
35. ASSOCIATE
36. CHILD
37. FAMILY_MEMBER
38. POLITICAL_ADVISER
39. SENIOR_OFFICIAL
40. UNMARRIED_PARTNER
41. SAME_SEX_SPOUSE
42. EMPLOYER
43. SHAREHOLDER_OR_OWNER
44. ASSOCIATED_SPECIAL_INTEREST_PERSON
45. PARENT_COMPANY
46. SUBSIDIARY
47. ASSET
status
Individual and Company
string		The association status. This will be set as CURRENT if the association is in effect, or PREVIOUS if the association has ceased to exist. When not available, this will be null.
direction
Individual and Company
string		The direction of the association. This will be set as OUTBOUND when the association type is expressed as the relationship of a match towards the associate (e.g. FATHER), or INBOUND when expressed from associate towards a match (e.g. SON). Both directions will always be returned.
names
Individual and Company
list name		The associated individual or company name.
note
Individual and Company
string		Additional notes if available on associated individual or company. When none available, this will be null.
documents
Individual and Company
list document		The documents associated with individual or company. When not available, this will be null.
addresses
Individual and Company
list address		The associated individual or company addresses. When not available, this will be null.
references
Individual and Company
list reference		The reference of listed information. When not available, this will be null.
associated_countries
Individual and Company
list		The associated individual or company country of association. This will be the three-letter standard or non-standard country ISO code. When not available, this will be null.
jurisdiction
Individual and Company
list		The associated individual or company associated jurisdiction. This will be the three-letter standard or non-standard country ISO code. When not available, this will be null.
countries_of_reported_allegation
Individual and Company
list		The associated individual or company country of allegation. This will be the three-letter standard or non-standard country ISO code. When not available, this will be null.
countries_of_citizenship
Individual
list		The associated individual country of citizenship. This will be the three-letter standard or non-standard country ISO code. When not available, this will be null.
countries_of_registration
Company
list		The associated company country of registration. This will be the three-letter standard or non-standard country ISO code. When not available, this will be null.
countries_of_ownership
Company
list		The matched company country of ownership. This will be the three-letter standard or non-standard country ISO code. When not available, this will be null.
countries_of_affiliation
Company
Company
list		The associated company country of affiliation. This will be the three-letter standard or non-standard country ISO code. When not available, this will be null.
countries_of_residence
Individual
list		The associated individual country of residence. This will be the three-letter standard or non-standard country ISO code. When not available, this will be null.
dobs
Individual
list structured date		The recorded date of births of associated individual. When not available, this will be null.
gender
string		The associated individual gender. Values can be MALE, FEMALE, UNKNOWN, or OTHER.
birth_places
Individual
list		The associated individual potential birth places. When not available, this will be null.
countries_of_citizenship
Individual
list		The associated individual country of citizenship. This will be the three-letter country ISO code. When not available, this will be null.
countries_of_residence
Individual and Company
list		The associated individual country of residence. This will be the three-letter country ISO code. When not available, this will be null.
occupations
Individual
list occupation		The associated individual occupation history. When not available, this will be null.
image_uri
Individual
string		The URI to the image of the associated individual. When not available, this will be null.
deceased
Individual
boolean		This will be set to true if the associated individual is deceased, false when alive, or null when unknown.
incorporation_number
Company
string		The associated company incorporation number. When not available, this will be null.
Example Response
   {
     "id": "{ASSOCIATION_ID}",
     "created_at": "2017-01-21T15:00:16Z",
     "updated_at": "2017-01-21T15:00:16Z",
     "entity_type": "INDIVIDUAL",
     "match_type": ["RELATIVE_OR_CLOSE_ASSOCIATE"],
     "association_type": "WIFE",
     "direction": "OUTBOUND",
     "status": "CURRENT",
     "names": [
         {
             "name_type": "PRIMARY_NAME",
             "first_name": "Sue",
             "last_name": "Doe"
         }
     ],
     "addresses": [
         {
             "line": "Middle house",
             "city": "Forest Hill",
             "Country": "GBR"
         },
         {
             "line": "Old house, main street",
             "city": "Aldgate",
             "Country": "GBR"
         }
     ],
     "image_uri": [
         "http://example.example/images/sample3.jpg",
     ]
 }

Retrieve an association

Retrieves the details of an existing association. You need to supply the unique customer, screening, match and association identifier.

Attributes
ParameterDescription
customer_id
required		The unique identifier for the customer.
screening_id
required		The unique identifier for the screening.
match_id
required		The unique identifier for the match.
association_id
required		The unique identifier for the association.
 
   GET /v1/customers/{customer_id}/screenings/{screening_id}/matches/{match_id}/associations/{asso_id}
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches/{match_id}/associations/{asso_id}' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {accessTokenUser}'
Example Response
  {
    "id": "{ASSOCIATION_ID}",
    "created_at": "2017-01-21T15:00:16Z",
    "updated_at": "2017-01-21T15:00:16Z",
    "entity_type": "INDIVIDUAL",
    "match_type": ["RELATIVE_OR_CLOSE_ASSOCIATE"],
    "association_type": "WIFE",
    "direction": "OUTBOUND",
    "status": "CURRENT",
    "names": [
        {
            "name_type": "PRIMARY_NAME",
            "first_name": "Sue",
            "last_name": "Doe"
        }
    ],
    "addresses": [
        {
            "line": "Middle house",
            "city": "Forest Hill",
            "Country": "GBR"
        },
        {
            "line": "Old house, main street",
            "city": "Aldgate",
            "Country": "GBR"
        }
    ],
    "image_uri": [
        "http://example.example/images/sample3.jpg",
    ]
  }

List all associations

Lists all existing associations. The associations are returned sorted by creation date, with the most recent associations appearing first. In addition to the attributes listed on the pagination section, the following optional parameters can be used to refine the response.

Attributes
ParameterDescription
entity_type
optional		An “equal” filter on the list based on the object entity_type field.
association_type
optional		An “equal” filter on the list based on the object association_type field.
status
optional		An “equal” filter on the list based on the object status field.
 
   GET /v1/customers/{customer_id}/screenings/{screening_id}/matches/{match_id}/associations
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches/{match_id}/associations' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {accessTokenUser}'

Ongoing Due Diligence

ClearDil allows you to meet your Ongoing Customer Due Diligence (ODD) commitments by providing you with the means to screen your customers on a regular basis against our daily-refreshed databases and lists.

To complement your risk-based KYC screening process, it is recommended that you first perform screening on your customers, and once they have been successfully onboarded to create ODD instructions to apply continuous monitoring, using ClearDil’s configurable frequencies and scopes.

The API allows you to create, update and retrieve ODD instructions for each of your customers.

All of our ODD settings are at a customer level.

Unlike regular screenings, ODD-trigged screenings will exclude any ODD-flagged matches you have previously dismissed. This is intended to reduce the number of false positives and ultimately the manual burden on compliance officers.

Please note if you disable an ODD instruction, and enable it again, the ClearDil KYC Engine will perform a full screening on the reinstated ODD run.

The ODD Object

Attributes
ParameterDescription
id
string		The unique identifier for the ODD instruction.
created_at
datetime		The date and time when the ODD instruction was created.
updated_at
datetime		The date and time when the ODD instruction was updated.
scope
list screening type		The list of screening types to be performed as part of the ODD instruction.
frequency
string		The frequency at which an ODD instruction is executed. Valid values: are:
1. DAILY
2. WEEKLY
3. MONTHLY
active
boolean		Indicates whether an ODD instruction is enabled. Set this to true to enable an ODD instruction or false to disable it.
Example Response
  {
    "id": "{ODD_ID}",
    "created_at": "2017-12-31T12:00:16Z",
    "updated_at": "2017-12-31T12:00:16Z",
    "scope": [
        "WATCHLIST",
        "ADVERSE_MEDIA"
    ],
    "frequency": "MONTHLY",
    "active": true
  }

Create an ODD

Creates a new ODD instruction object.

Attributes
ParameterDescription
scope
required		The list of screening types to be performed as part of the ODD instruction.
frequency
required		The frequency at which an ODD instruction is executed. Valid values: are:
1.DAILY
2.WEEKLY
3.MONTHLY
active
optional		Indicates whether an ODD instruction is enabled. Set this to true to enable an ODD instruction or false to disable it.
 
   POST /v1/customers/{customer_id}/odd
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/odd' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {accessTokenUser}' \
        --data '{
            "frequency" : "WEEKLY",
            "scope": ["PEP", "WATCHLIST"]
        }'
Example Response
  {
    "id": "{customer_id}",
    "created_at": "2017-12-31T12:00:16Z",
    "updated_at": "2017-12-31T12:00:16Z",
    "scope": [
      "WATCHLIST",
      "ADVERSE_MEDIA"
    ],
    "frequency": "MONTHLY",
    "active": true
  }

Retrieve an ODD

Retrieves the details of an existing ODD instruction. You need to supply the unique customer and ODD identifier.

Attributes
ParameterDescription
customer_id
required		The unique identifier for the customer.
odd_id
required		The unique identifier for the ODD .
 
   GET /v1/customers/{customer_id}/odd/{{odd_a_id}}
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/odd/{{odd_a_id}}' \
        --header 'Authorization: Bearer {accessTokenUser}'