How to use Name Verification

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

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