Field Match API — Guide & Testing Reference

Modified on Fri, 13 Mar at 8:15 PM

Topic: Identity Verification | Product: Flinks Connect | Effort: Requires a valid loginId and x-api-key

Overview: The /FieldMatchendpoint compares identity data you submit against financial data parsed from a connected bank account. Scores are returned per field (0–1) and as an overall match rate. Common use cases:

Confirm account ownership before linking a bank account to a financial service
Verify customer identity during onboarding
Detect discrepancies between submitted and actual account data

In this article

#	Section	What you'll find
1	Match Score Reference	Score ranges for all 7 identity fields
2	API Reference	Endpoint, authentication, request parameters, and response structure
3	Testing on Toolbox	Step-by-step test flow using the 5 preconfigured toolbox users
4	Test Scenarios	Per-user field comparisons and actual API responses for each score range
5	Quick Reference: Key Parameters	Parameter guide, test user credentials, and rate limit notes
6	Related Resources	Links to API docs, guides, and support

Match Score Reference

Scores are calculated using fuzzy string matching. Use the ranges below as guidance when interpreting results.

Name

Range	Meaning	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	Meaning	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	Meaning	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.65–0.79	—	—
0.50–0.64	—	—
0–0.49	No Match — multiple digits or area code different	4161234567 vs. 4165559999

Civic Address

Range	Meaning	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.50–0.64	—	—
0–0.49	No Match — different street number or street entirely	6133 University Blvd vs. 100 King St W

City

Range	Meaning	Example
1.0	Exact Match	Toronto vs. Toronto
0.80–0.99	—	—
0.65–0.79	—	—
0.50–0.64	—	—
0–0.49	No Match — different city	Toronto vs. Kingston

Province

Range	Meaning	Example
1.0	Exact Match	ON vs. ON
0.80–0.99	—	—
0.65–0.79	—	—
0.50–0.64	—	—
0–0.49	No Match — different province	ON vs. QC

Email

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

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

API Reference

Endpoint

POST /v3/{customerId}/BankingServices/FieldMatch

Base URL: https://{instance}-api.private.fin.ag

Replace {instance} with your environment: toolbox, sandbox, or your production instance name.

Authentication

x-api-key: {your-x-api-key}

Pass your API Secret in the x-api-key header. The /FieldMatch endpoint does not require a session token — no prior call to /Authorize is needed.

Request Body Parameters

Parameter	Type	Description
`loginId`	string	Obtained from a successful account connection
`fullName`	string	Full name (alternative to firstName / lastName)
`firstName`	string	First name
`lastName`	string	Last name
`postalCode`	string	Postal code
`civicAddress`	string	Street address
`city`	string	City
`province`	string	Province code (e.g. ON)
`email`	string	Email address
`phone`	string	Phone number
`threshold`	number	Optional. Score threshold (0–1). Enables the `overallMatch` boolean in the response.

✓ Only the fields you include in the request body are evaluated. Fields not included are ignored and will not appear in the response.

Response Fields

Field	Type	Description
`overallMatch`	boolean	Whether the overall score meets or exceeds the threshold. Only present when `threshold` is included.
`overallMatchRate`	number	Aggregate match score across all evaluated fields (0–1).
`fieldLevelMatch`	object	Per-field boolean result against the threshold.
`fieldLevelMatchRate`	object	Per-field decimal match scores (0–1).
`noData`	array	Fields requested but with no available account data for comparison.

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

Steps

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": <see table below>
}

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 scenario tables 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	—
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.

Actual API 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
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.

Actual API 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
civicAddress	6133 University Blvd	6133 University Ave	Different street type
city	Toronto	Toronto	—
province	ON	ON	—

Threshold: 0.65

Actual API 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
civicAddress	6133 University Blvd	100 King St W	Completely different address
city	Toronto	Toronto	—
province	ON	ON	—

Threshold: 0.5

Actual API 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
civicAddress	6133 University Blvd	42 Maple Dr	Completely different
city	Toronto	Kingston	Different city
province	ON	QC	Different province

Threshold: 0.0

Actual API response:

{
  "overallMatch": true,
  "overallMatchRate": 0.22571428,
  "fieldLevelMatchRate": {
    "fullName": 0.11, "phone": 0.4, "email": 0.42,
    "civicAddress": 0.1, "city": 0.4, "province": 0.0,
    "postalCode": 0.15, "noData": []
  }
}

Quick Reference: Key Parameters

Request Body Fields

Parameter	Required	Notes
`loginId`	Yes	Obtained from a completed Flinks Connect session. The only field that links the request to a specific bank account.
`threshold`	No	Decimal between 0 and 1. Enables the `overallMatch` boolean in the response.
`fullName`	No	Full name as a single string. Alternative to `firstName` + `lastName`.
`phone`	No	Format-normalized before comparison — `416-123-4567` and `4161234567` both score 1.0.
`email`	No	Returns `null` when the FI does not provide email data. Does not affect other field scores.
`province`	No	Use the 2-letter code (e.g., `ON`). Full name vs. abbreviation may produce a low score.
`civicAddress`	No	Street type abbreviations (Blvd vs. Boulevard) are tolerated at the Strong Match level.

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

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.

Last updated: March 2026 | Maintained by Flinks Technical Account Management

Field Match API — Guide & Testing Reference

Match Score Reference

Name

Postal Code

Phone

Civic Address

City

Province

Email

API Reference

Endpoint

Authentication

Request Body Parameters

Response Fields

Testing on Toolbox

Test Users

Steps

Test Scenarios

Quick Reference: Key Parameters

Request Body Fields

Toolbox Test Users

Notes

Related Resources