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.

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 `INDIVIDUAL`or`COMPANY`.
`joined_at` Individual and Company datetime	The date and time when the customer was registered with you. This is relevant for users that migrate existing customers.
`email` Individual and Company string	The customer’s email address.
`telephone` Individual and Company string	The customer’s telephone number.
`mobile` Individual and Company string	The customer’s mobile number.
`addresses` Individual and Company list address	A list of addresses associated with customer.
`title` Individual string	The customer’s title. Valid values are `MR`, `MRS`, `MISS`, or `MS`.
`first_name` Individual string	The customer’s first name.
`middle_name` Individual string	The customer’s middle name.
`last_name` Individual string	The customer’s last name.
`maiden_name` Individual string	The customer’s maiden name.
`alternative_first_name` Individual string	The customer’s alternative or new first name.
`alternative_middle_name` Individual string	The customer's alternative or new middle name.
`alternative_last_name` Individual string	The customer's alternative or new last name.
`dob` Individual date	The customer’s date of birth. The format is YYYY-MM-DD.
`gender` Individual string	The customer’s gender. Valid values are `MALE`, `FEMALE`, or `OTHER`.
`nationality` Individual string	The customer’s nationality. This will be the three-letter country 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 `MR`, `MRS`, `MISS`, or `MS`.
`first_name` Individual required	The customer’s first name.
`middle_name` Individual optional	The customer’s middle name
`last_name` Individual required	The customer’s last name.
`maiden_name` Individual optional	The customer’s maiden.
`alternative_first_name` Individual optional	The customer’s alternative or new first name.
`alternative_middle_name` Individual optional	The customer's alternative or new middle name.
`alternative_last_name` Individual optional	The customer's alternative or new last name.
`dob` Individual optional	The customer’s date of birth. The format is YYYY-MM-DD.
`gender` Individual optional	The customer’s gender. Valid values are `MALE`, `FEMALE`, or `OTHER`.
`nationality` Individual optional	The customer’s nationality. This will be the three-letter country 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:

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

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`, `MRS`, `MISS`, or `MS`.
`first_name` Individual	The customer’s first name.
`middle_name` Individual	The customer’s middle name.
`last_name` Individual	The customer’s last name.
`maiden_name` Individual	The customer’s maiden.
`alternative_first_name` Individual	The customer’s alternative or new first name.
`alternative_middle_name` Individual	The customer's alternative or new middle name.
`alternative_last_name` Individual	The customer's alternative or new last name.
`dob` Individual	The customer’s date of birth. The format is YYYY-MM-DD.
`gender` Individual	The customer’s gender. Valid values are `MALE`, `FEMALE`, or `OTHER`.
`nationality` Individual	The customer’s nationality. This will be the three-letter country 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 `HIGH`, `MEDIUM` and `LOW` when set, or null when not set.
`relationship` string	This indicates relationship risk level, which is automatically calculated by ClearDil upon the completion of a screening request. Valid values are `HIGH`, `MEDIUM` and `LOW` when set, or null when not set.
`occupation` string	This represents the occupation risk level, which is automatically calculated by ClearDil upon the completion of a screening request with PEP in its scope. This is only applicable to customers with political exposure. Valid values are `HIGH`, `MEDIUM` and `LOW` when set, or null when not set.
`country` string	This represents the country risk level, which is automatically calculated by ClearDil based on customer country details, which include the `address`, `nationality`, and `incorporation_country`. Valid values are `HIGH`, `MEDIUM` and `LOW` when set, or null when not set.
`overall` string	Overall risk score based on all available risk scores. Valid values are `HIGH`, `MEDIUM` and `LOW` when set, or null when not set.

Retrieve a risk profile

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:

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

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:

MRZ verification performs analysis checks on the Machine Readable Zone (MRZ) values specified by the user.
Image verification performs image, Optical Character Recognition (OCR), and MRZ analysis on the attachments associated with the supplied document.

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.