> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ibantrack.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Verify IBAN holder
> Create a new IBAN holder verification request.
## Overview
This endpoint is the core of Ibantrack. It allows you to verify whether the provided name matches the holder of the specified IBAN, in real-time and across the SEPA zone.
The verification is performed synchronously by querying the responding bank.
Use the interactive API playground to test requests directly from this page: Authenticate using your API token, modify request parameters, and inspect real API responses
## Request payload
### Required fields
| Field | Type | Description |
| --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `account.iban` | string | IBAN of the account to be verified. |
| `account_holder.name` | string | Name of the account holder to be verified.
- For individuals: full legal name.
- For businesses: legal business name (company name). |
## Example requests
### Individual — France
```json theme={null}
{
"account": {
"iban": "FR7630004000031234567890143"
},
"account_holder": {
"name": "Jean Dupont"
}
}
```
### Business — Germany
```json theme={null}
{
"account": {
"iban": "DE80500105172521224695"
},
"account_holder": {
"name": "Blue Horizon Travel GmbH"
}
}
```
**Timeout Notice:** Responses typically take 1-3 seconds, but can take up to 10 seconds for some European banks. Set your client timeout accordingly.
## OpenAPI
````yaml POST /account-holder-verifications
openapi: 3.0.0
info:
title: Ibantrack API
description: IBAN account holder verification API
version: 1.0.0
servers:
- url: https://api.ibantrack.com/api-v1
description: Production
security: []
paths:
/account-holder-verifications:
post:
tags:
- Account Holder Verifications
summary: Verify IBAN Holder
description: Verify the name of a bank account holder.
operationId: createAccountHolderVerification
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VerificationRequest'
responses:
'200':
description: Verification completed
content:
application/json:
schema:
$ref: '#/components/schemas/VerificationResponse'
examples:
Match:
$ref: '#/components/examples/MatchResult'
No match:
$ref: '#/components/examples/NoMatchResult'
Close Match:
$ref: '#/components/examples/CloseMatchResult'
Account Not Verifiable:
$ref: '#/components/examples/AccountNotVerifiableResult'
Institution out of scope:
$ref: '#/components/examples/OutOfScope'
'400':
description: Bad Request - The request is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Missing IBAN:
$ref: '#/components/examples/BadRequest'
'401':
description: Unauthorized - Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Invalid Token:
$ref: '#/components/examples/Unauthorized'
'403':
description: Forbidden - Account limits or permissions
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Credit limit reached:
$ref: '#/components/examples/AccessDenied'
security:
- bearerAuth: []
components:
schemas:
VerificationRequest:
type: object
required:
- account
- account_holder
properties:
account:
type: object
additionalProperties: false
required:
- iban
properties:
iban:
type: string
description: IBAN of the account to be verified.
example: FR7630004000031234567890143
account_holder:
type: object
additionalProperties: false
required:
- name
properties:
name:
type: string
description: >-
Name of the account holder to be verified.
- For individuals: full legal name.
- For businesses: legal business name (company name).
Identifiers such as VAT numbers, LEI, SIREN or other national
identifiers must not be provided in this field and will result
in a `no_match` outcome.
example: Jean Dupont
VerificationResponse:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
example: abc123ab-3171-4e97-92ec-a11e9fabc123
status:
type: string
readOnly: true
enum:
- pending
- completed
- failed
description: >-
The current lifecycle state of the verification request.
A `completed` status indicates that the financial institution has been successfully reached and processed the request.
A `failed`status indicates that the verification could not be
completed due to technical or institutional constraints.
Additional details may be provided in the `status_reason` field.
match_result:
type: string
readOnly: true
enum:
- match
- close_match
- no_match
- account_not_verifiable
description: >-
The outcome of the account holder name verification against the
financial institution’s records. Provided only when `status`is
`completed`.
matched_name:
type: string
readOnly: true
example: JEAN DUPONT
description: >-
Indicates the full name or company name as registered by the
financial institution. Provided only if 'match_result' is
'close_match' and in accordance with data privacy regulations.
status_reason:
type: string
readOnly: true
description: >-
Additional context on the request status. Primarily populated when
status is 'failed' or when match_result is 'account_not_verifiable'
example: institution_timeout
enrichment:
type: object
readOnly: true
properties:
status:
type: string
description: >-
Additional data derived from the IBAN. Currently available only
for French IBANs. Not available in sandbox mode.
example: completed
bic_code:
type: object
readOnly: true
properties:
value:
type: string
readOnly: true
example: BNPAFRPPXXX
status:
type: string
readOnly: true
enum:
- pending
- completed
- unavailable
- not_applicable
example: completed
bank_name:
type: object
readOnly: true
properties:
value:
type: string
readOnly: true
example: BNP PARIBAS
status:
type: string
readOnly: true
enum:
- pending
- completed
- unavailable
- not_applicable
example: completed
ErrorResponse:
type: object
properties:
code:
type: string
example: iban_required
message:
type: string
example: The IBAN field is required within account object.
examples:
MatchResult:
summary: Match
value:
id: abc123ab-3171-4e97-92ec-a11e9fabc123
status: completed
match_result: match
NoMatchResult:
summary: No match
value:
id: abc123ab-3171-4e97-92ec-a11e9fabc123
status: completed
match_result: no_match
CloseMatchResult:
summary: Close match
value:
id: abc123ab-3171-4e97-92ec-a11e9fabc123
status: completed
match_result: close_match
matched_name: JEAN DUCLOS
AccountNotVerifiableResult:
summary: Account not verifiable
value:
id: abc123ab-3171-4e97-92ec-a11e9fabc123
status: completed
match_result: account_not_verifiable
status_reason: verification_not_possible
OutOfScope:
summary: Institution out of scope
value:
id: abc123ab-3171-4e97-92ec-a11e9fabc123
status: failed
status_reason: institution_out_of_scope
BadRequest:
summary: Bad request
value:
code: iban_required
message: The IBAN field is required within account object.
Unauthorized:
summary: Unauthorized
value:
code: ERROR_CODE_UNAUTHORIZED
message: This token is expired.
AccessDenied:
summary: Access denied
value:
code: insufficient_credits
message: >-
You have reached your credit limit. Please top up your account to
continue using the service.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````