Skip to content
ClearDil Docs

ClearDil API 1.0

Updated 2022-02-21

This document is a detailed reference for our REST API.

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

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

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

API endpoint

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


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

Examples in this documentation are generated using Postman.

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

Try Now

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

Access your test token

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

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

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

Create customer

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

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

Screen customer

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

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

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

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

Topics

Authentication and headers

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

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

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

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

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

Request Headers

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

Errors

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

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

The following validation error codes only apply to invalid_request errors.

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

Pagination

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

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

Request Arguments

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

Patch object

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

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

Resources

Customers

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

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

The customer object

Attributes

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

Attributes

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

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

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

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

Create Customer

Attributes

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

Retrieve a Customer

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

Update a Customer

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

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

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

Attributes

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

Partially Update a Customer

Partially updates the details of an existing customer.

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

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

Delete a Customer

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

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

Attributes

ParameterDescription
customer_id
required		The unique identifier for the customer.

List all Customers

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

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

Risk profile

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

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

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

The Risk Profile Object

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

Attributes

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

Attributes

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

Retrieve a Risk Profile

Retrieves the risk profile of an existing customer.

Attributes

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

Documents

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

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

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

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

The Document Object

Attributes

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

Create and Upload a document

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

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

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

Retrieve a Document

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

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

Download a Document

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

Attributes

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

Update a Document

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

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

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

Partially update a document

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

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

List all Documents

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

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

Screenings

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

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

The Screening object

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

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

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

Create a screening

Creates a new screening object.

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

Retrieve a screening

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

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

List all screenings for customer

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

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

Search screenings

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

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

Matches

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

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

The Match object

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

The breakdown consists of nested object following the convention below:

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

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

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

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


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


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

Retrieve a match

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

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


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


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

List all matches

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

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

Confirm a match

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

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

Dismiss a match

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

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

Confirm multiple matches

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

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

Dismiss multiple matches

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

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

Associations

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

The association object

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

Retrieve an association

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

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

List all associations

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

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

Ongoing Due Diligence

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

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

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

All of our ODD settings are at a customer level.

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

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

The ODD Object

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

Create an ODD

Creates a new ODD instruction object.

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

Retrieve an ODD

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

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

Retrieve an ODD result

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
ParameterDescription
customer_id
required		The unique identifier for the customer.
odd_id
required		The unique identifier for the ODD .
RESULT
ParameterDescription
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.
 
   GET /v1/customers/{customer_id}/odd/{{odd_a_id}}/results
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/odd/{{odd_a_id}}/results' \
        --header 'Authorization: Bearer {accessTokenUser}'
Example Response
  {
    "content" : [
      {
        "customer_id" : "{CUSTOMER_ID}"
        "executed_at" : "2018-01-15T12:00:15Z",
        "dataset_version" : "55606f8e54dec6a456db52b426627cd72c904183",
        "screening_id" : "{SCREENING_ID}"
      }
    ]
  }

Update an ODD

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
ParameterDescription
customer_id
required		The unique identifier for the customer.
odd_id
required		The unique identifier for the ODD .
scopeThe list of screening types to be performed as part of the ODD instruction.
frequencyThe frequency at which an ODD instruction is executed. Valid values: are:
1. DAILY
2. WEEKLY
3. MONTHLY
activeIndicates whether an ODD instruction is enabled. Set this to true to enable an ODD instruction or false to disable it.
 
   PUT /v1/customers/{customer_id}/odd/{{odd_a_id}}
 
  curl --location --globoff --request PUT 'https://api.cleardil.com/v1/customers/{customer_id}/odd/{{odd_a_id}}' \
        --header 'Authorization: Bearer {accessTokenUser}' \
        --header 'Content-Type: application/json' \
        --data '{
            "frequency" : "MONTHLY",
            "scope": ["PEP", "WATCHLIST", "ADVERSE_MEDIA"],
            "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
  }

Partially update an ODD

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.

 
   PATCH /v1/customers/{customer_id}/odd/{{odd_a_id}}
 
  curl --location --globoff --request PATCH 'https://api.cleardil.com/v1/customers/{customer_id}/odd/{{odd_a_id}}' \
        --header 'Authorization: Bearer {accessTokenUser}' \
        --header 'Content-Type: application/json' \
        --data '[
          {"op": "replace", "path": "/frequency", "value": "DAILY"},
          {"op": "add", "path": "/scope/-", "value" : "DISQUALIFIED_ENTITIES"},
          {"op": "remove", "path": "/active"}
        ]
        '

Delete an ODD

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

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

List all ODDs

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
ParameterDescription
created_after
optional		A “greater than” filter on the list based on the object created_at field.
created_before
optional		A “less than” filter on the list based on the object created_at field.
updated_after
optional		A “greater than” filter on the list based on the object updated_at field.
updated_before
optional		A “less than” filter on the list based on the object updated_at field.
scope
optional		An “equal” filter on the list based on the object scope field.
 
   GET /v1/customers/{customer_id}/odd
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/odd' \
        --header 'Authorization: Bearer {accessTokenUser}'

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 TypeVerificationDescription
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_analysisIMAGEAsserts 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:

NameCountryType
National Identity CardEU and European Free Trade AssociationNATIONAL_ID_CARD
Driving LicenseCanadaDRIVING_LICENSE
VisaBiometric Residence PermitVISA

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

The document verification object

