Matchlists (Blocklists) | FrankieOne

What are Matchlists?

Matchlists are a sophisticated tool in the FrankieOne platform designed to screen entities against curated lists of attributes during your KYC process. They are an evolution of traditional blocklists, offering more nuanced classification and control over your risk-based decisioning.

While the primary use case is often for “blocklisting,” the Matchlist framework is designed to be flexible, allowing for different actions based on your compliance policies. In the current implementation, Blocklists are the first type of Matchlist available.

How Matchlists Work

The process is integrated directly into the workflow engine, allowing for automated, real-time screening at onboarding.

1. Configure a Matchlist

The FrankieOne team will work with you to set up your initial Matchlists. For now, a default “Blocklist” will be created with an action of BLOCK and a risk score.

2. Add Entries to the Matchlist

You populate your Matchlist with entries via the API. Each entry consists of one or more attributes (e.g., a name, email address, or document number) that you want to screen against.

3. Execute a Workflow with a Matchlist Step

When you execute an onboarding workflow, the dedicated Matchlist Step will screen the entity’s data against the entries in your Matchlist.

4. Review and Classify Hits

If a match is found, the workflow will return a HIT. Your compliance team can then review the match and classify it (e.g., as a TRUE_POSITIVE_REJECT or FALSE_POSITIVE) via the API.

Managing Your Matchlist and Its Entries

While you cannot create your own Matchlists yet, you have full control over managing the entries within the lists configured for you by the FrankieOne team.

Retrieve Your Matchlist Details

Use the GET /v2/matchlists endpoint to retrieve the details of the Matchlists created for you. This is how you find the matchlistName needed for managing entries.

1 GET /v2/matchlists

Adding Entries to a Matchlist

You can add entries one by one or in bulk using the POST /v2/matchlists/{matchlistName}/entries endpoint. Each entry must contain an array of attributes.

Example: Adding a Batch of Entries

1 {
2   "batchName": "known-fraud-list-q3",
3   "entries": [
4     {
5       "entityId": "ent_01J...",
6       "reference": "CASE-12345",
7       "reasons": [ "SUSPECTED_FRAUD_EMAIL" ],
8       "attributes": [
9         { "type": "IND_DISPLAY_NAME", "value": "John Smith" },
10         { "type": "EMAIL_ADDRESS", "value": "john.smith.fraud@example.com" }
11       ]
12     }
13   ],
14   "comment": { "text": "Added based on fraud report from Tier 2 team." }
15 }

Preventing Duplicate Entries

To maintain data integrity, the system enforces uniqueness rules. An entry will be rejected if it is a duplicate.

By entityId: An entry with the same entityId as an existing entry will be rejected.
By Attribute Combination: The system also checks for uniqueness based on specific combinations of attributes, even if no entityId is provided.
- For Individuals:
  - IND_GIVEN_NAME + IND_FAMILY_NAME + IND_DATE_OF_BIRTH
  - DOC_PRIMARY_IDENTIFIER + DOC_TYPE
- For Organizations:
  - ORG_NAME + ORG_REGISTERED_COUNTRY

Screening and Classifying Results

The Matchlist Workflow Step

For screening to occur, your workflow must contain a Matchlist Step. When this step executes:

If no match is found, the step result is CLEAR.
If a match is found, the step result is HIT, and a BLOCKLISTED issue with BLOCK severity is generated.

Classifying a Match

When a match is found, a compliance officer must review it and classify it using the PATCH /v2/individuals/{entityId}/results/matchlist endpoint.

Manual Status	Description
`FALSE_POSITIVE`	The match is incorrect and does not indicate a valid risk.
`TRUE_POSITIVE_REJECT`	The match is accurate, and the entity should be rejected.

After classifying all hits for an entity, you should re-run the workflow. This will re-evaluate the Matchlist step. If all hits have been resolved as FALSE_POSITIVE, the step result will change to CLEARED, and the BLOCKLISTED issue will be removed.

Managing Individual Entries via API

You can perform full CRUD (Create, Read, Update, Delete) operations on the entries within your Matchlists.

Action	Endpoint
Retrieve Entries	`GET /v2/matchlists/{matchlistName}/entries`
Search Entries	`POST /v2/search/matchlists`
Modify an Entry	`PATCH /v2/matchlists/{matchlistName}/entries/{entryId}`

Updating Entry Attributes

You cannot directly update the attributes of an existing Matchlist entry. To change an attribute, you must first mark the old entry’s state as DELETED and then create a new entry with the updated attributes.

Adding and Removing an Entire Entity

You can also manage entries based on an entityId.

Add Entity: POST /v2/matchlists/{matchlistName}/entries/addEntity
Remove Entity: PATCH /v2/matchlists/{matchlistName}/entries/removeEntity (This sets the entry state to DELETED).

Reference: Reason Codes

When adding an entry to a blocklist, you can provide one or more reason codes to add context for auditing and review.

Reason Code	Description
`SYNTHETIC_ID`	The identity is suspected to be synthetic.
`SUSPECTED_FRAUD`	Fraud is suspected.
`SUSPECTED_ID_THEFT`	Identity theft is suspected.
`ID_USED_IN_KNOWN_FRAUD`	The identity has been used in known fraud incidents.
`ID_THEFT_VICTIM`	The individual is a known victim of identity theft.
`REQUESTED_BLOCK`	A block has been requested for this entity.
`SUSPECTED_FRAUD_ADDRESS`	The address is suspected of being associated with fraud.
`SUSPECTED_FRAUD_EMAIL`	The email is suspected of being associated with fraud.
`SUSPECTED_FRAUD_PHONE`	The phone number is suspected of being associated with fraud.
`FREQUENT_USE_ADDRESS`	The address is being used with unusual frequency.
`FREQUENT_USE_EMAIL`	The email is being used with unusual frequency.
`FREQUENT_USE_PHONE`	The phone number is being used with unusual frequency.
`SUSPECTED_MONEY_MULE`	The individual is suspected of being a money mule.
`NON_PAYMENT`	Non-payment is the reason for adding the entity.

Configurable Attributes for Matchlist Checks

You can use any of the following attributes to create rules for matchlist checking:

Entry Attribute Type	Notes
ENTITY_TYPE	Maps to entity profile
EMAIL_ADDRESS	Direct mapping to email object
EMAIL_DOMAIN	Part of email object
PHONE_NUMBER	Including country and format validation
ADDR_STREET_NUMBER	Part of address schema
ADDR_STREET_NAME	Part of address schema
ADDR_STREET_TYPE	Part of address schema
ADDR_NEIGHBORHOOD	Part of address components
ADDR_LOCALITY	Part of address components
ADDR_DISTRICT	Part of address components
ADDR_SUBDIVISION	Part of address schema
ADDR_COUNTRY	ISO-3166-1 format
ADDR_POSTAL_CODE	Part of address schema
ADDR_UNSTRUCTURED_LONG_FORM	Flexible address format
DOC_CLASS	Document classification
DOC_TYPE	Document type specification
DOC_SUBTYPE	Further document categorization
DOC_PRIMARY_IDENTIFIER	Main document identifier
DOC_SECONDARY_IDENTIFIER	Additional document identifier
IND_DISPLAY_NAME	Display name for individuals
IND_GIVEN_NAME	First name
IND_FAMILY_NAME	Last name
IND_MIDDLE_NAME	Middle name
IND_DATE_OF_BIRTH	Individual’s birth date
IND_NATIONALITY	Country of nationality