Skip to main content
The /FieldMatch 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 linking
  • 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

  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

RangeDescriptionExample
1.0Exact MatchJonathan Doe vs. Jonathan Doe
0.80–0.99Strong Match — spelling error, nickname, or alternative spellingJonathan Doe vs. John Doe
0.65–0.79Possible Match — alias or multiple small discrepanciesJohn Doe vs. Jon Do
0.50–0.64Unlikely Match — could indicate a relative or shared last nameJonathan Doe vs. Steve Doe
0–0.49No Match — no common factorsJonathan Doe vs. Air Bud

​
Postal code

RangeDescriptionExample
1.0Exact MatchM6N4H9 vs. M6N4H9
0.80–0.99Strong Match — format difference or extra charactersM6N4H9 vs. M6N 4H9A
0.65–0.79Possible Match — one number or letter does not matchM6N4H9 vs. M6N4H1
0.50–0.64Unlikely Match — multiple characters do not matchM6N4H9 vs. M6N2H8
0–0.49No Match — no common factorsM6N4H9 vs. K7L3R67

​
Phone

RangeDescriptionExample
1.0Exact Match — including same number in different formats4161234567 vs. 416-123-4567
0.80–0.99Strong Match — one digit different4161234567 vs. 4161234560
0–0.49No Match — multiple digits or area code different4161234567 vs. 4165559999

​
Civic address

RangeDescriptionExample
1.0Exact Match6133 University Blvd vs. 6133 University Blvd
0.80–0.99Strong Match — abbreviated vs. full street type6133 University Blvd vs. 6133 University Boulevard
0.65–0.79Possible Match — different street type, same number and name6133 University Blvd vs. 6133 University Ave
0–0.49No Match — different street number or street entirely6133 University Blvd vs. 100 King St W

​
City

RangeDescriptionExample
1.0Exact MatchToronto vs. Toronto
0–0.49No Match — different cityToronto vs. Kingston

​
Province

RangeDescriptionExample
1.0Exact MatchON vs. ON
0–0.49No Match — different provinceON vs. QC

​
Email

RangeDescriptionExample
1.0Exact Matchjonathan.doe@email.com vs. jonathan.doe@email.com
0.80–0.99Strong Match — different domain or minor name variationjonathan.doe@email.com vs. jonathan.doe@gmail.com
0.65–0.79Possible Match — shortened local part, same domainjonathan.doe@email.com vs. j.doe@email.com
0–0.49No Match — different name and domainjonathan.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

UsernameHolder Name (FI-side)Postal Code (FI-side)Expected Score Range
field_match_100Jonathan DoeM6N4H91.0 — Exact Match
field_match_080John DoeM6N 4H9A0.80–0.99 — Strong Match
field_match_065Jon DoM6N4H10.65–0.79 — Possible Match
field_match_050Steve DoeM6N2H80.50–0.64 — Unlikely Match
field_match_000Air BudK7L3R670–0.49 — No Match
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 UserThreshold
field_match_1001.0
field_match_0800.8
field_match_0650.65
field_match_0500.5
field_match_0000.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)

FieldAPI InputFI-side ValueDifference
fullNameJonathan DoeJonathan Doe—
postalCodeM6N4H9M6N4H9—
phone41612345674161234567—
emailjonathan.doe@email.comjonathan.doe@email.com—
civicAddress6133 University Blvd6133 University Blvd—
cityTorontoToronto—
provinceONON—
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)

FieldAPI InputFI-side ValueDifference
fullNameJonathan DoeJohn DoeShortened first name
postalCodeM6N4H9M6N 4H9AFormat difference + extra character
phone4161234567416-123-4567Same number, different format
emailjonathan.doe@email.comjonathan.doe@gmail.comDifferent domain
civicAddress6133 University Blvd6133 University BoulevardStreet type written in full
cityTorontoToronto—
provinceONON—
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)

FieldAPI InputFI-side ValueDifference
fullNameJonathan DoeJon DoTwo characters missing
postalCodeM6N4H9M6N4H1Last character different
phone41612345674161234560Last digit different
emailjonathan.doe@email.comjonathan.doe@email.caDifferent TLD
civicAddress6133 University Blvd6133 University AveDifferent street type
cityTorontoToronto—
provinceONON—
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)

FieldAPI InputFI-side ValueDifference
fullNameJonathan DoeSteve DoeDifferent first name
postalCodeM6N4H9M6N2H8Multiple characters different
phone41612345674165559999Multiple digits different
emailjonathan.doe@email.comsteve.doe@outlook.comDifferent name and domain
civicAddress6133 University Blvd100 King St WCompletely different address
cityTorontoToronto—
provinceONON—
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)

FieldAPI InputFI-side ValueDifference
fullNameJonathan DoeAir BudNo common factors
postalCodeM6N4H9K7L3R67Completely different
phone41612345676139876543Different area code and number
emailjonathan.doe@email.comairbud@petco.comNo common factors
civicAddress6133 University Blvd42 Maple DrCompletely different
cityTorontoKingstonDifferent city
provinceONQCDifferent 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

UsernameLoginPasswordThresholdExpected overallMatchRate
field_match_100field_match_100_nomfaEveryday1.01.0
field_match_080field_match_080_nomfaEveryday0.8~0.92
field_match_065field_match_065_nomfaEveryday0.65~0.91
field_match_050field_match_050_nomfaEveryday0.5~0.61
field_match_000field_match_000_nomfaEveryday0.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.