Attributes
ParameterDescription
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.
PROPERTY
ParameterDescription
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
ParameterDescription
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
ParameterDescription
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
ParameterDescription
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 TypeSubtypeDescription
AUTHENTICITY_ANALYSISDAYLIGHT_COLOUR_ANALYSISAnalysis of daylight colours.
MRZ_VISUAL_FORMATAnalysis of MRZ visual format.
VISUAL_SECURITY_ELEMENTSAnalysis of graphical security elements.
PHOTO_LOCATIONAnalysis of photo location.
MRZ_MATCHING_TYPEAnalysis of MRZ / document consistency.
DOCUMENT_SPECIMENDocument specimen check.
INTEGRITY_ANALYSISDOCUMENT_RECOGNISEDDocument structure identified.
VALIDITY_OUT_OF_COUNTRYValidity of the document outside its issuing country.
DOCUMENT_TYPE_EXPIRATIONDocument expiration date identified.
ISSUE_COUNTRYDocument issuing country identified.
ISSUE_DATEDocument issuing date identified.
NATIONALITY_MATCHDocument nationality identified.
CONTENT_ANALYSISFIRST_NAME_RECOGNISEDFirst name recognised.
LAST_NAME_RECOGNISEDLast name recognised.
BIRTH_DATE_RECOGNISEDBirth date recognised.
DOC_NUMBER_RECOGNISEDDocument number recognised.
MRZ_ANALYSISMRZ_FIELDS_FORMATValidity of the MRZ content.
MRZ_CHECKSUMMRZ checksum check.
CONSISTENCY_ANALYSISCUSTOMER_FIRST_NAMEConsistency with customer’s first name.
CUSTOMER_LAST_NAMEConsistency with customer’s last name.
CUSTOMER_DOBConsistency with customer’s birth date.
CUSTOMER_GENDERConsistency with customer’s gender.
CUSTOMER_BIRTH_PLACEConsistency with customer’s birth place.
CUSTOMER_NATIONALITYConsistency with customer’s nationality.
EXPIRATION_CHECKDOCUMENT_EXPIRATIONDocument expiration check.
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}"
  }

Create a document verification

Creates a new document verification object.

Attributes
ParameterDescription
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.
 
   POST /v1/customers/{customer_id}/verifications
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/verifications' \
        --header 'Authorization: Bearer {accessTokenUser}' \
        --header 'Content-Type: application/json' \
        --data '{
            "document_id" : "{{document_b_id}}",
            "type" : "image"
        }'

Retrieve a document verification

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

Attributes
ParameterDescription
customer_id
required		The unique identifier for the customer.
verification_id
required		The unique identifier for the screening.
 
   GET /v1/customers/{customer_id}/verifications/{{verification_a_id}}
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/verifications/{{verification_a_id}}' \
        --header 'Authorization: Bearer {accessTokenUser}' \
        --header 'Content-Type: application/json'
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}"
  }

List all document verifications for customer

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
ParameterDescription
created_after
optional		A “greater than” filter on the list based on the object created_at field.
created_before
optional		A “less than” filter on the list based on the object created_at field.
updated_after
optional		A “greater than” filter on the list based on the object updated_at field.
updated_before
optional		A “less than” filter on the list based on the object updated_at field.
type
optional		An “equal” filter on the list based on the object type field.
status
optional		An “equal” filter on the list based on the object status field.
 
   GET /v1/customers/{customer_id}/verifications
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/verifications' \
        --header 'Authorization: Bearer {accessTokenUser}' \
        --header 'Content-Type: application/json' \
        --data '{
            "document_id" : "{{document_b_id}}",
            "type" : "image"
        }'

Search Documentation 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
ParameterDescription
created_after
optional		A “greater than” filter on the list based on the object created_at field.
created_before
optional		A “less than” filter on the list based on the object created_at field.
updated_after
optional		A “greater than” filter on the list based on the object updated_at field.
updated_before
optional		A “less than” filter on the list based on the object updated_at field.
type
optional		An “equal” filter on the list based on the object type field.
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.
 
   GET /v1/search/verifications?created_after=2022-06-01
 
  curl --location 'https://api.cleardil.com/v1/search/verifications?created_after=2022-06-01' \
        --header 'Authorization: Bearer api_token' \
        --header 'Content-Type: application/json'
Example Response

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.

Only JPEG, PNG, and BMP formats are currently supported. The allowed image file size is from 1KB to 4MB.

The identity verification object

ParameterDescription
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.
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}"
}
IDENTITY VERIFICATION RESULT
ParameterDescription
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

Creates a new identity verification object.

Attributes
ParameterDescription
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.
 
   POST /v1/customers/{customer_id}/identifications
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/identifications' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {accessTokenUser}' \
        --data '{
                "document_id" : "{{doc_id}}",
                "selfie_image" : "{{base64}}"
        }'

Retrieve an identity verification

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

Attributes
ParameterDescription
customer_id
required		The unique identifier for the customer.
identification_id
required		The unique identifier for the screening.
 
   GET /v1/customers/{customer_id}/identifications/{identity_id}
 
  curl --location --globoff --request GET 'https://api.cleardil.com/v1/customers/{customer_id}/identifications/{identity_id}' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {accessTokenUser}' \
        --data '{
                "document_id" : "{{doc_id}}",
                "selfie_image" : "{{base64}}"
        }'
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}"
  }

List all identity verifications

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
ParameterDescription
created_after
optional		A “greater than” filter on the list based on the object created_at field.
created_before
optional		A “less than” filter on the list based on the object created_at field.
updated_after
optional		A “greater than” filter on the list based on the object updated_at field.
updated_before
optional		A “less than” filter on the list based on the object updated_at field.
status
optional		An “equal” filter on the list based on the object status field.
 
   GET /v1/customers/{customer_id}/identifications
 
  curl --location --globoff --request GET 'https://api.cleardil.com/v1/customers/{customer_id}/identifications' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer api_token' \
        --data '{
                "document_id" : "{{doc_id}}",
                "selfie_image" : "{{base64}}"
        }'

