How to use Name Verification

This endpoint is available only for connected retail bank accounts.

Overview

The Verify Name API lets you confirm that a customer's provided name matches the name retrieved from their connected bank account. This verification helps reduce fraud and ensures that the connect accounts belongs to the customer you’ve onboarded.

⚠️

Note: This API currently supports retail bank accounts only (corporate account support is not available).


How It Works

The API compares the full_name you submit with the name on the bank account linked via the provided entity_id. The response includes:

  • The original and retrieved names
  • Match type (PERFECT_MATCH, PARTIAL_MATCH, NO_MATCH)
  • A confidence score
  • Session status (e.g. RECONNECT_REQUIRED if expired)

You must first create a customer and entity before using this endpoint, read the Getting Started with Data guide to learn how to do this.


Endpoint

POST /insights/v1/name-verification

Authentication: All production requests require mutual TLS (mTLS).

Environments: Available in both sandbox and production.


Request Schema

FieldTypeRequiredDescription
entity_idstringYesThe entity ID representing the user’s bank connection.
full_namestringYesThe name you wish to verify. Must meet the constraints below.
asyncbooleanOptionalWhether the API call should run asynchronously. Defaults to false.

full_name Constraints

Your full_name input must satisfy the following:

  • Minimum of 2 characters
  • Must contain at least two words
  • Can include the following characters: A–Z, a–z, ', ,, ., , and whitespace
  • Cannot include numbers or unsupported symbols
  • Example valid full names; Fatima Al-Mansoori ,Mohammed A. Khan,Jean-Pierre Dupont

Example Request

bash
CopyEdit
curl -X POST 'https://sandbox.leantech.me/insights/v1/name-verification' \
  --header 'Content-Type: application/json' \
  --header 'lean-app-token: YOUR_APP_TOKEN' \
  --data-raw '{
      "entity_id": "f08fb010-878f-407a-9ac2-a7840fb56185",
      "full_name": "Michael Garry Scott",
      "async": false
  }'

Response Examples

PERFECT_MATCH

{
  "status": "OK",
  "payload": {
    "full_name_provided": "Michael Garry Scott",
    "full_name_retrieved": "Michael Garry Scott",
    "match_type": "PERFECT_MATCH",
    "confidence": 1.0
  }
}

PARTIAL_MATCH

{
  "status": "OK",
  "payload": {
    "full_name_provided": "Michael G Scott",
    "full_name_retrieved": "Michael Garry Scott",
    "match_type": "PARTIAL_MATCH",
    "confidence": 0.87
  }
}

NO_MATCH

{
  "status": "OK",
  "payload": {
    "full_name_provided": "John Doe",
    "full_name_retrieved": "Michael Garry Scott",
    "match_type": "NO_MATCH",
    "confidence": 0.15
  }
}

RECONNECT_REQUIRED

Returned when the user’s bank session has expired or been revoked. In this case you will need to implement the reconnect flow (for a user to reconnect their account).

{
    "status": "RECONNECT_REQUIRED",
    "payload": {
        "reconnect_id": "1ab6f281-b021-4309-b181-d8341fae3242",
        "type": "reconnect"
    },
    "results_id": "1ab6f281-b021-4309-b181-d8341fae3242",
    "message": "User input is required to reconnect with the bank",
    "meta": {},
    "timestamp": "2025-07-01T14:22:10.534027328Z",
    "type": null,
    "status_detail": null
}

Match Types

Match typeMeaningConfidence score
PERFECT_MATCHNames are identical, character-for-character.1
PARTIAL_MATCHClose match, e.g. nicknames, abbreviations, spelling variants.0.7 and above, but below 1
NO_MATCHNo meaningful similarity.Less than 0.7
RECONNECT_REQUIREDSession is invalid or expired. User must reconnectN/A