NAV

ClearDil API 1.0

Updated 2022-02-21

API endpoint

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

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

Examples in this documentation are generated using Postman.

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.

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 sandbox.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.

Create customer

$ curl https://api.cleardil.com/v1/customers \
    -H 'Authorization: Bearer test_api_token' \
    -H 'content-type: application/json' \
    -X POST
    -d '{
            "type" : "INDIVIDUAL",
            "email" : "john.doe@example.com",
            "first_name" : "John",
            "last_name" : "Doe",
            "gender" : "MALE",
            "dob" : "1980-01-01"
        }'

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.

Screen customer

$ curl https://api.cleardil.com/v1/customers/{customer_id}/screenings \
    -H 'Authorization: Bearer test_api_token' \
    -H 'content-type: application/json' \
    -X POST
    -d '[
        "WATCHLIST",
        "PEP"
        ]'

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.

Topics

Authentication and headers

Example Request

curl https://api.cleardil.com/v1/oauth2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u "client_id:secret"

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.

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

Request Header
Request Header Description
Authorization
required
To request an access token, send your client_id and secret values as the HTTP basic authentication credentials. If you use cURL, specify -u “*client_id:secret*”. 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.

HTTP status code summary
Response code Meaning
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

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"
    }
  ]
}
Response code Meaning
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.
Error Types
Response code Meaning
invalid_request Request has malformed or missing fields.
invalid_sorting_request No property “{sort_term}” found.
invalid_patch_request Specified patch has invalid path or operation.
malformed_content Content of the request does not conform to specification.
invalid_operation Operation is not supported. {reason}.
invalid_token Provided token is invalid or expired.
access_denied Access to this resource is denied.
insufficient_permissions You don’t have sufficient permissions to perform this action.
resource_not_found Cannot find a resource {resource}.
duplicate Such resource already exists.
conflict Resource cannot be modified because of conflicting request.
resource_deleted The requested resource was deleted.
internal_error Operation execution was failed.
not_implemented Requested operation isn’t implemented yet.
service_maintenance A service is under planned maintenance.
Validation Error Codes

The following validation error codes only apply to invalid_request errors.

Response code Meaning
mandatory_field_missing This field is required.
incorrect_email_format The format of the email is incorrect.
past_date_expected The date value for this field is expected to be in the past.
date_out_of_bounds 1. 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_format Phone number does not meet international format.
invalid_country_code No country found for specified code.
invalid_pattern 1. For search terms: %, ^,* and @ are not allowed.
2. For incorporation number: Only numbers, digits, _ and - are allowed.
wrong_value_length Size must be between {x} and {y}.
invalid_value The value provided does not conform to specification.
invalid_date_format Invalid date format or value, expected YYYY-MM-DD.
invalid_mrz_format The format of MRZ line is invalid, only A-Z, 0-9 and < are expected.
invalid_constant_value The value provided does not conform to specification.

Pagination

Example Request

GET https://api.cleardil.com/v1/customers?page=0&size=2&sort=last_name,DESC

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
Parameter Description
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.

Patch object

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

Attributes
Parameter Description
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

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"
        }
    ]
}
Attributes
Parameter Description
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 MRMRSMISS, 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 MALEFEMALE, or OTHER.
nationality
Individual
string
The customer’s nationality. This will be the three-letter country ISO code.
birth_country
Individual
string
The customer’s country of birth. This will be the three-letter country ISO code.
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 ISO code.
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
Parameter Description
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
date
The date the customer moved in to this address. The format is YYYY-MM-DD.
to_date
date
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.

Create a customer

Definition

POST https://api.cleardil.com/v1/customers

Example Request

$ curl https://api.cleardil.com/v1/customers \
    -H 'Authorization: Bearer test_api_token' \
    -H 'content-type: application/json' \
    -X POST
    -d '{
            "type" : "INDIVIDUAL",
            "email" : "john.doe@example.com",
            "title" : "MR",
            "first_name" : "John",
            "middle_name": "A.",
            "last_name" : "Doe",
            "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"
                }
            ],
        }'

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

Creates a new customer object.

Attributes
Parameter Description
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 MRMRSMISS, 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 MALEFEMALE, or OTHER.
nationality
Individual
optional
The customer’s nationality. This will be the three-letter country ISO code.
birth_country
Individual
optional
The customer’s country of birth. This will be the three-letter country ISO code.
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 ISO code.
primary_contact_name
Company
optional
The company’s primary contact full name.
primary_contact_email
Company
optional
The company’s primary contact email address.

Retrieve a customer

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id} \
    -H 'Authorization: Bearer test_api_token' \
    -X GET

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

Retrieves the details of an existing customer. You need only supply the unique customer identifier that was returned upon customer creation.

Attributes
Parameter Description
customer_id
required
The unique identifier for the customer.

Update a customer

Definition

PUT https://api.cleardil.com/v1/customers/{customer_id}

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id} \
    -H 'Authorization: Bearer test_api_token' \
    -H 'content-type: application/json' \
    -X PUT
    -d '{
        "type" : "INDIVIDUAL",
        "email" : "john.doe@example.com",
        "title" : "MR",
        "first_name" : "John",
        "middle_name": "Smith",
        "last_name" : "Doe",
        "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"
            }
        ],
    }'

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

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:

Attributes
Parameter Description
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, MRSMISS, 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 MALEFEMALE, or OTHER.
nationality
Individual
The customer’s nationality. This will be the three-letter country ISO code.
birth_country
Individual
The customer’s country of birth. This will be the three-letter country ISO code.
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 ISO code.
primary_contact_name
Company
The company’s primary contact full name.
primary_contact_email
Company
The company’s primary contact email address.

Partially update a customer

Definition

PATCH https://api.cleardil.com/v1/customers/{customer_id}

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id} \
    -H 'Authorization: Bearer test_api_token' \
    -H 'content-type: application/json' \
    -X PATCH
    -d '[
            {
                "op": "replace",
                "path": "/first_name",
                "value": "Eric"
            },
            {
                "op": "replace",
                "path": "/last_name",
                "value": "Jones"
            },
            {
                "op": "replace",
                "path": "/addresses/0/to_date",
                "value": "2015-01-01"
            },
            {
                "op": "add", "path": "/addresses/-",
                "value" : {
                    "type" : "PRIMARY",
                    "line": "Street Line",
                    "city": "Acton",
                    "postal_code": "W77 X11",
                    "country": "GBR",
                    "from_date": "2015-01-02"
                }
            }
        ]'

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.

Delete a customer

Definition

