Managing Duplicate Entities

What are Duplicate Checks?

Duplicate checks are essential for maintaining data integrity, reducing fraud risk, and ensuring compliance. They prevent the creation of multiple records for the same individual within your system.

FrankieOne integrates this capability directly into your KYC workflow via a dedicated DUPLICATE step. This step provides:

• Automated identification of possible duplicates using configurable, rules-based matching logic.
• Manual review and resolution capabilities for operators to confirm or dismiss flagged duplicates.
• Seamless integration with existing KYC processes to support both operational efficiency and regulatory compliance.

How Duplicate Checks Work

The process is designed to flag potential duplicates during onboarding and provide your team with the tools to resolve them.

Implementation and API Guide

Step 1: Interpreting the Duplicate Check Result

When the DUPLICATE step returns a HIT, you need to parse the processResults within that step to understand the match. Each PRO will have class: "DUPLICATE".

The most important information is in the supplementaryData object.

1
{
2
    "processResultId": "01JNFWT5MKE75FMMZPWC7SDG2Z",
3
    "result": "HIT",
4
    "class": "DUPLICATE",
5
    "stepName": "DUPLICATE",
6
    "supplementaryData": {
7
        "type": "DUPLICATE",
8
        "duplicateEntityId": "98c545b6-7545-4337-85ce-30c64ef1ccff",
9
        "matchedFields": [
10
            {
11
                "objectType": "NAME",
12
                "objectId": "840268d6-d37e-43ad-a421-d35345472df4",
13
                "duplicateObjectId": "4331b636-5cb2-46d6-bba1-03536232909b",
14
                "matchStrength": 86
15
            },
16
            {
17
                "objectType": "ADDRESS",
18
                "objectId": "9c5fdaeb-056a-47c7-a36e-dcb59ddce5b3",
19
                "duplicateObjectId": "c0d6872f-dd14-43f2-86b2-60e1e7ae24c4",
20
                "matchStrength": 100
21
            }
22
        ],
23
        "matchedRules": [
24
            {
25
                "name": "Given + Family name + Short form normalised address",
26
                "strength": "HIGH"
27
            }
28
        ]
29
    }
30
}

Key supplementaryData Fields:

• duplicateEntityId: The entityId of the existing profile that was matched.
• matchedFields: An array detailing exactly which attributes matched between the two entities (e.g., NAME, ADDRESS). It includes the specific objectId for each attribute and the matchStrength.
• matchedRules: Shows which configured rule was triggered to create this match.

Step 2: Resolving Duplicates

After reviewing the evidence, an operator must classify the match. This is done by sending a PATCH request with the processResultId and a manualStatus.

Endpoint:

1
PATCH /v2/individuals/{entityId}/results/duplicate

Understanding the Manual Statuses The manualStatus you send should reflect the operator’s decision.

$
curl -X PATCH \
>
'{{baseHost}}/v2/individuals/{{entityId}}/results/duplicate' \
>
-H 'api_key: YOUR_API_KEY' \
>
-H 'X-Frankie-CustomerID: YOUR_CUSTOMER_ID' \
>
-d '{
>
    "processResults": [
>
        "01JNFWT5MKE75FMMZPWC7SDG2Z"
>
    ],
>
    "manualStatus": "FALSE_POSITIVE",
>
    "comment": {
>
        "text": "Reviewed by operator. Confirmed different individuals with similar names."
>
    }
>
}'

Key Concepts: State and Relationships

• Relationships: When a duplicate is confirmed (TRUE_POSITIVE_ACCEPT or TRUE_POSITIVE_REJECT), a permanent relationship is created between the two entities. You can see this in the response of GET /v2/individuals/{entityId} under the relationships.duplicates array.
• DUPLICATE State: An entity’s service profile is moved to the DUPLICATE state when a relationship identifies it as such. An entity remains a duplicate as long as at least one relationship points to it. If all such relationships are removed (e.g., by being marked as FALSE_POSITIVE or if the source entity is deleted), its DUPLICATE state will be revoked.

Configuration (Reference)

The matching logic for the DUPLICATE step is highly configurable by the FrankieOne team.

1
{
2
    "ruleSets": {
3
        "default": {
4
            "rules": [
5
                {
6
                    "name": "Document identifiers",
7
                    "matchFields": [ "DOC_PRIMARY_IDENTIFIER", "DOC_TYPE", "DOC_COUNTRY" ],
8
                    "method": "EXACT",
9
                    "riskFactor": "VERY_HIGH"
10
                },
11
                {
12
                    "name": "Given + Family name + Date of birth",
13
                    "matchFields": [ "GIVEN_NAME", "FAMILY_NAME", "DATE_OF_BIRTH" ],
14
                    "method": "EXACT",
15
                    "riskFactor": "VERY_HIGH"
16
                }
17
            ]
18
        }
19
    }
20
}

Duplicate Check Logic

FrankieOne’s duplicate detection uses configurable rules to compare key attributes between entities. If any rule is matched, the entity is flagged as a potential duplicate.

Matching Rule Examples:

• External Reference: Exact match on EXTERNAL_REFERENCE.
• Document Identifiers: Exact match on all of DOC_PRIMARY_IDENTIFIER, DOC_SECONDARY_IDENTIFIER, DOC_COUNTRY, DOC_SUBDIVISION, and DOC_TYPE.
• Phone Number: Exact match on PHONE_NUMBER.
• Email Address: Exact match on EMAIL_ADDRESS.
• Full Name: Exact match on both GIVEN_NAME and FAMILY_NAME.
• Full Name + Date of Birth: Exact match on GIVEN_NAME, FAMILY_NAME, and DATE_OF_BIRTH.
• Full Name + Normalised Address: Exact match on ADDR_NORM_SHORT, GIVEN_NAME, and FAMILY_NAME.

All rules use exact matching. You can customise which rules are active and their risk levels by working with FrankieOne.