Search identity verifications

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
ParameterDescription
created_after
optional		A “greater than” filter on the list based on the object created_at field.
created_before
optional		A “less than” filter on the list based on the object created_at field.
updated_after
optional		A “greater than” filter on the list based on the object updated_at field.
updated_before
optional		A “less than” filter on the list based on the object updated_at field.
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.
 
   GET /v1/customers/{customer_id}/identifications
 
  curl --location --globoff --request GET 'https://api.cleardil.com/v1/customers/{customer_id}/identifications' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer api_token' \
        --data '{
                "document_id" : "{{doc_id}}",
                "selfie_image" : "{{base64}}"
        }'

Proof Of Address Verification

ClearDil support an extensive number document globally to perform the POA verifications.

The table below lists the various analysis checks that are undertaken by ClearDil’s POA verification engine, this analysis works better hand in hand with the Verification Flow that captures the GPS coordinates of the user when performing the verification from his mobile device.

Analysis TypeDescription
country proximityAsserts whether the verification is performed from the same country as the address specified in the POA document.
IP proximityAsserts whether IP detected from where the verification is performed within an acceptable distance from the address specified in the POA document.
GPS proximityAsserts whether the GPS coordinates from where the verification is performed is within an acceptable distance from the address specified in the POA document.

ClearDil supports the two most common files used globally the utility bills and bank statements.

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

The POA verification object

Attributes
ParameterDescription
id
string		The unique identifier for the POA verification.
document_id
string		The unique identifier for the POA document used for the verification.
created_at
datetime		The date and time when the POA verification was created.
updated_at
datetime		The date and time when the POA verification was updated.
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 POA 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.
document_properties
list		The document properties derived using OCR technology.
status
string		The overall status of the POA 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.
PROPERTY
ParameterDescription
holder_attributes
hash, holder data object		The holder’s personal details as derived from verified document.
document_attributes
hash, document data object		The holder’s document details as derived from verified document.
address_attributes
hash, address data object		The holder’s address details as derived from verified document.
HOLDER DATA
ParameterDescription
entity_name
string		Entity names derived from verified document.
DOCUMENT DATA
ParameterDescription
document_type
string		The type of document detected. Values can be:
1. UTILITY_BILL
2. BANK_STATEMENT
3. UNKNOWN
issuer
string		Institution name issuing the document derived from verified document. 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.
ADDRESS DATA
ParameterDescription
address
hash, address extracted		Structured address derived from verified document. When not available, this will be null.
address_line
string		Full unstructured address derived from verified document. When not available, this will be null.
address_country
string		Country of the address derived from verified document. When not available, this will be null.
ADDRESS EXTRATED
Attributes
ParameterDescription
property_number
integer		The property number for this address.
line
string		The first line of the customer’s address.
city
string		The city or town of the customer’s address.
state
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.
coordinates
string		The coordinates calculated for this particular address.
ANALYSIS TYPE

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

Analysis TypeSubtypeDescription
CUSTOMER_CONSISTENCYFIRST_NAMEConsistency with customer’s first name.
LAST_NAMEConsistency with customer’s last name.
ADDRESSConsistency with customer’s birth date.
DATE ANALYSISDOCUMENT_AGEDocument validity check.
GEO_LOCATIONIP_COUNTRY_MATCHIndicate whether the country identified through the IP matches the country listed in the Proof of Address (POA) document.
IP_PROXIMITY_MATCHIndicate whether the IP detected from where the verification is performed within an acceptable distance from the address specified in the POA document.
GPS_PROXIMITY_MATCHIndicate whether the GPS location detected during the verification process is within an acceptable proximity to the address stated in the Proof of Address (POA) document.
Example Response
  {
    "id": "{ADDRESS_VERIFICATION_ID}",
    "document_id": "{DOCUMENT_ID}",
    "status": "DONE",
    "outcome": {
      "result": "CLEAR",
      "customer_consistency": {
        "first_name": "CLEAR",
        "last_name": "CLEAR",
        "address": "CLEAR"
      },
      "analysis": {
        "document_age": "CLEAR"
      },
      "geo_location": {
        "ip_country_match": "CLEAR",
        "ip_proximity_match": "CLEAR",
        "gps_proximity_match": "CLEAR"
      }
    },
    "document_properties": {
      "holder_attributes": {
        "entity_name": "John Doe"
      },
      "document_attributes": {
        "document_type": "bank_statement",
        "issuer": "Lloyds Bank",
        "issuing_date": {
          "day": 21,
          "month": 8,
          "year": 2017
        }
      },
      "address_attributes": {
        "address": {
          "property_number": "28",
          "line": "Rivington St",
          "city": "London",
          "state": "London",
          "postalCode": "EC2A 3DU",
          "country": "GB",
          "coordinates": "42.987,-24.235"
        },
        "address_line": "28 Rivington St London EC2A 3DU",
        "address_country": "GB"
      }
    },
    "created_at": "2017-11-10T22:54:17Z",
    "updated_at": "2017-11-10T22:54:17Z"
  }

Create a POA verification

Creates a new POA verification object.

Attributes
ParameterDescription
document_id
required		The unique identifier for the document to be verified.
gps_coordinates
required		The unique identifier for the document to be verified.
 
   POST /v1/customers/{{customer_id}}/address-verifications
 
  curl -X POST https://api.cleardil.com/v1/customer/{customer_id}/address-verification/ \
      -H 'Authorization: <YOUR_API_KEY>' \
      -H 'Content-Type: application/json' \
      -d '{
            "document_id":"{document_id}",
            "gps_coordinates":"19.0321692,73.0603878"
          }'

Retrieve a POA verification

Retrieves the details of an existing Proof Of Address (POA) verification. You need to supply the unique customer and POA verification identifier.

Attributes
ParameterDescription
customer_id
required		The unique identifier for the customer.
verification_id
required		The unique identifier for the screening.
 
   GET /v1/customers/{{customer_id}}/address-verifications/{{verification_id}}
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{{customer_id}}/address-verifications/{{verification_id}}' \
        --header 'Authorization: Bearer {accessTokenUser}' \
        --header 'Content-Type: application/json'