DELETE https://api.cleardil.com/v1/customers/{customer_id}

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id} \
 -H 'Authorization: Bearer test_api_token' \
 -X DELETE

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. Please note, once a customer has undergone any type of checks (e.g. screening), they can no longer be deleted.

Attributes
Parameter Description
customer_id
required
The unique identifier for the customer.

List all customers

Definition

GET https://api.cleardil.com/v1/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.

Attributes
Parameter Description
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 API allows you to retrieve your customer’s risk profile.

The risk profile object

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"
}
Attributes
Parameter Description
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.

PROFILE

Attributes
Parameter Description
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
Parameter Description
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 HIGHMEDIUM 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 HIGHMEDIUM 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 HIGHMEDIUM 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 HIGHMEDIUM and LOW when set, or null when not set.
overall
string
Overall risk score based on all available risk scores. Valid values are HIGHMEDIUM and LOW when set, or null when not set.

Retrieve a risk profile

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}/risk_profile

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/risk_profile \
    -H 'Authorization: Bearer test_api_token' \
    -H 'content-type: application/json' \
    -X GET

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

Retrieves the risk profile of an existing customer.

Attributes
Parameter Description
text
required
The text of the note.

Documents

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

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.

The document object

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"
}
Attributes
Parameter Description
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.

Create and upload a document

Definition

POST https://api.cleardil.com/v1/customers/{customer_id}/documents

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/documents \
    -H 'Authorization: Bearer test_api_token' \
    -X POST
    -F 'front_side=@foo.jpg' \
    -F 'back_side=@bar.jpg' \
    -F 'type=PASSPORT' \
    -F 'document_name=Customer passport' \
    -F 'document_description=Primary ID document' \
    -F 'document_number=N1234567890' \
    -F 'issuing_country=GBR' \
    -F 'issue_date=2010-01-01' \
    -F 'expiry_date=2020-01-01' \
    -F 'mrz_line1=IDGBRDOE<<<<<<<<<<<<<<<<<<<<<<<<<<<<' \
    -F 'mrz_line2=N1234567890JOHN<<<<<<<<<<<<6512068F4' \

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

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.

Attributes
Parameter Description
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.

Retrieve a document

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}/documents/{document_id}

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/documents/{document_id} \
    -H 'Authorization: Bearer test_api_token' \
    -X GET

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

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

Attributes
Parameter Description
customer_id
required
The unique identifier for the customer.
document_id
required
The unique identifier for the document.

Download a document

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}/documents/{document_id}/download

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/documents/{document_id}/download?side=front  \
    -H 'Authorization: Bearer test_api_token' \
    -X GET

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.

Update a document

Definition

PUT https://api.cleardil.com/v1/customers/{customer_id}/documents/{document_id}

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/documents/{document_id} \
    -H 'Authorization: Bearer test_api_token' \
    -X PUT
    -F 'front_side=@foo.jpg' \
    -F 'back_side=@bar.jpg' \
    -F 'type=DRIVING_LICENSE' \
    -F 'document_name=Customer driving license' \
    -F 'document_description=Primary ID document' \
    -F 'document_number=N1234567890' \
    -F 'issuing_country=GBR' \
    -F 'issue_date=2010-01-01' \
    -F 'expiry_date=2020-01-01'

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

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
Parameter Description
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.

Partially update a document

Definition

PATCH https://api.cleardil.com/v1/customers/{customer_id}/documents/{document_id}

Example Request

$ curl https://api.cleardil.com/v1/customers/b19872d0-07ea-4d04-84eb-eb7758869b28/documents/d78913a9-7dcd-46c8-a8fc-91b4f85329f5  \
    -H 'Authorization: Bearer test_api_token' \
    -H 'content-type: application/json' \
    -X PATCH
    -d '[
            {
                "op": "replace",
                "path": "/type",
                "value": "DRIVING_LICENSE"
            },
        ]'

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.

List all documents

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}/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
Parameter Description
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.

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

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"
    }
}
Attributes
Parameter Description
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.

SCREENING TYPE

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

Scope Description Coverage
WATCHLIST We 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
PEP We 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_ENTITIES We will search your customer against our disqualified entities database which also includes disqualified , banned and barred individuals and companies. Global
ADVERSE_MEDIA We will search your customer against our adverse media database of hand-picked articles from trusted news outlets. Global

SCREENING RESULT

Screening result and description
Result Description
IN_PROGRESS Indicates the screening is still being processed by ClearDil.
AWAITING_VALIDATION Indicates ClearDil has found one or more potential matches against your customer. These matches will require manual validation using the Matches endpoint.
CONFIRMED Indicates at least one match has been confirmed using the Matches endpoint.
DISMISSED Indicates that all the screening matches have been dismissed by you as they were not deemed to be genuine matches (i.e. false positives).
CLEAR Indicates 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

Definition

POST https://api.cleardil.com/v1/customers/{customer_id}/screenings/

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/screenings \
    -H 'Authorization: Bearer test_api_token' \
    -H 'content-type: application/json' \
    -X POST
    -d '[
        "PEP",
        "WATCHLIST",
        "DISQUALIFIED_ENTITIES"
    ]'

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

Creates a new screening object.

Attributes
Parameter Description
scope
required
A list of the screenings to be performed.

Retrieve a screening

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id} \
    -H 'Authorization: Bearer test_api_token' \
    -X GET

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

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

Attributes
Parameter Description
customer_id
required
The unique identifier for the customer.
screening_id
required
The unique identifier for the screening.

List all screenings for customer

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}/screenings

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
Parameter Description
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.

Search screenings

Definition

GET https://api.cleardil.com/v1/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
Parameter Description
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.

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

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
                    }
                ]}
            ]}
        }
    }
}
Attributes
Parameter Description
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
Parameter Description
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
Parameter Description
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
Parameter Description
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
Parameter Description
title
string
The tile 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
Parameter Description
name
string
The 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
string
Current status of the reference. Possible values are CURRENT or SUSPENDED.

SCORECARD

Attributes
Parameter Description
overall_score
string
The 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 object
The breakdown of the scorecard.

BREAKDOWN

The breakdown consists of nested object following the convention below:

Attributes
Parameter Description
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.

ISO Code Description
000 Unknown.
111 International.
222 Abkhazia.
333 Kosovo.
444 Curaçao.
555 None.
666 St. Maarten.
777 South Ossetia.
888 Turkish Republic of Northern Cyprus.

Retrieve a match

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches/{match_id}

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches/{match_id} \
    -H 'Authorization: Bearer test_api_token' \
    -X GET

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

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

