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

# Field Match API — Guide & Testing Reference

> Detailed guide for using and testing the /FieldMatch API, including match score ranges for all fields, test users, and test scenarios.

The [/FieldMatch](/api/utilities/identity/field-match) endpoint compares identity data you submit against financial data parsed from a connected bank account, returning scores per field (0–1) and an overall match rate.

Common applications include:

* Confirming account ownership before connecting a customer’s bank account to your financial service
* Verifying customer identity during onboarding
* Detecting discrepancies between submitted and actual account data

For setup instructions, see [Confirm Your Customer's Identity](./confirm-your-customers-identity).

## How it works

1. **Bank Connection**: The end-user links a bank account via Flinks Connect. The system parses financial data including full name, postal code, email, phone, address, city, and province, returning a `loginId`.

2. **Comparison Engine**: You submit identity data via POST to `/BankingServices/FieldMatch` with the `loginId`. A fuzzy matching algorithm compares submitted data against parsed bank data, accounting for abbreviations, missing tokens, and formatting differences.

3. **Match Result**: The response includes per-field scores and an overall match rate.

## Match score reference

### Name

| Range         | Description                                                      | Example                       |
| :------------ | :--------------------------------------------------------------- | :---------------------------- |
| **1.0**       | Exact Match                                                      | Jonathan Doe vs. Jonathan Doe |
| **0.80–0.99** | Strong Match — spelling error, nickname, or alternative spelling | Jonathan Doe vs. John Doe     |
| **0.65–0.79** | Possible Match — alias or multiple small discrepancies           | John Doe vs. Jon Do           |
| **0.50–0.64** | Unlikely Match — could indicate a relative or shared last name   | Jonathan Doe vs. Steve Doe    |
| **0–0.49**    | No Match — no common factors                                     | Jonathan Doe vs. Air Bud      |

### Postal code

| Range         | Description                                          | Example             |
| :------------ | :--------------------------------------------------- | :------------------ |
| **1.0**       | Exact Match                                          | M6N4H9 vs. M6N4H9   |
| **0.80–0.99** | Strong Match — format difference or extra characters | M6N4H9 vs. M6N 4H9A |
| **0.65–0.79** | Possible Match — one number or letter does not match | M6N4H9 vs. M6N4H1   |
| **0.50–0.64** | Unlikely Match — multiple characters do not match    | M6N4H9 vs. M6N2H8   |
| **0–0.49**    | No Match — no common factors                         | M6N4H9 vs. K7L3R67  |

### Phone

| Range         | Description                                              | Example                     |
| :------------ | :------------------------------------------------------- | :-------------------------- |
| **1.0**       | Exact Match — including same number in different formats | 4161234567 vs. 416-123-4567 |
| **0.80–0.99** | Strong Match — one digit different                       | 4161234567 vs. 4161234560   |
| **0–0.49**    | No Match — multiple digits or area code different        | 4161234567 vs. 4165559999   |

### Civic address

| Range         | Description                                                  | Example                                            |
| :------------ | :----------------------------------------------------------- | :------------------------------------------------- |
| **1.0**       | Exact Match                                                  | 6133 University Blvd vs. 6133 University Blvd      |
| **0.80–0.99** | Strong Match — abbreviated vs. full street type              | 6133 University Blvd vs. 6133 University Boulevard |
| **0.65–0.79** | Possible Match — different street type, same number and name | 6133 University Blvd vs. 6133 University Ave       |
| **0–0.49**    | No Match — different street number or street entirely        | 6133 University Blvd vs. 100 King St W             |

### City

| Range      | Description               | Example              |
| :--------- | :------------------------ | :------------------- |
| **1.0**    | Exact Match               | Toronto vs. Toronto  |
| **0–0.49** | No Match — different city | Toronto vs. Kingston |

### Province

| Range      | Description                   | Example   |
| :--------- | :---------------------------- | :-------- |
| **1.0**    | Exact Match                   | ON vs. ON |
| **0–0.49** | No Match — different province | ON vs. QC |

### Email

| Range         | Description                                             | Example                                                                                                             |
| :------------ | :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------ |
| **1.0**       | Exact Match                                             | [jonathan.doe@email.com](mailto:jonathan.doe@email.com) vs. [jonathan.doe@email.com](mailto:jonathan.doe@email.com) |
| **0.80–0.99** | Strong Match — different domain or minor name variation | [jonathan.doe@email.com](mailto:jonathan.doe@email.com) vs. [jonathan.doe@gmail.com](mailto:jonathan.doe@gmail.com) |
| **0.65–0.79** | Possible Match — shortened local part, same domain      | [jonathan.doe@email.com](mailto:jonathan.doe@email.com) vs. [j.doe@email.com](mailto:j.doe@email.com)               |
| **0–0.49**    | No Match — different name and domain                    | [jonathan.doe@email.com](mailto:jonathan.doe@email.com) vs. [airbud@petco.com](mailto:airbud@petco.com)             |

<Note>
  The `email` field returns `null` when the financial institution does not provide email data. This is expected and does not affect other field scores.
</Note>

For full endpoint details, request/response parameters, and the interactive API playground, see the [/FieldMatch API reference](/api/utilities/identity/field-match).

## Testing on Toolbox

Five test users are available on the `toolbox` instance, each calibrated to produce a specific match score range.

### Test users

| Username          | Holder Name (FI-side) | Postal Code (FI-side) | Expected Score Range       |
| :---------------- | :-------------------- | :-------------------- | :------------------------- |
| `field_match_100` | Jonathan Doe          | M6N4H9                | **1.0** — Exact Match      |
| `field_match_080` | John Doe              | M6N 4H9A              | 0.80–0.99 — Strong Match   |
| `field_match_065` | Jon Do                | M6N4H1                | 0.65–0.79 — Possible Match |
| `field_match_050` | Steve Doe             | M6N2H8                | 0.50–0.64 — Unlikely Match |
| `field_match_000` | Air Bud               | K7L3R67               | 0–0.49 — No Match          |

### Step 1 — Connect a test user via Flinks Connect

Open the toolbox iframe:

```
https://toolbox-iframe.private.fin.ag/v2/?demo=true
```

Select **FlinksCapital** as the institution. Log in using the test user's username with the `_nomfa` suffix and `Everyday` as the password (e.g., `field_match_100_nomfa` / `Everyday`). Capture the `loginId` from the postMessage event:

```javascript theme={null}
window.addEventListener('message', function(e) {
  if (e.data.step === 'REDIRECT') {
    const loginId = e.data.loginId;
  }
});
```

### Step 2 — Call /FieldMatch with standard reference inputs

Use these inputs across all 5 users. The score difference comes from account-side data, not from the inputs you provide.

```json theme={null}
POST https://toolbox-api.private.fin.ag/v3/{customerId}/BankingServices/FieldMatch
Content-Type: application/json
x-api-key: {your-x-api-key}

{
  "loginId": "<loginId>",
  "fullName": "Jonathan Doe",
  "postalCode": "M6N4H9",
  "phone": "4161234567",
  "email": "jonathan.doe@email.com",
  "civicAddress": "6133 University Blvd",
  "city": "Toronto",
  "province": "ON",
  "threshold": 0.8
}
```

| Test User         | Threshold |
| :---------------- | :-------- |
| `field_match_100` | `1.0`     |
| `field_match_080` | `0.8`     |
| `field_match_065` | `0.65`    |
| `field_match_050` | `0.5`     |
| `field_match_000` | `0.0`     |

### Step 3 — Validate the response

Compare `overallMatchRate` and `fieldLevelMatchRate` against the expected ranges in the scenarios below.

## Test scenarios

### Scenario 1 — Exact Match (field\_match\_100)

| Field        | API Input                                               | FI-side Value                                           | Difference |
| :----------- | :------------------------------------------------------ | :------------------------------------------------------ | :--------- |
| fullName     | Jonathan Doe                                            | Jonathan Doe                                            | —          |
| postalCode   | M6N4H9                                                  | M6N4H9                                                  | —          |
| phone        | 4161234567                                              | 4161234567                                              | —          |
| email        | [jonathan.doe@email.com](mailto:jonathan.doe@email.com) | [jonathan.doe@email.com](mailto:jonathan.doe@email.com) | —          |
| civicAddress | 6133 University Blvd                                    | 6133 University Blvd                                    | —          |
| city         | Toronto                                                 | Toronto                                                 | —          |
| province     | ON                                                      | ON                                                      | —          |

**Threshold**: `1.0` — `overallMatch: true` only when all fields are an exact match.

```json 200 Response theme={null}
{
  "overallMatch": true,
  "overallMatchRate": 1.0,
  "fieldLevelMatchRate": {
    "fullName": 1.0, "phone": 1.0, "email": 1.0,
    "civicAddress": 1.0, "city": 1.0, "province": 1.0,
    "postalCode": 1.0, "noData": []
  }
}
```

### Scenario 2 — Strong Match (field\_match\_080)

| Field        | API Input                                               | FI-side Value                                           | Difference                          |
| :----------- | :------------------------------------------------------ | :------------------------------------------------------ | :---------------------------------- |
| fullName     | Jonathan Doe                                            | John Doe                                                | Shortened first name                |
| postalCode   | M6N4H9                                                  | M6N 4H9A                                                | Format difference + extra character |
| phone        | 4161234567                                              | 416-123-4567                                            | Same number, different format       |
| email        | [jonathan.doe@email.com](mailto:jonathan.doe@email.com) | [jonathan.doe@gmail.com](mailto:jonathan.doe@gmail.com) | Different domain                    |
| civicAddress | 6133 University Blvd                                    | 6133 University Boulevard                               | Street type written in full         |
| city         | Toronto                                                 | Toronto                                                 | —                                   |
| province     | ON                                                      | ON                                                      | —                                   |

**Threshold**: `0.8` — `overallMatch: true` when the overall score meets or exceeds 0.8.

```json 200 Response theme={null}
{
  "overallMatch": true,
  "overallMatchRate": 0.9242857,
  "fieldLevelMatchRate": {
    "fullName": 0.8, "phone": 1.0, "email": 0.81,
    "civicAddress": 0.94, "city": 1.0, "province": 1.0,
    "postalCode": 0.92, "noData": []
  }
}
```

### Scenario 3 — Possible Match (field\_match\_065)

| Field        | API Input                                               | FI-side Value                                         | Difference               |
| :----------- | :------------------------------------------------------ | :---------------------------------------------------- | :----------------------- |
| fullName     | Jonathan Doe                                            | Jon Do                                                | Two characters missing   |
| postalCode   | M6N4H9                                                  | M6N4H1                                                | Last character different |
| phone        | 4161234567                                              | 4161234560                                            | Last digit different     |
| email        | [jonathan.doe@email.com](mailto:jonathan.doe@email.com) | [jonathan.doe@email.ca](mailto:jonathan.doe@email.ca) | Different TLD            |
| civicAddress | 6133 University Blvd                                    | 6133 University Ave                                   | Different street type    |
| city         | Toronto                                                 | Toronto                                               | —                        |
| province     | ON                                                      | ON                                                    | —                        |

**Threshold**: `0.65`

```json 200 Response theme={null}
{
  "overallMatch": true,
  "overallMatchRate": 0.9071429,
  "fieldLevelMatchRate": {
    "fullName": 0.74, "phone": 0.9, "email": 0.95,
    "civicAddress": 0.93, "city": 1.0, "province": 1.0,
    "postalCode": 0.83, "noData": []
  }
}
```

### Scenario 4 — Unlikely Match (field\_match\_050)

| Field        | API Input                                               | FI-side Value                                         | Difference                    |
| :----------- | :------------------------------------------------------ | :---------------------------------------------------- | :---------------------------- |
| fullName     | Jonathan Doe                                            | Steve Doe                                             | Different first name          |
| postalCode   | M6N4H9                                                  | M6N2H8                                                | Multiple characters different |
| phone        | 4161234567                                              | 4165559999                                            | Multiple digits different     |
| email        | [jonathan.doe@email.com](mailto:jonathan.doe@email.com) | [steve.doe@outlook.com](mailto:steve.doe@outlook.com) | Different name and domain     |
| civicAddress | 6133 University Blvd                                    | 100 King St W                                         | Completely different address  |
| city         | Toronto                                                 | Toronto                                               | —                             |
| province     | ON                                                      | ON                                                    | —                             |

**Threshold**: `0.5`

```json 200 Response theme={null}
{
  "overallMatch": true,
  "overallMatchRate": 0.6142857,
  "fieldLevelMatchRate": {
    "fullName": 0.5, "phone": 0.4, "email": 0.46,
    "civicAddress": 0.27, "city": 1.0, "province": 1.0,
    "postalCode": 0.67, "noData": []
  }
}
```

### Scenario 5 — No Match (field\_match\_000)

| Field        | API Input                                               | FI-side Value                               | Difference                     |
| :----------- | :------------------------------------------------------ | :------------------------------------------ | :----------------------------- |
| fullName     | Jonathan Doe                                            | Air Bud                                     | No common factors              |
| postalCode   | M6N4H9                                                  | K7L3R67                                     | Completely different           |
| phone        | 4161234567                                              | 6139876543                                  | Different area code and number |
| email        | [jonathan.doe@email.com](mailto:jonathan.doe@email.com) | [airbud@petco.com](mailto:airbud@petco.com) | No common factors              |
| civicAddress | 6133 University Blvd                                    | 42 Maple Dr                                 | Completely different           |
| city         | Toronto                                                 | Kingston                                    | Different city                 |
| province     | ON                                                      | QC                                          | Different province             |

**Threshold**: `0.0`

```json 200 Response theme={null}
{
  "overallMatch": true,
  "overallMatchRate": 0.22571428,
  "fieldLevelMatchRate": {
    "fullName": 0.11, "phone": 0.4, "email": 0.42,
    "civicAddress": 0.10, "city": 0.40, "province": 0.0,
    "postalCode": 0.15, "noData": []
  }
}
```

## Quick reference

### Toolbox test users

| Username          | Login                   | Password   | Threshold | Expected overallMatchRate |
| :---------------- | :---------------------- | :--------- | :-------- | :------------------------ |
| `field_match_100` | `field_match_100_nomfa` | `Everyday` | `1.0`     | 1.0                       |
| `field_match_080` | `field_match_080_nomfa` | `Everyday` | `0.8`     | \~0.92                    |
| `field_match_065` | `field_match_065_nomfa` | `Everyday` | `0.65`    | \~0.91                    |
| `field_match_050` | `field_match_050_nomfa` | `Everyday` | `0.5`     | \~0.61                    |
| `field_match_000` | `field_match_000_nomfa` | `Everyday` | `0.0`     | \~0.23                    |

### Key notes

* The `email` field returns `null` when the financial institution does not provide email data — this is expected and does not indicate an error.
* Fields included in the request but with no available account data will return `0` and appear in the `noData` array.
* The `threshold` parameter is optional. Without it, only `fieldLevelMatchRate` decimal scores are returned — no `overallMatch` boolean.
* Match scores use fuzzy string matching and may vary slightly by algorithm version. Use the ranges above as guidance, not exact expected values.