Get Bank Account IBAN Verification results via Webhooks

Webhooks provide an efficient way to get notified when a Bank Account IBAN Verification has been completed, and to retrieve the related verification results.
For more details on setting up and managing Webhooks, please refer to this dedicated section.

To receive those notifications, subscribe to the following event:

Event	Description
`verification.bank_account_lookup.done`	Triggered when a bank account verification is complete

Example Webhook Payload for a verified Bank Account IBAN Verification:

{
    "event_id": "57ec86c3-23b4-4720-aaf6-535e46347a94",
    "event_name": "verification.bank_account_lookup.done",
    "event_time": "1348177752",
    "subscription_id": "d09f0367-d80a-309c-a2ed-7083991fc564",
    "subscription_description": "A great webhook",
    "sandbox": false,
    "data": {
        "bank_account_lookup": {
            "id": "dd507dfa-cac6-48be-ae5e-0754b552e96b",
            "workspace_id": "090b4f7e-25e8-423d-9387-741f6188ba7a",
            "workflow_session_id": null,
            "previous_attempt_id": null,
            "applicant_id": null,
            "created_at": "2025-03-24T13:32:26+00:00",
            "updated_at": "2025-03-24T13:32:46+00:00",
            "status": "verified",
            "status_codes": [],
            "data_anonymized": false,
            "data": {
                "extracted_from_document": null,
                "account_holder": null
            }
        }
    }
}

For more information on the statuses and error codes, refer to this section.

Retrieve detailed Bank Account IBAN Verification results

You can also obtain detailed verification results by calling a dedicated endpoint, with the id returned when requesting a Bank Account IBAN Verification:

GET /verifications/bank_account_lookups/{id}

{
    "id": "dd507dfa-cac6-48be-ae5e-0754b552e96b",
    "workspace_id": "090b4f7e-25e8-423d-9387-741f6188ba7a",
    "workflow_session_id": null,
    "previous_attempt_id": null,
    "applicant_id": null,
    "created_at": "2025-03-24T13:32:26+00:00",
    "updated_at": "2025-03-24T13:32:46+00:00",
    "status": "failed",
    "status_codes": [
        "BALV_1330"
    ],
    "data_anonymized": false,
    "data": {
        "extracted_from_document": null,
        "account_holder": "John P Waldo"
    }
}

Similar to the webhook, you will receive the verification status and any associated error codes if the verification was not verified. For more information on the statuses and error codes, refer to this section.

Response fields

Field	Type	Description
`status`	string	Status of the verification. See Follow Bank Account IBAN Verification status.
`status_codes`	array	Indicates the cause when the status is `failed` or `inconclusive`.
`data_anonymized`	boolean	When `true`, every field under `data` is set to `null`.
`data.extracted_from_document.iban`	string	The IBAN read from the document, when the verification was initiated with a file. `null` when the IBAN was submitted directly.
`data.account_holder`	string	The account holder name as the bank holds it. Best effort — the bank does not always disclose it. See When is `account_holder` returned? below.

When is `account_holder` returned?

Whether the bank discloses the name it holds depends on the type of the expected holder and on how closely the name matched.

Expected holder	Status code	`data.account_holder`
Natural person	`BALV_1330` — close match	Returned when the bank discloses it
Natural person	`BALV_1103` — no match	Never returned: the scheme does not disclose an individual's name on a no match
Legal person	`BALV_1330` — close match	Returned when the bank discloses it
Legal person	`BALV_1103` — no match	May be returned: the bank can still disclose the company name it holds

In every case the disclosure is best effort — the bank is never obliged to return the name.

List all Bank Account IBAN Verification requests

To retrieve a list of all verification requests, you can call the following endpoint. You can filter by status or paginate the results based on your needs:

GET /verifications/bank_account_lookups

{
    "meta": {
        "next_cursor": null
    },
    "data": [
        {
            "id": "8222ffef-99ef-4b1f-9a1d-013389866974",
            "workspace_id": "090b4f7e-25e8-423d-9387-741f6188ba7a",
            "workflow_session_id": null,
            "previous_attempt_id": null,
            "applicant_id": null,
            "created_at": "2025-01-28T15:32:55+00:00",
            "updated_at": "2025-01-28T15:33:15+00:00",
            "status": "failed",
            "status_codes": [
                "BALV_1103"
            ],
            "data_anonymized": false
        }
    ]
}

Get Bank Account IBAN Verification results via Webhooks

Retrieve detailed Bank Account IBAN Verification results

Response fields

When is account_holder returned?

List all Bank Account IBAN Verification requests

When is `account_holder` returned?