> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Matchlists (Blocklists)

> Learn how to manage and utilize Matchlists to enhance your KYC processes efficiently.

## 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## 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.

```http theme={null}
  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`.

```json title="Example: Adding a Batch of Entries" theme={null}
{
  "batchName": "known-fraud-list-q3",
  "entries": [
    {
      "entityId": "ent_01J...",
      "reference": "CASE-12345",
      "reasons": [ "SUSPECTED_FRAUD_EMAIL" ],
      "attributes": [
        { "type": "IND_DISPLAY_NAME", "value": "John Smith" },
        { "type": "EMAIL_ADDRESS", "value": "john.smith.fraud@example.com" }
      ]
    }
  ],
  "comment": { "text": "Added based on fraud report from Tier 2 team." }
}
```

### 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.  |

<Callout icon="thumbtack" color="#1A6CFF" iconType="regular">
  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.
</Callout>

***

## 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}` |

<Callout icon="bell" color="#FFCA16" iconType="regular">
  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.
</Callout>

### 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                  |