---
updatedAt: 2026-06-29T16:19:25.000Z
agentTools:
  projectIndex: https://docs.truelayer.com/llms.txt
---

# Account holder verification

To verify an account holder, submit their name, sort code, and account number via a POST request, then check the verification status with a GET request.

When you make a payout, an account holder verification check is performed on the beneficiary. In this process, the beneficiary’s name and account identifiers (sort code and account number) are checked against what is on file at the bank.

## Make an account holder verification request

To verify a specific account holder, you need:

* An account holder name
* A sort code and account number, or an IBAN
* A valid access token with the scope `verification`.

<Callout icon="📘" theme="info">
  ###

  To enable the `verification` scope for account holder verification requests, contact us.
</Callout>

Make a POST request to the [/v3/account-holder-verifications/requests](https://docs.truelayer.com/reference/create-account-holder-verification) endpoint with this information:

```json Example with SCAN
{
  "account_holder_name": "John Doe",
  "account_identifier": {
	  "type": "sort_code_account_number",
    "sort_code": "123456",
    "account_number": "12345678"
  }
}
```
```json Example with IBAN
{
  "account_holder_name": "John Doe",
  "account_identifier": {
	  "type": "iban",
    "iban": "FR7630006000011234567890189"
}
```

In the API response, you receive an `id` for the request.

```json Example response
{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
```

You do not receive any information on the status of the verification check in the response. To find out the result of the check, you need to make a GET request to the same endpoint, using the `id` you received in the response.

## Monitor an account holder verification check

When you make an account holder verification check, it can have one of the following results:

* Account holder verification is complete and the result was `match`
* Account holder verification is complete and the result was `partial_match` , which also includes the account holder name
* Account holder verification is complete and the result was `no_match`
* Account holder verification is complete and the result was `match_not_possible`, which also includes a failure reason in plain English
* The verification attempt failed.

Normally, the verification process takes a few seconds.

## GET account holder verification

To see the status of a particular check, you can make a GET request to the [/v3/account-holder-verifications/requests/{id}](https://docs.truelayer.com/reference/get-account-holder-verification) endpoint (where `id` is the ID of the request that you created earlier).

```json Pending example
{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "status": "pending"
}
```
```json Match example
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "match_result": {
    "type": "match"
  }
}
```
```json No_match example
{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "status": "completed",
  "match_result": {
    "type": "no_match"
  }
}
```

The response will contain:

* the `id` of the verification request<br />You already submitted this in the previous step.
* the `status` of the request<br />This can be `pending`, `complete` or `failed`.
* the `result` of the check, if the check is completed or failed<br />This can be `match`, `partial_match`, `no_match` or `match_not_possible`.

If you receive a `partial_match` result, you also receive the account holder’s name in the response, so you can decide whether to move forward with the payout:

```json Partial_match example
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "completed",
  "match_result": {
    "type": "partial_match",
    "account_holder_name": "Jean D."
  }
}
```

If you receive a `match_not_possible` or `failed` response, you also receive a failure reason with information on why verification failed:

```json Match_not_possible example
{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "status": "completed",
  "match_result": {
    "type": "match_not_possible",
    "failure_reason": "Bank unable to match"
  }
}
```
```json Failed example
{
  "id": "550e8400-e29b-41d4-a716-446655440004",
  "status": "failed",
  "failure_reason": "provider_error"
}
```

If you receive a `failed` webhook or response to a GET request, we recommend retrying the check.

## Webhooks

To set up webhooks for account holder verification, contact us. You won't be able to set up account holder verification webhooks in Console.

```json Match example
{
  "type": "account_holder_verification_completed",
  "event_version": 1,
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "account_holder_verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "match_result": {
    "type": "match"
  }
}
```
```json No match example
{
  "type": "account_holder_verification_completed",
  "event_version": 1,
  "event_id": "e2g7ggc3-h25f-74g7-d049-7798h8e77263",
  "account_holder_verification_id": "880h1733-h5ce-74h7-e049-7798h8e77263",
  "match_result": {
    "type": "no_match"
  }
}
```
```json Partial match example
{
  "type": "account_holder_verification_completed",
  "event_version": 1,
  "event_id": "d1f6ffb2-g14e-63f6-c938-6687g7d66152",
  "account_holder_verification_id": "770g0622-g4bd-63g6-d938-6687g7d66152",
  "match_result": {
    "type": "partial_match",
    "account_holder_name": "J Smith"
  }
}
```
```json Verification failed example
{
  "type": "account_holder_verification_failed",
  "event_version": 1,
  "event_id": "c9e5eeb1-f03d-52e5-b827-5576f6c55041",
  "account_holder_verification_id": "660f9511-f3ac-52f5-c827-5576f6c55041",
  "failure_reason": "provider_error"
}
```
```json Match_not_possible example
{
  "type": "account_holder_verification_completed",
  "event_version": 1,
  "event_id": "e2g7ggc3-h25f-74g7-d049-7798h8e77263",
  "account_holder_verification_id": "880h1733-h5ce-74h7-e049-7798h8e77263",
  "match_result": {
    "type": "match_not_possible",
    "failure_reason": "Bank unable to match"
  }
}
```

##

## Test account holder verification in sandbox

We recommend that you test account holder verification endpoints in our sandbox environment (`https://api.truelayer-sandbox.com`) as part of your integration.

Use the data in the table below to test specific scenarios, including different failure reasons. Where you see ANY\_IBAN for the`iban` value, substitute any valid IBAN.

For ANY\_NAME, substitute any name **except those that would produce a different, specific result** (so don’t use `John Doe`, `John partial`, `John impossiblematch` or `John pspfail` for this field).

When you make a request to the POST endpoint, you receive an AHV\_ID value. This is an identifier for the specific verification check that you've just done.

Then, to confirm the result of each of these test scenarios, call the **GET account holder verification** endpoint. Include the AHV\_ID in the endpoint URL. Depending on the result of the verification check, you receive a different outcome when calling the GET endpoint.

**POST** Request endpoint: `https://https://api.truelayer-sandbox.com/v3/account-holder-verifications/requests`

**GET** Response endpoint: `https://https://api.truelayer-sandbox.com/v3/account-holder-verifications/requests/{{AHV_ID}}`

| POST Request body                                                                                                                                         | Status of verification check | Match result received |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------- | :-------------------- |
| `{       "account_holder_name": "John Doe",       "account_identifier": {           "type": "iban",           "iban": "ANY_IBAN"       }   }`             | Completed                    | Match                 |
| `{       "account_holder_name": "ANY_NAME",       "account_identifier": {           "type": "iban",           "iban": "ANY_IBAN"       }   }`             | Completed                    | No Match              |
| `{       "account_holder_name": "John partial",       "account_identifier": {           "type": "iban",           "iban": "ANY_IBAN"       }   }`         | Completed                    | Partial Match         |
| `{       "account_holder_name": "John impossiblematch",       "account_identifier": {           "type": "iban",           "iban": "ANY_IBAN"       }   }` | Completed                    | Match Not Possible    |
| `{       "account_holder_name": "John pspfail",       "account_identifier": {           "type": "iban",           "iban": "ANY_IBAN"       }   }`         | Failed                       | N/A                   |

Below are the GET responses that you receive for each match result.

| Match result                                           | GET response                                                                                                                                                                                                |
| :----------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Match                                                  | `{       "id": "4c7d28cb-20be-40a3-a952-07cdd6e628b2",       "status": "completed",       "match_result": {           "type": "match"       }   }`                                                          |
| No match                                               | `{       "id": "38118169-8384-4091-9aef-c41127eead62",       "status": "completed",       "match_result": {           "type": "no_match"       }   }`                                                       |
| Partial match                                          | `{       "id": "942e66b7-6e1a-4cbe-9a11-8d322ea1207b",       "status": "completed",       "match_result": {           "type": "partial_match",           "account_holder_name": "John Doe"       }   }`     |
| Match not possible                                     | `{       "id": "ac0f5311-55ba-4284-8097-69ca58eaacd9",       "status": "completed",       "match_result": {           "type": "match_not_possible",           "reason": "Bank unable to match"       }   }` |
| No match result, because the verification check failed | `{       "id": "408b1b61-dd41-432c-b480-c48f88186c4a",       "status": "failed",       "failure_reason": "VOP scheme provider error"   }`                                                                   |

<br />