Review Matches

Get Started > API User Guide > Review Matches

Review Matches

A screening request may result in one or multiple matches. A match is determined by ClearDil’s fuzzy scorecard logic and pre-defined thresholds. The matches API allows you to retrieve, review, and validate matches relating to a given screening request. The validation of a potential match refers to either the confirmation or dismissal of the match once you have reviewed the details at hand.

Unlike many other AML KYC providers that provide a binary response to your screening requests (i.e. match found or not found), we provide the means to manage the end-to-end flow of your customer screening, investigation, research and validation.

Retrieve Matches

To get the list of potential matches, execute the cURL sample request below.

Example request:

    curl -X GET https://api.cleardil.com/v1/customer/{customer_id}/screeings/{screeing_id}/matches \
         -H 'Authorization: Bearer your_token'

Retrieve a Match

To review a single match from the list of matches, you can execute the cURL sample request below.

Example request:

    curl -X GET https://api.cleardil.com/v1/customer/{customer_id}/screeings/{screeing_id}/matches/{match_id} \
         -H 'Authorization: Bearer your_token'

Example response:

    {
        "id": "123456-7890-4cb4-b9bf-12a34bc56dff",
        "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
                        }
                    ]
                }
            ]
        }
    }

Review Associations

Unlike other AML KYC providers, ClearDil offers extensive information on the associates of a given match such as relatives, business partners, and friends. To review entities associated with a given match, you can execute the cURL sample request below.

Example request:

    curl -X GET https://api.cleardil.com/v1/customer/{customer_id}/screeings/{screeing_id}/matches/{match_id}/associations \
         -H 'Authorization: Bearer your_token'

Retrieve an Association

To review a single association, you can execute the cURL sample request below.

    curl -X GET https://api.cleardil.com/v1/customer/{customer_id}/screeings/{screeing_id}/matches/{match_id}/associations/{association_id} \
         -H 'Authorization: Bearer your_token'

Example response:

    {
        "id": "123456-7890-4cb4-b9bf-01f11dc85e11",
        "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",
        ]
      }

Please refer to API Reference for further information regarding the Matches API and Associations API.