Attributes
Parameter Description
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.

List all matches

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches \
    -H 'Authorization: Bearer test_api_token' \
    -X GET

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
Parameter Description
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.

Confirm a match

Definition

POST https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches/{match_id}/confirm

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches/{match_id}/confirm \
    -X POST

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

Attributes
Parameter Description
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.

Dismiss a match

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches/{match_id}/dismiss

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches/{match_id}/dismiss \
    -H 'Authorization: Bearer test_api_token' \
    -X POST

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

Attributes
Parameter Description
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.

Confirm multiple matches

Definition

POST https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches/confirm

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches/confirm \
    -H 'Authorization: Bearer test_api_token' \
    -X POST
    -d '[
            "{screening_id_1}",
            "{screening_id_2}"
    ]'

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

Attributes
Parameter Description
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.

Dismiss multiple matches

Definition

POST https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches/dismiss

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches/dismiss \
    -H 'Authorization: Bearer test_api_token' \
    -X POST
    -d '[
            "{screening_id_1}",
            "{screening_id_2}"
    ]'

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

Attributes
Parameter Description
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 dismissed in bulk.

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

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

Retrieve an association

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches/{match_id}/associations/{association_id}

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches/{match_id}/associations/{association_id} \
    -H 'Authorization: Bearer test_api_token' \
    -X GET

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

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

Attributes
Parameter Description
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.

List all associations

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches/{match_id}/associations

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/screenings/{screening_id}/matches/{match_id}/associations \
    -H 'Authorization: Bearer test_api_token' \
    -X GET

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
Parameter Description
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.

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.

The ODD object

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
}
Attributes
Parameter Description
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.

Create an ODD

Definition

POST https://api.cleardil.com/v1/customers/{customer_id}/odd

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/odd \
  -H 'Authorization: Bearer test_api_token' \
  -H 'content-type: application/json' \
  -X POST
  -d '{
      "scope" : [WATCHLIST","ADVERSE_MEDIA"],
      "frequency" : "MONTHLY",
      "active" : true
    }'

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
}

Creates a new ODD instruction object.

Attributes
Parameter Description
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.

Retrieve an ODD

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}/odd/{odd_id}

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/odd/{odd_id} \
  -H 'Authorization: Bearer test_api_token' \
  -H 'content-type: application/json' \
  -X GET

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
}

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

Attributes
Parameter Description
customer_id
required
The unique identifier for the customer.
odd_id
required
The unique identifier for the ODD .

Retrieve an ODD result

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}/odd/{odd_id}/results

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/odd/{odd_id}/results \
  -H 'Authorization: Bearer test_api_token' \
  -H 'content-type: application/json' \
  -X GET

Example Response

{
  "content" : [
    {
      "customer_id" : "{CUSTOMER_ID}"
      "executed_at" : "2018-01-15T12:00:15Z",
      "dataset_version" : "55606f8e54dec6a456db52b426627cd72c904183",
      "screening_id" : "{SCREENING_ID}"
    }
  ]
}

Retrieves the results of an ODD instruction that has been executed. You need to supply the unique customer and ODD identifier.

A list of result objects will be returned.

Attributes
Parameter Description
customer_id
required
The unique identifier for the customer.
odd_id
required
The unique identifier for the ODD .

RESULT

Attributes
Parameter Description
customer_id
string
The unique identifier for the customer.
screening_id
string
The unique identifier for the screening request that has been created due to the execution of an ODD instruction.
dataset_version
string
The ClearDil dataset version used for the ODD run.
executed_at
datetime
The date and time when the ODD instruction was executed.

Update an ODD

Definition

PUT https://api.cleardil.com/v1/customers/{customer_id}/odd/{odd_id}

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/odd/{odd_id}  \
  -H 'Authorization: Bearer test_api_token' \
  -H 'content-type: application/json' \
  -X PUT
  -d '{
      "scope" : [WATCHLIST","ADVERSE_MEDIA"],
      "frequency" : "MONTHLY",
      "active" : true
    }'

Example Response

 {
     "id": "{ODD_ID}",
     "created_at": "2017-12-31T12:00:16Z",
     "updated_at": "2017-12-31T12:02:48Z",
     "scope": [
        "WATCHLIST",
        "ADVERSE_MEDIA"
     ],
     "frequency": "MONTHLY",
     "active": true
 }

Updates the details of an existing ODD instruction. This is an idempotent method and will require all fields you have on an ODD instruction to be provided as part of request.

Attributes
Parameter Description
customer_id
required
The unique identifier for the customer.
odd_id
required
The unique identifier for the ODD .
scope The list of screening types to be performed as part of the ODD instruction.
frequency The frequency at which an ODD instruction is executed. Valid values: are:
1.DAILY
2.WEEKLY
3.MONTHLY
active Indicates whether an ODD instruction is enabled. Set this to true to enable an ODD instruction or false to disable it.

Partially update an ODD

Definition

PATCH https://api.cleardil.com/v1/customers/{customer_id}/odd/{odd_id}

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/odd/{odd_id}  \
  -H 'Authorization: Bearer test_api_token' \
  -H 'content-type: application/json' \
  -X PATCH
  -d '[
      {
          "op": "replace",
          "path": "/frequency",
          "value": "MONTHLY"
      }
  ]'

Partially updates the details of an existing ODD instruction. Only fields to be updated should be provided in the request as a JSON patch object.

Delete an ODD

Definition

Deletes an existing ODD instruction. You need to supply the unique customer and ODD identifier.

DELETE https://api.cleardil.com/v1/customers/{customer_id}/odd/{odd_id}

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/odd/{odd_id}  \
 -H 'Authorization: Bearer test_api_token' \
 -X DELETE
Attributes
Parameter Description
customer_id
required
The unique identifier for the customer.
odd_id
required
The unique identifier for the ODD .

List all ODDs

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}/odd

Lists all existing ODD instructions associated with a given customer. The ODD instructions 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
Parameter Description
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.

Document Verifications

ClearDil offers an extensive array of out-of-the-box document verifications. Two verification types exist:

The table below lists the various analysis checks that are undertaken by ClearDil’s document verification engine, depending on the verification type you opt for.