Example Response
    {
      "id": "{ADDRESS_VERIFICATION_ID}",
      "document_id": "{DOCUMENT_ID}",
      "status": "DONE",
      "outcome": {
        "result": "CLEAR",
        "customer_consistency": {
          "first_name": "CLEAR",
          "last_name": "CLEAR",
          "address": "CLEAR"
        },
        "analysis": {
          "document_age": "CLEAR"
        },
        "geo_location": {
          "ip_country_match": "CLEAR",
          "ip_proximity_match": "CLEAR",
          "gps_proximity_match": "CLEAR"
        }
      },
      "document_properties": {
        "holder_attributes": {
          "entity_name": "John Doe"
        },
        "document_attributes": {
          "document_type": "bank_statement",
          "issuer": "Lloyds Bank",
          "issuing_date": {
            "day": 21,
            "month": 8,
            "year": 2017
          }
        },
        "address_attributes": {
          "address": {
            "property_number": "28",
            "line": "Rivington St",
            "city": "London",
            "state": "London",
            "postalCode": "EC2A 3DU",
            "country": "GB",
            "coordinates": "42.987,-24.235"
          },
          "address_line": "28 Rivington St London EC2A 3DU",
          "address_country": "GB"
        }
      },
      "created_at": "2017-11-10T22:54:17Z",
      "updated_at": "2017-11-10T22:54:17Z"
    }

List all POA verifications for customer

Lists all existing Proof Of Address (POA) 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
ParameterDescription
created_after
optional		A “greater than” filter on the list based on the object created_at field.
created_before
optional		A “less than” filter on the list based on the object created_at field.
updated_after
optional		A “greater than” filter on the list based on the object updated_at field.
updated_before
optional		A “less than” filter on the list based on the object updated_at field.
type
optional		An “equal” filter on the list based on the object type field.
status
optional		An “equal” filter on the list based on the object status field.
 
   GET /v1/customers/{{customer__id}}/address-verifications
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{{customer_id}}/address-verifications' \
        --header 'Authorization: Bearer {accessTokenUser}' \
        --header 'Content-Type: application/json' \
        --data '{
            "document_id" : "{{document_id}}",
            "type" : "image"
        }'

Search Proof Of Address Verifications

Search for Proof Of Address (POA) 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
ParameterDescription
created_after
optional		A “greater than” filter on the list based on the object created_at field.
created_before
optional		A “less than” filter on the list based on the object created_at field.
updated_after
optional		A “greater than” filter on the list based on the object updated_at field.
updated_before
optional		A “less than” filter on the list based on the object updated_at field.
text
optional		A “contains” filter on the list based on the object text field.
 
   GET /v1/search/verifications?created_after=2022-06-01
 
  curl --location 'https://api.cleardil.com/v1/search/address-verifications?created_after=2022-06-01' \
        --header 'Authorization: Bearer api_token' \
        --header 'Content-Type: application/json'

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

ParameterDescription
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 TypeParametersDescription
SCREENING_REPORTscreening_id
string		Generates a report for a completed screening request.
Example Response
  {
    "id" : "{REPORT_ID}",
    "name" : "My first report",
    "type" : "SCREENING_REPORT",
    "parameters" : {
        "screening_id" : "{SCREENING_ID}"
    },
    "created_at" : "2018-02-11T12:00:16Z"
  }

Retrieve a report

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

Attributes
ParameterDescription
report_id
required		The unique identifier for the report.
 
   GET /v1/reports/{report_id}
 
  curl --location 'https://api.cleardil.com/v1/reports/{report_id}' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer api_token'
Example Response
  {
      "id" : "{REPORT_ID}",
      "name" : "My first report",
      "type" : "SCREENING_REPORT",
      "parameters" : {
          "screening_id" : "{SCREENING_ID}"
      },
      "created_at" : "2018-02-11T12:00:16Z"
  }

Download a report

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

Attributes
ParameterDescription
report_id
required		The unique identifier for the report.
extension
required		The required format for the report. Valid values are:
1.PDF
 
   GET /v1/reports/{report_id}/pdf
 
  curl --location 'https://api.cleardil.com/v1/reports/{report_id}/pdf' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer api_token'

List all report

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
ParameterDescription
created_after
optional		A “greater than” filter on the list based on the object created_at field.
created_before
optional		A “less than” filter on the list based on the object created_at field.
type
optional		An “equal” filter on the list based on the object type field.
 
   GET /v1/reports
 
  curl --location 'https://api.cleardil.com/v1/reports' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer api_token'

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

Attributes
ParameterDescription
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.
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
  }

Retrieve a file

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

