Matchlists (Blocklists)

Matchlists: The Upgraded Blocklist

Matchlists are a sophisticated tool in FrankieOne’s suite, designed to enhance the Know Your Customer (KYC) processes by allowing entities to be screened against curated lists of attributes. Unlike traditional blocklists, Matchlists provide nuanced classification for more granular decision-making during onboarding workflows. In the current implementation, Blocklists are the first type of Matchlist available, providing advanced screening capabilities beyond simple blocklisting. While Matchlists can be used for blocking, their enhanced capabilities allow for more sophisticated risk management.

Key Features

Getting Started

Follow these steps to begin using Matchlists for enhanced KYC processes. Ensure the Matchlist Step is added to your workflow, especially if you are migrating from v1 to v2.

1
{
2
  "requestId": "01HN9XHZN6MGXM9JXG50K59Q85",
3
  "matchlists": [
4
    {
5
      "matchlistId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
6
      "name": "Blocklist",
7
      "description": "Prevents the entity from proceeding in the workflow.",
8
      "isDefault": true,
9
      "action": "BLOCK",
10
      "riskScore": 1,
11
      "state": "ACTIVE",
12
      "createdBy": "operator-12345", // Example operatorId
13
      "createdAt": "2025-04-01T01:39:07.182Z",
14
      "updatedBy": "operator-67890", // Example operatorId
15
      "updatedAt": "2025-04-01T01:39:07.182Z"
16
    }
17
  ]
18
}

1
// Add a batch of entries to the Matchlist
2
{
3
"batchName": "blocklist-1.csv", // Name of the batch for tracking purposes
4
"entries": [
5
{
6
  "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", // Unique identifier for the entity
7
  "reference": "CERT-BAD-ACTOR-1234-5678", // Reference for the entry
8
  "reasons": [
9
    "FREQUENT_USE_EMAIL" // Reason for adding the entity
10
  ],
11
  "attributes": [
12
    {
13
      "type": "ENTITY_TYPE",
14
      "value": "INDIVIDUAL"
15
    },
16
    {
17
      "type": "IND_DISPLAY_NAME",
18
      "value": "John Doe"
19
    },
20
    {
21
      "type": "EMAIL_ADDRESS",
22
      "value": "john.doe@example.com"
23
    }
24
  ]
25
}
26
],
27
"comment": {
28
"text": "Update after speaking to security over phone directly" // Additional context for the entry
29
}
30
}

Managing Entries

Learn how to retrieve, search, update, and manage entries within your Matchlists. This section covers the endpoints and methods available for handling Matchlist entries effectively.

Retrieve Entries

Get a list of entries using the endpoint GET /v2/matchlists/{matchlistName}/entries/{entityId}.

Search Entries

Use the endpoint GET /v2/matchlists/{matchlistName}/entries/search to search for entries based on matchlist attributes. Note that attribute comparisons are case-insensitive (e.g., “John” equals “john”).

Retrieve a Matchlist Entry

Retrieve a matchlist entry using the endpoint GET /v2/matchlists/{matchlistName}/entries/{entityId}.

Modify Entries

Use endpoint PATCH v2/matchlists/{matchlistName}/entries/{entityId} to update a matchlist entry’s non-attribute fields such as reference, state, reason.

Add Individual to Matchlist

Add an individual to the Matchlist using the endpoint POST /v2/matchlists/{matchlistName}/entries/addEntity.

Remove Individual from Matchlist

Remove an individual from a Matchlist using the endpoint PATCH /v2/matchlists/{matchlistName}/entries/removeEntity. This automatically sets the state of the entry to DELETED.

Screening Workflow

Integrate Matchlists into your onboarding workflow to enhance risk assessment and decision-making. The following steps outline how to effectively utilize Matchlists in your KYC processes.

Reason Codes

The following table outlines the predefined reason codes available for Blocklists. Customers can add their own reason codes if needed.

A Note on Duplicate Entries

To ensure data integrity, the Matchlist system enforces strict rules to prevent duplicate entries. These rules apply to both entityId and specific attribute combinations, depending on the entity type.

Key Principles

• Unique entityId: Each entry must have a unique entityId. Attempting to create an entry with an existing entityId will result in rejection.
• Attribute Combinations: Duplication checks also apply to specific attribute combinations, which vary by entity type:
  • Individual Entity Type:
    • The combination of IND_GIVEN_NAME, IND_FAMILY_NAME, and IND_DATE_OF_BIRTH must be unique.
  • Organization Entity Type:
    • The combination of ORG_NAME and ORG_REGISTERED_COUNTRY must be unique.
  • The combination of DOC_PRIMARY_IDENTIFIER and DOC_TYPE must be unique.
  • At least two attributes from the following set must be unique: ADDR_STREET_NUMBER, ADDR_STREET_NAME, ADDR_POSTAL_CODE, and ADDR_COUNTRY.
• Case Insensitivity: Attribute comparisons are case-insensitive (e.g., “John” equals “john”).

Important Considerations

• Entries without an entityId can still be created, but the attribute uniqueness rules will apply.
• If an entry violates the duplication rules, it will be rejected to maintain data integrity.
• The system prioritizes preventing duplication based on the defined rules to ensure accurate and reliable screening results.

By adhering to these rules, the Matchlist system ensures that each entry is unique and avoids conflicts or redundancies in the screening process.

Integration Instructions

Prerequisites

• Access to FrankieOne API.
• Configured Matchlist with defined attributes and match rules.
• Ensure your API keys are active and configured for access.

Troubleshooting

• Issue: Unable to create a Matchlist entry.
  • Solution: Ensure all required attributes are provided and avoid duplicates.
• Issue: No matches found during screening.
  • Solution: Verify that the correct Matchlist and attributes are being used.

Additional Resources

• FrankieOne API Documentation
• Contact Support