Analysis Type Verification Description
authenticity_analysis IMAGE,
MRZ
Asserts whether the document is a fake, a specimen, or a copy.
integrity_analysis IMAGE,
MRZ
Asserts whether the document was of a valid and an identifiable format
content_analysis IMAGE Asserts whether data extracted by OCR from multiple places on the document is consistent with the data held in MRZ.
mrz_analysis IMAGE,
MRZ
Asserts whether MRZ data is valid and adheres to the internationally-recognised standards.
consistency_analysis IMAGE,
MRZ
Asserts whether data on the document is consistent with customers detailed held by ClearDil e.g. Asserts whether the name on a passport is the same as your customer’s name.
expiration_check IMAGE,
MRZ
Checks whether the document at hand has expired or not.

Depending on the document type and issuing country, images of both sides of the document may be required. The table below specifies the document types for which both sides are required:

Name Country Type
National Identity Card EU and European Free Trade Association NATIONAL_ID_CARD
Driving License Canada DRIVING_LICENSE
Visa Biometric Residence Permit VISA


The API allows you to create and retrieve document verification requests.

The document verification object

Example Response

{
    "created_at": "2017-11-10T22:54:17Z",
    "updated_at": "2017-11-10T22:54:17Z",
    "document_id": "{DOCUMENT_ID}",
    "customer_id": "{CUSTOMER_ID}",
    "entity_name": "John Doe",
    "type": "IMAGE",
    "outcome": {
        "authenticity_analysis": {
            "status": "ERROR",
            "breakdown": [
                {
                    "type": "MRZ_MATCHING_TYPE",
                    "status": "NOT_APPLICABLE"
                },
                {
                    "type": "MRZ_VISUAL_FORMAT",
                    "status": "NOT_APPLICABLE"
                },
                {
                    "type": "PHOTO_LOCATION",
                    "status": "NOT_APPLICABLE"
                },
                {
                    "type": "DAYLIGHT_COLOUR_ANALYSIS",
                    "status": "NOT_APPLICABLE"
                },
                {
                    "type": "DOCUMENT_SPECIMEN",
                    "status": "ERROR"
                },
                {
                    "type": "VISUAL_SECURITY_ELEMENTS",
                    "status": "NOT_APPLICABLE"
                }
            ]
        },
        "integrity_analysis": {
            "status": "CLEAR",
            "breakdown": [
                {
                    "type": "ISSUE_COUNTRY",
                    "status": "CLEAR"
                },
                {
                    "type": "DOCUMENT_TYPE_EXPIRATION",
                    "status": "CLEAR"
                },
                {
                    "type": "VALIDITY_OUT_OF_COUNTRY",
                    "status": "NOT_APPLICABLE"
                },
                {
                    "type": "NATIONALITY_MATCH",
                    "status": "CLEAR"
                },
                {
                    "type": "DOCUMENT_RECOGNISED",
                    "status": "CLEAR"
                },
                {
                    "type": "ISSUE_DATE",
                    "status": "CLEAR"
                }
            ]
        },
        "content_analysis": {
            "status": "NOT_APPLICABLE",
            "breakdown": [
                {
                    "type": "DOC_NUMBER_RECOGNISED",
                    "status": "NOT_APPLICABLE"
                },
                {
                    "type": "LAST_NAME_RECOGNISED",
                    "status": "NOT_APPLICABLE"
                },
                {
                    "type": "FIRST_NAME_RECOGNISED",
                    "status": "NOT_APPLICABLE"
                },
                {
                    "type": "BIRTH_DATE_RECOGNISED",
                    "status": "NOT_APPLICABLE"
                }
            ]
        },
        "mrz_analysis": {
            "status": "CLEAR",
            "breakdown": [
                {
                    "type": "MRZ_FIELDS_FORMAT",
                    "status": "CLEAR"
                },
                {
                    "type": "MRZ_CHECKSUM",
                    "status": "CLEAR"
                }
            ]
        },
        "consistency_analysis": {
            "status": "ATTENTION",
            "breakdown": [
                {
                    "type": "CUSTOMER_DOB",
                    "status": "ATTENTION"
                },
                {
                    "type": "CUSTOMER_BIRTH_PLACE",
                    "status": "NOT_APPLICABLE"
                },
                {
                    "type": "CUSTOMER_NATIONALITY",
                    "status": "ATTENTION"
                },
                {
                    "type": "CUSTOMER_LAST_NAME",
                    "status": "ATTENTION"
                },
                {
                    "type": "CUSTOMER_GENDER",
                    "status": "NOT_APPLICABLE"
                },
                {
                    "type": "CUSTOMER_FIRST_NAME",
                    "status": "ATTENTION"
                }
            ]
        },
        "expiration_check": {
            "status": "ATTENTION",
            "breakdown": [
                {
                    "type": "DOCUMENT_EXPIRATION",
                    "status": "ATTENTION"
                }
            ]
        }
    },
    "properties": {
        "document_type": "NATIONAL_IDENTITY_CARD",
        "document_data": {
            "document_number": "GZ000030E",
            "mrz_line1": "IDGIBGZ000030E2Q15000174<<<<<<",
            "mrz_line2": "7402061M2501280GBR<<<<<<<<<<<0",
            "mrz_line3": "FREEMAN<<PAUL<JAMES<<<<<<<<<<<",
            "issuing_country": "GIB",
            "expiry_date": {
                "day": 28,
                "month": 1,
                "year": 2025
            }
        },
        "holder_data": {
            "first_name": [
                "PAUL",
                "JAMES"
            ],
            "last_name": [
                "FREEMAN"
            ],
            "dob": {
                "day": 6,
                "month": 2,
                "year": 1974
            },
            "nationality": "GBR",
            "gender": "MALE"
        },
        "extracted_images": []
    },
    "status": "DONE",
    "id": "{VERIFICATION_ID}"
}
Attributes
Parameter Description
id
string
The unique identifier for the document verification.
customer_id
string
The unique identifier for the customer.
entity_name
string
The concatenated first_name and last_name of the customer if an individual, or company_name if a company.
document_id
string
The unique identifier for the document to be verified.
created_at
datetime
The date and time when the document verification was created.
updated_at
datetime
The date and time when the document verification was updated.
type
string
The type of document verification to be performed. Valid values are:
1.IMAGE
2.MRZ
outcome
hash
Provides the outcome and the breakdown of the analysis done on the document, which facilitates the identification and resolution of any potential warnings. The format will be a list of key-value pairs, the keys representing the document verification check carried out and value is the result. For each of the verification checks, the API may return one of the following results:
1. IN_PROGRESS - indicates the corresponding analysis is in progress.
2. CLEAR - indicates the analysis has not found any items requiring attention.
3. ATTENTION - indicates the analysis has found items requiring your attention.
4. ERROR - indicates the corresponding analysis could not complete because of an error.
5. NOT_APPLICABLE - indicates the corresponding analysis is not applicable.
properties
list
The document properties derived using OCR technology.
status
string
The overall status of the document verification. Values can be:
1. INITIATED - indicates verification request is created.
2. PENDING - indicates one or more of the verifications checks are IN_PROGRESS.
3. DONE - indicates all the verifications checks have been completed by ClearDil.