Attributes
ParameterDescription
file_id
required		The unique identifier for the file.
 
   GET /v1/files/{{file_id}}
 
  curl --location --globoff --request GET 'https://api.cleardil.com/v1/files/{{file_id}}' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI1WWR1TU5ac1NvdVRIMk5hRXQ4Wlg3VXlpdlVsTWxnXzh0clFIRVhLWWs0In0.eyJqdGkiOiJiY2YxMzliZS0xZDdjLTQ5MDEtOTE2NC00ZTNjY2JjNjg4OTAiLCJleHAiOjE3MDYyMTc5NzQsIm5iZiI6MCwiaWF0IjoxNzA2MjE0Mzc0LCJpc3MiOiJodHRwOi8va2V5Y2xvYWs6ODA4MC9hdXRoL3JlYWxtcy9jbGVhcmRpbCIsImF1ZCI6ImNyeXB0bzFfaWQiLCJzdWIiOiI2MTg1NGJhMS0yMTczLTRiMTktYTQzOC05NjcxMmFlNzJlZmIiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJjcnlwdG8xX2lkIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiN2U0MzA2YmYtNmU1My00ZmQyLThlYmUtOGM3Yjk1YTM1MTBmIiwiYWNyIjoiMSIsImNsaWVudF9zZXNzaW9uIjoiMjQ1ZTJlOGMtNmJhOC00ZGQzLTg0NmUtYjExNDI2YTljNzVkIiwiYWxsb3dlZC1vcmlnaW5zIjpbXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIlJPTEVfVVNFUiIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwiY2xpZW50SG9zdCI6IjE3Mi4xOC4wLjUiLCJjbGllbnRJZCI6ImNyeXB0bzFfaWQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzZXJ2aWNlLWFjY291bnQtY3J5cHRvMV9pZCIsImNsaWVudEFkZHJlc3MiOiIxNzIuMTguMC41IiwiYXV0aG9yaXRpZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJST0xFX1VTRVIiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfQ.K5_ZlGSKhcdIXDqQRxUaxsoysoUNEkMY2S09eutWvv8firWwP3eN8bCgeGWS3Vpog4vvvKo54XLfHWQe54480eQPvuPN8J5MCEYMjkiHPWqH47a9V2D8vd1pLyMGKOkLMsMnVbdTcpgUyNdH7TvUT0qskmlUn24Sd01cx6LIQ_sCxkhOrsgMxMfEiSIua1ZtmtnCFX2HWrHOFlvZJlldnAUMYVqN_lEGOnC1dJvhhIWFTskaw2XQbwmOEHlxFTITmIhaduYVMyo3EhmzHe_iymXSy9prlSjnZi8ucv3rFrLQWts2KlQDZmjdctRlx2AdLuiC3vRHH4sYlSTC0LfY6g' \
        --data '{
          "text" : "this is a note about Brian!"
        }'
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
  }

Download a file

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

Attributes
ParameterDescription
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.
 
   GET /v1/files/{{file_id}}?output=BASE64
 
  curl --location --globoff 'https://api.cleardil.com/v1/files/{{file_id}}?output=BASE64' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI1WWR1TU5ac1NvdVRIMk5hRXQ4Wlg3VXlpdlVsTWxnXzh0clFIRVhLWWs0In0.eyJqdGkiOiJiY2YxMzliZS0xZDdjLTQ5MDEtOTE2NC00ZTNjY2JjNjg4OTAiLCJleHAiOjE3MDYyMTc5NzQsIm5iZiI6MCwiaWF0IjoxNzA2MjE0Mzc0LCJpc3MiOiJodHRwOi8va2V5Y2xvYWs6ODA4MC9hdXRoL3JlYWxtcy9jbGVhcmRpbCIsImF1ZCI6ImNyeXB0bzFfaWQiLCJzdWIiOiI2MTg1NGJhMS0yMTczLTRiMTktYTQzOC05NjcxMmFlNzJlZmIiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJjcnlwdG8xX2lkIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiN2U0MzA2YmYtNmU1My00ZmQyLThlYmUtOGM3Yjk1YTM1MTBmIiwiYWNyIjoiMSIsImNsaWVudF9zZXNzaW9uIjoiMjQ1ZTJlOGMtNmJhOC00ZGQzLTg0NmUtYjExNDI2YTljNzVkIiwiYWxsb3dlZC1vcmlnaW5zIjpbXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIlJPTEVfVVNFUiIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwiY2xpZW50SG9zdCI6IjE3Mi4xOC4wLjUiLCJjbGllbnRJZCI6ImNyeXB0bzFfaWQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzZXJ2aWNlLWFjY291bnQtY3J5cHRvMV9pZCIsImNsaWVudEFkZHJlc3MiOiIxNzIuMTguMC41IiwiYXV0aG9yaXRpZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJST0xFX1VTRVIiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfQ.K5_ZlGSKhcdIXDqQRxUaxsoysoUNEkMY2S09eutWvv8firWwP3eN8bCgeGWS3Vpog4vvvKo54XLfHWQe54480eQPvuPN8J5MCEYMjkiHPWqH47a9V2D8vd1pLyMGKOkLMsMnVbdTcpgUyNdH7TvUT0qskmlUn24Sd01cx6LIQ_sCxkhOrsgMxMfEiSIua1ZtmtnCFX2HWrHOFlvZJlldnAUMYVqN_lEGOnC1dJvhhIWFTskaw2XQbwmOEHlxFTITmIhaduYVMyo3EhmzHe_iymXSy9prlSjnZi8ucv3rFrLQWts2KlQDZmjdctRlx2AdLuiC3vRHH4sYlSTC0LfY6g'

