Field Match API: Guide & Testing Reference

The /FieldMatch endpoint compares identity data you submit against financial data parsed from a connected bank account, returning scores per field (0 to 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.

How it works

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.
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.
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 to 0.99	Strong Match: spelling error, nickname, or alternative spelling	Jonathan Doe vs. John Doe
0.65 to 0.79	Possible Match: alias or multiple small discrepancies	John Doe vs. Jon Do
0.50 to 0.64	Unlikely Match: could indicate a relative or shared last name	Jonathan Doe vs. Steve Doe
0 to 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 to 0.99	Strong Match: format difference or extra characters	M6N4H9 vs. M6N 4H9A
0.65 to 0.79	Possible Match: one number or letter does not match	M6N4H9 vs. M6N4H1
0.50 to 0.64	Unlikely Match: multiple characters do not match	M6N4H9 vs. M6N2H8
0 to 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 to 0.99	Strong Match: one digit different	4161234567 vs. 4161234560
0 to 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 to 0.99	Strong Match: abbreviated vs. full street type	6133 University Blvd vs. 6133 University Boulevard
0.65 to 0.79	Possible Match: different street type, same number and name	6133 University Blvd vs. 6133 University Ave
0 to 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 to 0.49	No Match: different city	Toronto vs. Kingston

Province

Range	Description	Example
1.0	Exact Match	ON vs. ON
0 to 0.49	No Match: different province	ON vs. QC

Email

Range	Description	Example
1.0	Exact Match	jonathan.doe@email.com vs. jonathan.doe@email.com
0.80 to 0.99	Strong Match: different domain or minor name variation	jonathan.doe@email.com vs. jonathan.doe@gmail.com
0.65 to 0.79	Possible Match: shortened local part, same domain	jonathan.doe@email.com vs. j.doe@email.com
0 to 0.49	No Match: different name and domain	jonathan.doe@email.com vs. airbud@petco.com

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

For full endpoint details, request/response parameters, and the interactive API playground, see the /FieldMatch API reference.

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 to 0.99: Strong Match
`field_match_065`	Jon Do	M6N4H1	0.65 to 0.79: Possible Match
`field_match_050`	Steve Doe	M6N2H8	0.50 to 0.64: Unlikely Match
`field_match_000`	Air Bud	K7L3R67	0 to 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:

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.

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	n/a
postalCode	M6N4H9	M6N4H9	n/a
phone	4161234567	4161234567	n/a
email	jonathan.doe@email.com	jonathan.doe@email.com	n/a
civicAddress	6133 University Blvd	6133 University Blvd	n/a
city	Toronto	Toronto	n/a
province	ON	ON	n/a

Threshold: 1.0, overallMatch: true only when all fields are an exact match.

200 Response

{
  "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	jonathan.doe@gmail.com	Different domain
civicAddress	6133 University Blvd	6133 University Boulevard	Street type written in full
city	Toronto	Toronto	n/a
province	ON	ON	n/a

Threshold: 0.8, overallMatch: true when the overall score meets or exceeds 0.8.

200 Response

{
  "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	jonathan.doe@email.ca	Different TLD
civicAddress	6133 University Blvd	6133 University Ave	Different street type
city	Toronto	Toronto	n/a
province	ON	ON	n/a

Threshold: 0.65

200 Response

{
  "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	steve.doe@outlook.com	Different name and domain
civicAddress	6133 University Blvd	100 King St W	Completely different address
city	Toronto	Toronto	n/a
province	ON	ON	n/a

Threshold: 0.5

200 Response

{
  "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	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

200 Response

{
  "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.

Getting Started

AI

Connect

Enrich

Pay

Webhooks

Upload

Dashboard

Outbound

Security

Support

Field Match API: Guide & Testing Reference

How it works

Match score reference

Name

Postal code

Phone

Civic address

City

Province

Email

Testing on Toolbox

Test users

Step 1: Connect a test user via Flinks Connect

Step 2: Call /FieldMatch with standard reference inputs

Step 3: Validate the response

Test scenarios

Scenario 1: Exact Match (field_match_100)

Scenario 2: Strong Match (field_match_080)

Scenario 3: Possible Match (field_match_065)

Scenario 4: Unlikely Match (field_match_050)

Scenario 5: No Match (field_match_000)

Quick reference

Toolbox test users

Key notes

​How it works

​Match score reference

​Name

​Postal code

​Phone

​Civic address

​City

​Province

​Email

​Testing on Toolbox

​Test users

​Step 1: Connect a test user via Flinks Connect

​Step 2: Call /FieldMatch with standard reference inputs

​Step 3: Validate the response

​Test scenarios

​Scenario 1: Exact Match (field_match_100)

​Scenario 2: Strong Match (field_match_080)

​Scenario 3: Possible Match (field_match_065)

​Scenario 4: Unlikely Match (field_match_050)

​Scenario 5: No Match (field_match_000)

​Quick reference

​Toolbox test users

​Key notes

How it works

Match score reference

Name

Postal code

Phone

Civic address

City

Province

Email

Testing on Toolbox

Test users

Step 1: Connect a test user via Flinks Connect

Step 2: Call /FieldMatch with standard reference inputs

Step 3: Validate the response

Test scenarios

Scenario 1: Exact Match (field_match_100)

Scenario 2: Strong Match (field_match_080)

Scenario 3: Possible Match (field_match_065)

Scenario 4: Unlikely Match (field_match_050)

Scenario 5: No Match (field_match_000)

Quick reference

Toolbox test users

Key notes