PROPERTIES

Attributes
Parameter Description
document_type
string
The type of document detected. Values can be:
1.PASSPORT
2.NATIONAL_IDENTITY_CARD
3.DRIVING_LICENSE
4.RESIDENCE_PERMIT
5.VISA
6.POLLING_CARD
7.UNKNOWN
holder_data
hash, holder data object
The holder’s personal details as derived from verified document.
document_data
hash, document data object
The holder’s document details as derived from verified document.
extracted_images
list extracted image
The extracted images as derived from the verified document.

HOLDER DATA

Attributes
Parameter Description
first_name
list
First names derived from verified document.
last_name
list
Last names derived from verified document.
dob
hash, structured date
Date of birth derived from verified document. When not available, this will be null.
gender
string
Gender derived from verified document. When not available, this will be null. Values can be MALE, FEMALE, UNKNOWN, or OTHER.
birth_place
string
Birth place derived from verified document. When not available, this will be null.
nationality
string
Nationality derived from verified document. This will be the three-letter country ISO code. When not available, this will be null.
address
hash, address
Address derived from verified document. When not available, this will be null.

DOCUMENT DATA

Attributes
Parameter Description
document_number
string
Number of the document. When not available, this will be null.
issuing_country
string
Issuing country derived from verified document. This will be the three-letter country ISO code. When not available, this will be null.
issuing_date
hash, structured date
Issuing date derived from verified document. When not available, this will be null.
expiry_date
hash, structured date
Expiry date derived from verified document. When not available, this will be null.
mrz_line1
string
First line of MRZ string derived from verified document. When not available, this will be null.
mrz_line3
string
Second line of MRZ string derived from verified document. When not available, this will be null.
mrz_line3
string
Third line of MRZ string derived from verified document. When not available, this will be null.

EXTRACTED IMAGE

Attributes
Parameter Description
type
string
The segment of the document that has been extracted. Values can be:
1.CROPPED_DOCUMENT
2.CROPPED_FACE
3.CROPPED_SIGNATURE
format
string
The format of the image. This will always be set to BASE64.
file_id
string
The unique identifier for the file attachment. The files API can be used to download the extract image. Please note, when attempting to download the file, use BASE64 as the output format.

ANALYSIS TYPE

The following table outlines the various analysis types conducted by ClearDil.

Analysis Type Subtype Description
AUTHENTICITY_ANALYSIS DAYLIGHT_COLOUR_ANALYSIS Analysis of daylight colours.
MRZ_VISUAL_FORMAT Analysis of MRZ visual format.
VISUAL_SECURITY_ELEMENTS Analysis of graphical security elements.
PHOTO_LOCATION Analysis of photo location.
MRZ_MATCHING_TYPE Analysis of MRZ / document consistency.
DOCUMENT_SPECIMEN Document specimen check.
INTEGRITY_ANALYSIS DOCUMENT_RECOGNISED Document structure identified.
VALIDITY_OUT_OF_COUNTRY Validity of the document outside its issuing country.
DOCUMENT_TYPE_EXPIRATION Document expiration date identified.
ISSUE_COUNTRY Document issuing country identified.
ISSUE_DATE Document issuing date identified.
NATIONALITY_MATCH Document nationality identified.
CONTENT_ANALYSIS FIRST_NAME_RECOGNISED First name recognised.
LAST_NAME_RECOGNISED Last name recognised.
BIRTH_DATE_RECOGNISED Birth date recognised.
DOC_NUMBER_RECOGNISED Document number recognised.
MRZ_ANALYSIS MRZ_FIELDS_FORMAT Validity of the MRZ content.
MRZ_CHECKSUM MRZ checksum check.
CONSISTENCY_ANALYSIS CUSTOMER_FIRST_NAME Consistency with customer’s first name.
CUSTOMER_LAST_NAME Consistency with customer’s last name.
CUSTOMER_DOB Consistency with customer’s birth date.
CUSTOMER_GENDER Consistency with customer’s gender.
CUSTOMER_BIRTH_PLACE Consistency with customer’s birth place.
CUSTOMER_NATIONALITY Consistency with customer’s nationality.
EXPIRATION_CHECK DOCUMENT_EXPIRATION Document expiration check.

Create a document verification

Definition

POST https://api.cleardil.com/v1/customers/{customer_id}/verifications

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/verifications \
    -H 'Authorization: Bearer test_api_token' \
    -X POST
    -d '{
        "document_id": "{document_id}",
        "type": "IMAGE"
        }'

Creates a new document verification object.

Attributes
Parameter Description
type
required
The type of document verification to be performed. Valid values are:
1.IMAGE
2.MRZ
document_id
required
The unique identifier for the document to be verified.

Retrieve a document verification

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}/verifications/{verification_id}

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/verifications/{verification_id} \
    -H 'Authorization: Bearer test_api_token' \
    -X GET

Example Response