Update a file

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
ParameterDescription
file_id
required		The unique identifier for the file.
filenameThe 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.
 
   PUT /v1/files/{{file_id}}
 
  curl --location --globoff --request PUT 'https://api.cleardil.com/v1/files/{{file_id}}' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI1WWR1TU5ac1NvdVRIMk5hRXQ4Wlg3VXlpdlVsTWxnXzh0clFIRVhLWWs0In0.eyJqdGkiOiJiY2YxMzliZS0xZDdjLTQ5MDEtOTE2NC00ZTNjY2JjNjg4OTAiLCJleHAiOjE3MDYyMTc5NzQsIm5iZiI6MCwiaWF0IjoxNzA2MjE0Mzc0LCJpc3MiOiJodHRwOi8va2V5Y2xvYWs6ODA4MC9hdXRoL3JlYWxtcy9jbGVhcmRpbCIsImF1ZCI6ImNyeXB0bzFfaWQiLCJzdWIiOiI2MTg1NGJhMS0yMTczLTRiMTktYTQzOC05NjcxMmFlNzJlZmIiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJjcnlwdG8xX2lkIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiN2U0MzA2YmYtNmU1My00ZmQyLThlYmUtOGM3Yjk1YTM1MTBmIiwiYWNyIjoiMSIsImNsaWVudF9zZXNzaW9uIjoiMjQ1ZTJlOGMtNmJhOC00ZGQzLTg0NmUtYjExNDI2YTljNzVkIiwiYWxsb3dlZC1vcmlnaW5zIjpbXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIlJPTEVfVVNFUiIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwiY2xpZW50SG9zdCI6IjE3Mi4xOC4wLjUiLCJjbGllbnRJZCI6ImNyeXB0bzFfaWQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzZXJ2aWNlLWFjY291bnQtY3J5cHRvMV9pZCIsImNsaWVudEFkZHJlc3MiOiIxNzIuMTguMC41IiwiYXV0aG9yaXRpZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJST0xFX1VTRVIiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfQ.K5_ZlGSKhcdIXDqQRxUaxsoysoUNEkMY2S09eutWvv8firWwP3eN8bCgeGWS3Vpog4vvvKo54XLfHWQe54480eQPvuPN8J5MCEYMjkiHPWqH47a9V2D8vd1pLyMGKOkLMsMnVbdTcpgUyNdH7TvUT0qskmlUn24Sd01cx6LIQ_sCxkhOrsgMxMfEiSIua1ZtmtnCFX2HWrHOFlvZJlldnAUMYVqN_lEGOnC1dJvhhIWFTskaw2XQbwmOEHlxFTITmIhaduYVMyo3EhmzHe_iymXSy9prlSjnZi8ucv3rFrLQWts2KlQDZmjdctRlx2AdLuiC3vRHH4sYlSTC0LfY6g' \
        --data '{
                  "content_type": "image/jpeg",
                  "filename" : "passport copy",
                  "size" : 1234
        }'
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
 }

Partially update a file

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.

 
   PATCH /v1/files/{{file_id}}
 
  curl --location --globoff --request PATCH 'https://api.cleardil.com/v1/files/{{file_id}}' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI1WWR1TU5ac1NvdVRIMk5hRXQ4Wlg3VXlpdlVsTWxnXzh0clFIRVhLWWs0In0.eyJqdGkiOiJiY2YxMzliZS0xZDdjLTQ5MDEtOTE2NC00ZTNjY2JjNjg4OTAiLCJleHAiOjE3MDYyMTc5NzQsIm5iZiI6MCwiaWF0IjoxNzA2MjE0Mzc0LCJpc3MiOiJodHRwOi8va2V5Y2xvYWs6ODA4MC9hdXRoL3JlYWxtcy9jbGVhcmRpbCIsImF1ZCI6ImNyeXB0bzFfaWQiLCJzdWIiOiI2MTg1NGJhMS0yMTczLTRiMTktYTQzOC05NjcxMmFlNzJlZmIiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJjcnlwdG8xX2lkIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiN2U0MzA2YmYtNmU1My00ZmQyLThlYmUtOGM3Yjk1YTM1MTBmIiwiYWNyIjoiMSIsImNsaWVudF9zZXNzaW9uIjoiMjQ1ZTJlOGMtNmJhOC00ZGQzLTg0NmUtYjExNDI2YTljNzVkIiwiYWxsb3dlZC1vcmlnaW5zIjpbXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIlJPTEVfVVNFUiIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwiY2xpZW50SG9zdCI6IjE3Mi4xOC4wLjUiLCJjbGllbnRJZCI6ImNyeXB0bzFfaWQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzZXJ2aWNlLWFjY291bnQtY3J5cHRvMV9pZCIsImNsaWVudEFkZHJlc3MiOiIxNzIuMTguMC41IiwiYXV0aG9yaXRpZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJST0xFX1VTRVIiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfQ.K5_ZlGSKhcdIXDqQRxUaxsoysoUNEkMY2S09eutWvv8firWwP3eN8bCgeGWS3Vpog4vvvKo54XLfHWQe54480eQPvuPN8J5MCEYMjkiHPWqH47a9V2D8vd1pLyMGKOkLMsMnVbdTcpgUyNdH7TvUT0qskmlUn24Sd01cx6LIQ_sCxkhOrsgMxMfEiSIua1ZtmtnCFX2HWrHOFlvZJlldnAUMYVqN_lEGOnC1dJvhhIWFTskaw2XQbwmOEHlxFTITmIhaduYVMyo3EhmzHe_iymXSy9prlSjnZi8ucv3rFrLQWts2KlQDZmjdctRlx2AdLuiC3vRHH4sYlSTC0LfY6g' \
        --data '[
            {
                "op": "replace",
                "path": "/filename",
                "value": "passport copy"
            }
        ]'

