ℹ️

Availability

Account Holder Verifications are available for supported bank accounts. Coverage may vary depending on the destination account and the participating financial institution.

Devengo Account Holder Verifications API allows you to verify whether the person or entity identified in your request is the legal account holder of a bank account. This guide will teach you how to create and confirm account holder verifications from start to finish.

Please notice that this service ONLY verifies that a provided person is the legal account holder of the provided IBAN. If you want to verify that a non-account holder (e.g. beneficiary) has access to the IBAN please use our Access Verifications API.

Although the verification occurs just in a few seconds, this is an asynchronous process and we recommend to create a webhook to receive our callbacks to have detailed and realtime control over the process.

Create a Sandbox Account

The first step, unless you are already using other Devengo products, is to create a Sandbox Account. The Sandbox Account allows you to test the functions without using real bank accounts or transactions. To create a Sandbox Account, follow these steps:

1. Create your account by filling out this form.
2. You will receive a confirmation email. Once confirmed, you will have full access to the Devengo API.

Create an API Key

Now that your Sandbox account is ready, you'll need to generate an API key. This key serves as your authentication credential for all requests to the Devengo API.

To generate an API key, navigate to the API Keys section in the Control Panel.

You're now ready to make your first holder verification.

You need to sign every request to authenticate them so learn how to sign them in Authentication.

Create the first Account Holder Verification

Once you have created your API key and learnt how to sign your request for authentication, you can start creating Account Holder Verifications:

curl -X POST https://api.sandbox.devengo.com/v1/holder_verifications \
-H 'Content-Type: application/json' \
-H "X-Devengo-Api-Key-Id: your_api_key_id" \
-H "X-Devengo-Api-Key-Nonce: your_nonce" \
-H "X-Devengo-Api-Key-Timestamp: your_timestamp" \
-H "X-Devengo-Api-Key-Signature: your_signature" \
-d '{
      "name": "Devengo S.L",
      "identifier": {
        "type": "tax_id",
        "value": "B88353412",
        "country_code": "ES"
      },
      "account": {
          "type": "iban",
          "iban": "ES3669409999050000000001"
      }
}'

You will get a response with this structure:

{
  "holder_verification": {
    "id": "vhv_2KX8KGkSUMr37APZsRb2l2",
    "name": "Devengo S.L"",
    "identifier": {
      "type": "tax_id",
      "value": "B88353412",
      "country_code": "ES"
    },
    "account": {
        "type": "iban",
        "iban": "ES3669409999050000000001"
    },
    "status": "created",
    "company_reference": null,
    "metadata": {},
    "response": null,
    "fee": {
      "cents": 0,
      "currency": "EUR"
    },
    "response": {
        "code": "match"
    },
    "verification_attribute": "name",
    "created_at": "2025-06-21T09:14:05Z",
    "error": null
  }
}

Result of the verification

Once we receive the verification response from the destination account's financial institution, we will update the status accordingly:

• confirmed if the information provided in the request matches the legal account holder of the provided account.
• failed if the information provided in the request does not match the legal account holder of the provided account.
• rejected if the legal account holder of the provided account could not be verified.

The verification_attribute field indicates which attribute was used to perform the verification (for example, tax_id or name).

The response field provides additional information about the verification result:

• match when the information provided in the request matches the legal account holder.
• no_match when the information provided in the request does not match the legal account holder.
• close_match when the verification is performed using the provided name and it is considered similar to the legal account holder's name, but not an exact match.

⚠️

close_match is only returned for name-based verifications, and always together with status = confirmed. It indicates that the provided name is sufficiently similar to the legal account holder's name, but not an exact match, so you should evaluate whether this level of similarity is acceptable for your use case.

📘

Sandbox Testing

For information about testing Account Holder Verifications in the Sandbox environment, see our Sandbox test data documentation.

Retrieving an Account Holder Verification

You can always access the state of an account holder verification using the corresponding endpoint:

curl --request GET \
     --url https://api.sandbox.devengo.com/v1/holder_verifications/vhv_2KX8KGkSUMr37APZsRb2l2 \
-H 'Content-Type: application/json' \
-H "X-Devengo-Api-Key-Id: your_api_key_id" \
-H "X-Devengo-Api-Key-Nonce: your_nonce" \
-H "X-Devengo-Api-Key-Timestamp: your_timestamp" \
-H "X-Devengo-Api-Key-Signature: your_signature" \

Next steps

• Understand the lifecycle of an Account Holder Verification.
• Learn about the errors that can occur.
• Create a webhook.