{
    "created_at": "2017-11-10T22:54:17Z",
    "updated_at": "2017-11-10T22:54:17Z",
    "document_id": "{DOCUMENT_ID}",
    "customer_id": "{CUSTOMER_ID}",
    "entity_name": "John Doe",
    "type": "IMAGE",
    "outcome": {
        "authenticity_analysis": {
            "status": "ERROR",
            "breakdown": [
                {
                    "type": "MRZ_MATCHING_TYPE",
                    "status": "NOT_APPLICABLE"
                },
                {
                    "type": "MRZ_VISUAL_FORMAT",
                    "status": "NOT_APPLICABLE"
                },
                {
                    "type": "PHOTO_LOCATION",
                    "status": "NOT_APPLICABLE"
                },
                {
                    "type": "DAYLIGHT_COLOUR_ANALYSIS",
                    "status": "NOT_APPLICABLE"
                },
                {
                    "type": "DOCUMENT_SPECIMEN",
                    "status": "ERROR"
                },
                {
                    "type": "VISUAL_SECURITY_ELEMENTS",
                    "status": "NOT_APPLICABLE"
                }
            ]
        },
        "integrity_analysis": {
            "status": "CLEAR",
            "breakdown": [
                {
                    "type": "ISSUE_COUNTRY",
                    "status": "CLEAR"
                },
                {
                    "type": "DOCUMENT_TYPE_EXPIRATION",
                    "status": "CLEAR"
                },
                {
                    "type": "VALIDITY_OUT_OF_COUNTRY",
                    "status": "NOT_APPLICABLE"
                },
                {
                    "type": "NATIONALITY_MATCH",
                    "status": "CLEAR"
                },
                {
                    "type": "DOCUMENT_RECOGNISED",
                    "status": "CLEAR"
                },
                {
                    "type": "ISSUE_DATE",
                    "status": "CLEAR"
                }
            ]
        },
        "content_analysis": {
            "status": "NOT_APPLICABLE",
            "breakdown": [
                {
                    "type": "DOC_NUMBER_RECOGNISED",
                    "status": "NOT_APPLICABLE"
                },
                {
                    "type": "LAST_NAME_RECOGNISED",
                    "status": "NOT_APPLICABLE"
                },
                {
                    "type": "FIRST_NAME_RECOGNISED",
                    "status": "NOT_APPLICABLE"
                },
                {
                    "type": "BIRTH_DATE_RECOGNISED",
                    "status": "NOT_APPLICABLE"
                }
            ]
        },
        "mrz_analysis": {
            "status": "CLEAR",
            "breakdown": [
                {
                    "type": "MRZ_FIELDS_FORMAT",
                    "status": "CLEAR"
                },
                {
                    "type": "MRZ_CHECKSUM",
                    "status": "CLEAR"
                }
            ]
        },
        "consistency_analysis": {
            "status": "ATTENTION",
            "breakdown": [
                {
                    "type": "CUSTOMER_DOB",
                    "status": "ATTENTION"
                },
                {
                    "type": "CUSTOMER_BIRTH_PLACE",
                    "status": "NOT_APPLICABLE"
                },
                {
                    "type": "CUSTOMER_NATIONALITY",
                    "status": "ATTENTION"
                },
                {
                    "type": "CUSTOMER_LAST_NAME",
                    "status": "ATTENTION"
                },
                {
                    "type": "CUSTOMER_GENDER",
                    "status": "NOT_APPLICABLE"
                },
                {
                    "type": "CUSTOMER_FIRST_NAME",
                    "status": "ATTENTION"
                }
            ]
        },
        "expiration_check": {
            "status": "ATTENTION",
            "breakdown": [
                {
                    "type": "DOCUMENT_EXPIRATION",
                    "status": "ATTENTION"
                }
            ]
        }
    },
    "properties": {
        "document_type": "NATIONAL_IDENTITY_CARD",
        "document_data": {
            "document_number": "GZ000030E",
            "mrz_line1": "IDGIBGZ000030E2Q15000174<<<<<<",
            "mrz_line2": "7402061M2501280GBR<<<<<<<<<<<0",
            "mrz_line3": "FREEMAN<<PAUL<JAMES<<<<<<<<<<<",
            "issuing_country": "GIB",
            "expiry_date": {
                "day": 28,
                "month": 1,
                "year": 2025
            }
        },
        "holder_data": {
            "first_name": [
                "PAUL",
                "JAMES"
            ],
            "last_name": [
                "FREEMAN"
            ],
            "dob": {
                "day": 6,
                "month": 2,
                "year": 1974
            },
            "nationality": "GBR",
            "gender": "MALE"
        },
        "extracted_images": []
    },
    "status": "DONE",
    "id": "{VERIFICATION_ID}"
}

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

Attributes
Parameter Description
customer_id
required
The unique identifier for the customer.
verification_id
required
The unique identifier for the screening.

List all document verifications for customer

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}/verifications

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

Attributes
Parameter Description
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.
status
optional
An “equal” filter on the list based on the object status field.

Search document verifications

Definition

GET https://api.cleardil.com/v1/search/verifications

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

Attributes
Parameter Description
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.
status
optional
An “equal” filter on the list based on the object status field.
document_ids
optional
A “equal' filter on the list based on the document object id field. This can be a list.
customer_ids
optional
A "equal' filter on the list based on the customer object id field. This can be a list.

Identity Verifications

ClearDil uses the latest in facial recognition and biometric algorithms to calculate a similarity score of how likely two faces belong to the same person.

The API allows you to create and retrieve identity verification requests.

The identity verification object

Example Response

{
    "created_at": "2017-11-10T22:54:17Z",
    "updated_at": "2017-11-10T22:54:17Z",
    "document_id": "{DOCUMENT_ID}",
    "customer_id": "{CUSTOMER_ID}",
    "entity_name": "John Doe",
    "selfie_id": "{SELFIE_ID}",
    "status": "DONE",
    "face_match": true,
    "similarity": 0.9531
    "face_analysis":{
        "selfie_image":{
            "age": 25,
            "gender": "MALE",
            "exposure_level" : "GOOD_EXPOSURE",
            "noise_level" : "LOW",
            "blur_level" : "LOW"
        },
        "identity_document":{
            "age": 22,
            "gender": "MALE",
            "exposure_level" : "GOOD_EXPOSURE",
            "noise_level" : "LOW",
            "blur_level" : "LOW"
        }
    },
    "id": "{IDENTIFICATION_ID}"
}
Attributes
Parameter Description
id
string
The unique identifier for the identity verification.
customer_id
string
The unique identifier for the customer.
entity_name
string
The concatenated first_name and last_name of the customer.
document_id
string
The unique identifier for the document (e.g. passport) to be used for comparison against a selfie image.
selfie_id
string
The unique identifier for the selfie image to be verified.
created_at
datetime
The date and time when the identity verification was created.
updated_at
datetime
The date and time when the identity verification was updated.
face_match
boolean
This will be set to true if the selfie image taken by the customer is deemed to match the photo embedded in a document.
similarity
integer
This indicates the similarity level of whether two faces belong to the same person. By default, ClearDil sets the face_match to true when the similarity is greater than or equal to 0.5.
face_analysis
hash
Provides breakdown of identity verification result. The format will be a list of key-value pairs for the selfie image and identity document provided.
status
hash
The overall status of the identity verification. Values can be:. Values can be:
1. INITIATED - indicates verification request is created.
2. PENDING - indicates one or more of the verifications checks are IN_PROGRESS.
3. DONE - indicates all the verifications checks have been completed by ClearDil.

IDENTITY VERIFICATION RESULT