List all 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
ParameterDescription
created_after
optional		A “greater than” filter on the list based on the object created_at field.
created_before
optional		A “less than” filter on the list based on the object created_at field.
updated_after
optional		A “greater than” filter on the list based on the object updated_at field.
updated_before
optional		A “less than” filter on the list based on the object updated_at field.
 
   GET /v1/files
 
  curl --location 'https://api.cleardil.com/v1/files' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI1WWR1TU5ac1NvdVRIMk5hRXQ4Wlg3VXlpdlVsTWxnXzh0clFIRVhLWWs0In0.eyJqdGkiOiJiY2YxMzliZS0xZDdjLTQ5MDEtOTE2NC00ZTNjY2JjNjg4OTAiLCJleHAiOjE3MDYyMTc5NzQsIm5iZiI6MCwiaWF0IjoxNzA2MjE0Mzc0LCJpc3MiOiJodHRwOi8va2V5Y2xvYWs6ODA4MC9hdXRoL3JlYWxtcy9jbGVhcmRpbCIsImF1ZCI6ImNyeXB0bzFfaWQiLCJzdWIiOiI2MTg1NGJhMS0yMTczLTRiMTktYTQzOC05NjcxMmFlNzJlZmIiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJjcnlwdG8xX2lkIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiN2U0MzA2YmYtNmU1My00ZmQyLThlYmUtOGM3Yjk1YTM1MTBmIiwiYWNyIjoiMSIsImNsaWVudF9zZXNzaW9uIjoiMjQ1ZTJlOGMtNmJhOC00ZGQzLTg0NmUtYjExNDI2YTljNzVkIiwiYWxsb3dlZC1vcmlnaW5zIjpbXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIlJPTEVfVVNFUiIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwiY2xpZW50SG9zdCI6IjE3Mi4xOC4wLjUiLCJjbGllbnRJZCI6ImNyeXB0bzFfaWQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzZXJ2aWNlLWFjY291bnQtY3J5cHRvMV9pZCIsImNsaWVudEFkZHJlc3MiOiIxNzIuMTguMC41IiwiYXV0aG9yaXRpZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJST0xFX1VTRVIiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfQ.K5_ZlGSKhcdIXDqQRxUaxsoysoUNEkMY2S09eutWvv8firWwP3eN8bCgeGWS3Vpog4vvvKo54XLfHWQe54480eQPvuPN8J5MCEYMjkiHPWqH47a9V2D8vd1pLyMGKOkLMsMnVbdTcpgUyNdH7TvUT0qskmlUn24Sd01cx6LIQ_sCxkhOrsgMxMfEiSIua1ZtmtnCFX2HWrHOFlvZJlldnAUMYVqN_lEGOnC1dJvhhIWFTskaw2XQbwmOEHlxFTITmIhaduYVMyo3EhmzHe_iymXSy9prlSjnZi8ucv3rFrLQWts2KlQDZmjdctRlx2AdLuiC3vRHH4sYlSTC0LfY6g'

Delete a file

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
ParameterDescription
file_id
required		The unique identifier for the file.
 
   DELETE /v1/files/{{file_id}}
 
  curl --location --globoff --request DELETE 'https://api.cleardil.com/v1/files/{{file_id}}' \
        --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI1WWR1TU5ac1NvdVRIMk5hRXQ4Wlg3VXlpdlVsTWxnXzh0clFIRVhLWWs0In0.eyJqdGkiOiJiY2YxMzliZS0xZDdjLTQ5MDEtOTE2NC00ZTNjY2JjNjg4OTAiLCJleHAiOjE3MDYyMTc5NzQsIm5iZiI6MCwiaWF0IjoxNzA2MjE0Mzc0LCJpc3MiOiJodHRwOi8va2V5Y2xvYWs6ODA4MC9hdXRoL3JlYWxtcy9jbGVhcmRpbCIsImF1ZCI6ImNyeXB0bzFfaWQiLCJzdWIiOiI2MTg1NGJhMS0yMTczLTRiMTktYTQzOC05NjcxMmFlNzJlZmIiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJjcnlwdG8xX2lkIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiN2U0MzA2YmYtNmU1My00ZmQyLThlYmUtOGM3Yjk1YTM1MTBmIiwiYWNyIjoiMSIsImNsaWVudF9zZXNzaW9uIjoiMjQ1ZTJlOGMtNmJhOC00ZGQzLTg0NmUtYjExNDI2YTljNzVkIiwiYWxsb3dlZC1vcmlnaW5zIjpbXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIlJPTEVfVVNFUiIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwiY2xpZW50SG9zdCI6IjE3Mi4xOC4wLjUiLCJjbGllbnRJZCI6ImNyeXB0bzFfaWQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzZXJ2aWNlLWFjY291bnQtY3J5cHRvMV9pZCIsImNsaWVudEFkZHJlc3MiOiIxNzIuMTguMC41IiwiYXV0aG9yaXRpZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJST0xFX1VTRVIiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfQ.K5_ZlGSKhcdIXDqQRxUaxsoysoUNEkMY2S09eutWvv8firWwP3eN8bCgeGWS3Vpog4vvvKo54XLfHWQe54480eQPvuPN8J5MCEYMjkiHPWqH47a9V2D8vd1pLyMGKOkLMsMnVbdTcpgUyNdH7TvUT0qskmlUn24Sd01cx6LIQ_sCxkhOrsgMxMfEiSIua1ZtmtnCFX2HWrHOFlvZJlldnAUMYVqN_lEGOnC1dJvhhIWFTskaw2XQbwmOEHlxFTITmIhaduYVMyo3EhmzHe_iymXSy9prlSjnZi8ucv3rFrLQWts2KlQDZmjdctRlx2AdLuiC3vRHH4sYlSTC0LfY6g' \
        --data ''

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

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

Create a note

Creates a new note object.

