⚠️

Geographic Limitation

This API is at the moment available only for Spanish IBANs and NIF/NIEs.

Devengo Account Holder Verifications API allows you to confirm that a Spanish NIF/NIE 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 '{
      "recipient": "Devengo S.L"",
      "taxid": "B88353412",
      "destination": {
          "type": "iban",
          "iban": "ES3969400001150000000001"
      }
}'

You will get a response with this structure:

{
  "holder_verification": {
    "id": "vhv_2KX8KGkSUMr37APZsRb2l2",
    "counterparty": {
      "name": "Devengo S.L",
      "taxid": "B88353412",
      "account": {
        "identifiers": [
          {
            "type": "iban",
            "iban": "ES3969400001150000000001"
          }
        ],
        "bank": {
          "name": "Devengo",
          "bic": "DEVNESM2XXX"
        }
      }
    },
    "status": "created",
    "company_reference": null,
    "metadata": {},
    "response": null,
    "fee": {
      "cents": 0,
      "currency": "EUR"
    },
    "created_at": "2025-06-21T09:14:05Z",
    "error": null
  }
}

Result of the verification

Once we receive the verification response from the counterparty's financial institution, we will update the status to the corresponding value:

• confirmed if the counterparty is the legal account holder.
• failed if the counterparty is not the legal account holder.
• rejected if the legal holder of the provided account can't be verified (e.g. because the account does not exist, has been closed, etc.).

📘

Sandbox Testing

Please note that in the Sandbox environment:

• All verifications for the IBAN ES8569400001100000000000 will become rejected
• Verifications for any other IBAN will be processed.
• Using the counterparty identifier B88353412 will return a confirmed verification
• Any other counterparty identifier will return a failed verification.

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.
• Create a webhook.