Attributes
Parameter Description
age
integer
This is indicates an estimated “visual age” number in years. It is how old a person looks like rather than the actual biological age.
exposure_level
string
This indicates face exposure level. Values can be GOOD_EXPOSURE, OVER_EXPOSURE or UNDER_EXPOSURE.
blur_level
string
This is indicates the face blur level. Values can be LOW, MEDIUM or HIGH. Larger value means more blurry the face is.
noise_level
string
This is indicates the noise level of face pixels. Values can be LOW, MEDIUM or HIGH. Larger value means more noisy the face is.
gender
string
This is indicates the gender. Values are MALE or FEMALE.

Create an identity verification

Definition

POST https://api.cleardil.com/v1/customers/{customer_id}/identifications

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/identifications \
    -H 'Authorization: Bearer test_api_token' \
    -X POST
    -d '{
        "document_id": "{DOCUMENT_ID}",
        "selfie_image": <BASE64_ENCODED_IMAGE>
        }'

Creates a new identity verification object.

Attributes
Parameter Description
document_id
required
The unique identifier for the document (e.g. passport) to be used for comparison against a selfie image.
selfie_image
required
The Base64 encoded selfie image. Upon creation of the identity verification request, a selfie ID will be generated for subsequent retrieval.

Retrieve an identity verification

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}/identifications/{identification_id}

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/identifications/{identification_id} \
    -H 'Authorization: Bearer test_api_token' \
    -X GET

Example Response

{
    "created_at": "2017-11-10T22:54:17Z",
    "updated_at": "2017-11-10T22:54:17Z",
    "document_id": "{DOCUMENT_ID}",
    "customer_id": "{CUSTOMER_ID}",
    "entity_name": "John Doe",
    "selfie_id": "{SELFIE_ID}",
    "status": "DONE",
    "face_match": true,
    "similarity": 0.9531
    "face_analysis":{
        "selfie_image":{
            "age": 25,
            "gender": "MALE",
            "exposure_level" : "GOOD_EXPOSURE",
            "noise_level" : "LOW",
            "blur_level" : "LOW"
        },
        "identity_document":{
            "age": 22,
            "gender": "MALE",
            "exposure_level" : "GOOD_EXPOSURE",
            "noise_level" : "LOW",
            "blur_level" : "LOW"
        }
    },
    "id": "{IDENTIFICATION_ID}"
}

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

Attributes
Parameter Description
customer_id
required
The unique identifier for the customer.
identification_id
required
The unique identifier for the screening.

List all identity verifications for customer

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}/identifications

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

Attributes
Parameter Description
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.
status
optional
An “equal” filter on the list based on the object status field.

Search identity verifications

Definition

GET https://api.cleardil.com/v1/search/identifications

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

Attributes
Parameter Description
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.
status
optional
An “equal” filter on the list based on the object status field.
document_ids
optional
A “equal' filter on the list based on the document object id field. This can be a list.
customer_ids
optional
A "equal' filter on the list based on the customer object id field. This can be a list.

Reports

Reports are auto-generated when a screening check is complete.

The API allows you to retrieve and download reports in any of the supported formats, such as PDF.

The report object

Example Response

{
    "id" : "{REPORT_ID}",
    "name" : "My first report",
    "type" : "SCREENING_REPORT",
    "parameters" : {
        "screening_id" : "{SCREENING_ID}"
    },
    "created_at" : "2018-02-11T12:00:16Z"
}
Attributes
Parameter Description
id
string
The unique identifier for the report.
created_at
datetime
The date and time when the report was created.
name
string
The name of the report.
type
string
The report type. Valid values are:
1.SCREENING_REPORT
parameters
map
A key-value map of parameters defined for the specified report type.

REPORT TYPE

Each report type is associated with its own set of parameters, passed in a key-value format:

Report Type Parameters Description
SCREENING_REPORT screening_id
string
Generates a report for a completed screening request.

Retrieve a report

Definition

GET https://api.cleardil.com/v1/reports/{report_id}

Example Request

$ curl https://api.cleardil.com/v1/reports/{report_id} \
    -H 'Authorization: Bearer test_api_token' \
    -X GET

Example Response

{
    "id" : "{REPORT_ID}",
    "name" : "My first report",
    "type" : "SCREENING_REPORT",
    "parameters" : {
        "screening_id" : "{SCREENING_ID}"
    },
    "created_at" : "2018-02-11T12:00:16Z"
}

Retrieves the details of an existing report. You need to supply the unique report identifier.

Attributes
Parameter Description
report_id
required
The unique identifier for the report.

Download a report

Definition

GET https://api.cleardil.com/v1/reports/{report_id}/{extension}/download

Example Request

$ curl $ curl https://api.cleardil.com/v1/reports/{report_id}/pdf/download \
    -H 'Authorization: Bearer test_api_token' \
    -X GET

Downloads a report document. You need to supply the unique report identifier and extension.

Attributes
Parameter Description
report_id
required
The unique identifier for the report.
extension
required
The required format for the report. Valid values are:
1.PDF

List all reports

Definition

GET https://api.cleardil.com/v1/reports

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

Attributes
Parameter Description
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.
type
optional
An “equal” filter on the list based on the object type field.

Files

Several of our services, such as document verification and identity verification , make use of file attachments in order to execute a check.

The files API allows you to retrieve, update, upload, download and delete any of these files. It provides means to upload and download files as multipart/form-data or application/json (i.e. Base64 encoded content). The file size must not exceed 4MB when encoded in Base64. We recommend using files less than 2MB.

The file object

Example Response

{
    "id" : "{FILE_ID}",
    "created_at" : "2018-02-14T12:00:16Z",
    "updated_at" : "2018-02-14T12:00:16Z",
    "content_type" : "image/jpeg",
    "filename" : "passport",
    "size" : 1234,
    "content" : "<BASE664_ENCODED_IMAGE>",
    "locked" : false
}
Attributes
Parameter Description
id
string
The unique identifier for the file.
created_at
datetime
The date and time when the file was created.
updated_at
datetime
The date and time when the file was updated.
filename
string
The file name.
size
string
The size of the file in bytes. Required for an application/json request.
content_type
string
The MIME-standard content type of the file (e.g. image/jpeg).
content
string
Base64 encoded file content. Required for an application/json request.
file
form-data parameter
An attribute indicating a path to the local file to be uploaded. Required for a multipart/form-data request.
locked
boolean
This will be set to true if the file is locked and can no longer be deleted, or false if it can be deleted.

Retrieve a file

Definition

GET https://api.cleardil.com/v1/files/{file_id}

Example Request

$ curl https://api.cleardil.com/v1/files/{file_id} \
    -H 'Authorization: Bearer test_api_token' \
    -X GET