Attributes
ParameterDescription
text
required		The text of the note. A note can not exceed 4000 characters.
 
   POST /v1/customers/{customer_id}/notes
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/notes' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI1WWR1TU5ac1NvdVRIMk5hRXQ4Wlg3VXlpdlVsTWxnXzh0clFIRVhLWWs0In0.eyJqdGkiOiJiY2YxMzliZS0xZDdjLTQ5MDEtOTE2NC00ZTNjY2JjNjg4OTAiLCJleHAiOjE3MDYyMTc5NzQsIm5iZiI6MCwiaWF0IjoxNzA2MjE0Mzc0LCJpc3MiOiJodHRwOi8va2V5Y2xvYWs6ODA4MC9hdXRoL3JlYWxtcy9jbGVhcmRpbCIsImF1ZCI6ImNyeXB0bzFfaWQiLCJzdWIiOiI2MTg1NGJhMS0yMTczLTRiMTktYTQzOC05NjcxMmFlNzJlZmIiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJjcnlwdG8xX2lkIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiN2U0MzA2YmYtNmU1My00ZmQyLThlYmUtOGM3Yjk1YTM1MTBmIiwiYWNyIjoiMSIsImNsaWVudF9zZXNzaW9uIjoiMjQ1ZTJlOGMtNmJhOC00ZGQzLTg0NmUtYjExNDI2YTljNzVkIiwiYWxsb3dlZC1vcmlnaW5zIjpbXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIlJPTEVfVVNFUiIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwiY2xpZW50SG9zdCI6IjE3Mi4xOC4wLjUiLCJjbGllbnRJZCI6ImNyeXB0bzFfaWQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzZXJ2aWNlLWFjY291bnQtY3J5cHRvMV9pZCIsImNsaWVudEFkZHJlc3MiOiIxNzIuMTguMC41IiwiYXV0aG9yaXRpZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJST0xFX1VTRVIiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfQ.K5_ZlGSKhcdIXDqQRxUaxsoysoUNEkMY2S09eutWvv8firWwP3eN8bCgeGWS3Vpog4vvvKo54XLfHWQe54480eQPvuPN8J5MCEYMjkiHPWqH47a9V2D8vd1pLyMGKOkLMsMnVbdTcpgUyNdH7TvUT0qskmlUn24Sd01cx6LIQ_sCxkhOrsgMxMfEiSIua1ZtmtnCFX2HWrHOFlvZJlldnAUMYVqN_lEGOnC1dJvhhIWFTskaw2XQbwmOEHlxFTITmIhaduYVMyo3EhmzHe_iymXSy9prlSjnZi8ucv3rFrLQWts2KlQDZmjdctRlx2AdLuiC3vRHH4sYlSTC0LfY6g' \
        --data '{
          "text" : "this is a note about Brian!"
        }'
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."
  }

Retrieve a note

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

Attributes
ParameterDescription
customer_id
required		The unique identifier for the customer.
note_id
required		The unique identifier for the note.
 
   GET /v1/customers/{customer_id}/notes/{{note_a_id}}
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/notes/{{note_a_id}}' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI1WWR1TU5ac1NvdVRIMk5hRXQ4Wlg3VXlpdlVsTWxnXzh0clFIRVhLWWs0In0.eyJqdGkiOiJiY2YxMzliZS0xZDdjLTQ5MDEtOTE2NC00ZTNjY2JjNjg4OTAiLCJleHAiOjE3MDYyMTc5NzQsIm5iZiI6MCwiaWF0IjoxNzA2MjE0Mzc0LCJpc3MiOiJodHRwOi8va2V5Y2xvYWs6ODA4MC9hdXRoL3JlYWxtcy9jbGVhcmRpbCIsImF1ZCI6ImNyeXB0bzFfaWQiLCJzdWIiOiI2MTg1NGJhMS0yMTczLTRiMTktYTQzOC05NjcxMmFlNzJlZmIiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJjcnlwdG8xX2lkIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiN2U0MzA2YmYtNmU1My00ZmQyLThlYmUtOGM3Yjk1YTM1MTBmIiwiYWNyIjoiMSIsImNsaWVudF9zZXNzaW9uIjoiMjQ1ZTJlOGMtNmJhOC00ZGQzLTg0NmUtYjExNDI2YTljNzVkIiwiYWxsb3dlZC1vcmlnaW5zIjpbXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIlJPTEVfVVNFUiIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwiY2xpZW50SG9zdCI6IjE3Mi4xOC4wLjUiLCJjbGllbnRJZCI6ImNyeXB0bzFfaWQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzZXJ2aWNlLWFjY291bnQtY3J5cHRvMV9pZCIsImNsaWVudEFkZHJlc3MiOiIxNzIuMTguMC41IiwiYXV0aG9yaXRpZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJST0xFX1VTRVIiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfQ.K5_ZlGSKhcdIXDqQRxUaxsoysoUNEkMY2S09eutWvv8firWwP3eN8bCgeGWS3Vpog4vvvKo54XLfHWQe54480eQPvuPN8J5MCEYMjkiHPWqH47a9V2D8vd1pLyMGKOkLMsMnVbdTcpgUyNdH7TvUT0qskmlUn24Sd01cx6LIQ_sCxkhOrsgMxMfEiSIua1ZtmtnCFX2HWrHOFlvZJlldnAUMYVqN_lEGOnC1dJvhhIWFTskaw2XQbwmOEHlxFTITmIhaduYVMyo3EhmzHe_iymXSy9prlSjnZi8ucv3rFrLQWts2KlQDZmjdctRlx2AdLuiC3vRHH4sYlSTC0LfY6g'
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."
  }

Update a note

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

Attributes
ParameterDescription
customer_id
required		The unique identifier for the customer.
note_id
required		The unique identifier for the note.
textThe text of the note.
 
   PUT /v1/customers/{customer_id}/notes/{note_id}
 
  curl --location --globoff --request PUT 'https://api.cleardil.com/v1/customers/{customer_id}/notes/{note_id}' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer api_token' \
        --data '{
                "text" : "this is a note about Brian!"
        }'
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."
  }

Delete a note

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

Attributes
ParameterDescription
customer_id
required		The unique identifier for the customer.
note_id
required		The unique identifier for the note.
 
   DELETE /v1/customers/{customer_id}
 
  curl --location --globoff --request DELETE 'https://api.cleardil.com/v1/customers/{customer_id}' \
        --header 'Authorization: Bearer api_token' \
        --data ''

List all 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
ParameterDescription
created_after
optional		A “greater than” filter on the list based on the object created_at field.
created_before
optional		A “less than” filter on the list based on the object created_at field.
updated_after
optional		A “greater than” filter on the list based on the object updated_at field.
updated_before
optional		A “less than” filter on the list based on the object updated_at field.
text
optional		A “contains” filter on the list based on the object text field.
 
   GET /v1/customers/{customer_id}/notes
 
  curl --location --globoff 'https://api.cleardil.com/v1/customers/{customer_id}/notes' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer api_token'