Example Response

{
    "id" : "{FILE_ID}",
    "created_at" : "2018-02-14T12:00:16Z",
    "updated_at" : "2018-02-14T12:00:16Z",
    "content_type" : "image/jpeg",
    "filename" : "passport",
    "size" : 1234,
    "content" : "<BASE664_ENCODED_IMAGE>",
    "locked" : false
}

Retrieves the details of an existing file. You need to supply the unique file identifier.

Attributes
Parameter Description
file_id
required
The unique identifier for the file.

Download a file

Definition

GET https://api.cleardil.com/v1/files/{file_id}?output=BASE64

Example Request

$ curl https://api.cleardil.com/v1/files/{file_id}?output=BASE64\
    -H 'Authorization: Bearer test_api_token' \
    -X GET

Downloads a previously uploaded file. You need to supply the unique file identifier and output format.

Attributes
Parameter Description
file_id
required
The unique identifier for the customer.
output
required
The type of output file content. Valid values are:
1.STREAM - returns file contents as part of the HTTP response.
2.BASE64 - returns Base64 encoded string as part of file object JSON.

Update a file

Definition

PUT https://api.cleardil.com/v1/files/{file_id}

Example Request

$ curl https://api.cleardil.com/v1/files/{file_id} \
    -H 'Authorization: Bearer test_api_token' \
    -X PUT
    -d '{
          "content_type": "image/jpeg",
          "filename" : "passport copy",
          "size" : 1234,
          "content" : "<base64-encoded data>",
        }'

Example Response

{
    "id" : "{FILE_ID}",
    "created_at" : "2018-02-14T12:00:16Z",
    "updated_at" : "2018-02-14T12:00:16Z",
    "content_type" : "image/jpeg",
    "filename" : "passport",
    "size" : 1234,
    "content" : "<BASE664_ENCODED_IMAGE>",
    "locked" : false
}

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

Please note, this currently works with application/json requests only (i.e. BASE64 encoded content).

Attributes
Parameter Description
file_id
required
The unique identifier for the file.
filename The file name.
size
required
The size of the file in bytes. Required for an application/json request.
content_type
required
The MIME-standard content type of the file (e.g. image/jpeg).
content
required
Base64 encoded file content. Required for an application/json request.
file
required
An attribute indicating a path to the local file to be uploaded. Required for a multipart/form-data request.

Partially update a file

Definition

PATCH https://api.cleardil.com/v1/files/{file_id}

Example Request

$ curl https://api.cleardil.com/v1/files/{file_id} \
    -H 'Authorization: Bearer test_api_token' \
    -H 'content-type: application/json' \
    -X PATCH
    -d '[
            {
                "op": "replace",
                "path": "/filename",
                "value": "passport copy"
            },
        ]'

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

Delete a file

Definition

DELETE https://api.cleardil.com/v1/files/{file_id}

Example Request

$ curl https://api.cleardil.com/v1/files/{file_id} \
 -H 'Authorization: Bearer test_api_token' \
 -X DELETE

Deletes an existing file. You need only supply the unique file identifier. Please note, once a file attachment has undergone any type of checks (e.g. document verification, identity verification), it can no longer be deleted.

Attributes
Parameter Description
file_id
required
The unique identifier for the file.

List all files

Definition

GET https://api.cleardil.com/v1/files

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

Attributes
Parameter Description
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.

Notes

A note is a comment that can be associated with a customer to support operational activities. The API allows you to create, retrieve, update, and delete notes.

The note object

Example Response

{
    "id": "{NOTE_ID}",
    "created_at": "2017-01-17T23:46:26Z",
    "updated_at": "2017-01-17T23:46:26Z",
    "text": "A useful note about John Doe."
}
Attributes
Parameter Description
id
string
The unique identifier for the note.
created_at
datetime
The date and time when the note was created.
updated_at
datetime
The date and time when the note was updated.
text
string
The text of the note. A note can not exceed 4000 characters.

Create a note

Definition

POST https://api.cleardil.com/v1/customers/{customer_id}/notes/

Example Request

$ curl https://api.cleardil.com/v1/customers/{note_id}/notes \
    -H 'Authorization: Bearer test_api_token' \
    -H 'content-type: application/json' \
    -X POST
    -d '{
            "text" : "A useful note about John Doe."
        }'

Example Response

{
    "id": "{NOTE_ID}",
    "created_at": "2017-01-17T23:46:26Z",
    "updated_at": "2017-01-17T23:46:26Z",
    "text": "A useful note about John Doe."
}

Creates a new note object.

Attributes
Parameter Description
text
required
The text of the note. A note can not exceed 4000 characters.

Retrieve a note

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}/notes/{note_id}

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/notes/{note_id}\
 -H 'Authorization: Bearer test_api_token' \
 -X GET

Example Response

{
    "id": "{NOTE_ID}",
    "created_at": "2017-01-17T23:46:26Z",
    "updated_at": "2017-01-17T23:46:26Z",
    "text": "A useful note about John Doe."
}

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

Attributes
Parameter Description
customer_id
required
The unique identifier for the customer.
note_id
required
The unique identifier for the note.

Update a note

Definition

PUT https://api.cleardil.com/v1/customers/{customer_id}/notes/{note_id}

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/notes/{note_id}\
    -H 'Authorization: Bearer test_api_token' \
    -H 'content-type: application/json' \
    -X PUT
    -d '{
            "text" : "Update note on John Doe."
        }'

Example Response

{
    "id": "{NOTE_ID}",
    "created_at": "2017-01-17T23:46:26Z",
    "updated_at": "2017-01-18T10:10:10Z",
    "text": "Update note on John Doe."
}

Updates the details of an existing note. You need to supply the unique customer and note identifier.

Attributes
Parameter Description
customer_id
required
The unique identifier for the customer.
note_id
required
The unique identifier for the note.
text The text of the note.

Delete a note

Definition

DELETE https://api.cleardil.com/v1/customers/{customer_id}/notes/{note_id}

Example Request

$ curl https://api.cleardil.com/v1/customers/{customer_id}/notes/{note_id}\
 -H 'Authorization: Bearer test_api_token' \
 -X DELETE

Deletes an existing note. You need to supply the unique customer and note identifier.

Attributes
Parameter Description
customer_id
required
The unique identifier for the customer.
note_id
required
The unique identifier for the note.

List all notes

Definition

GET https://api.cleardil.com/v1/customers/{customer_id}/notes

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

Attributes
Parameter Description
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.
text
optional
A “contains” filter on the list based on the object text field.