BVN Verification API Documentation

API Overview

1. How BVN Verification Works

The VerifyDeck BVN Verification API provides an interface for submitting a Bank Verification Number and receiving the verification result.

The integration follows four steps:

1. Collect the BVN: Obtain the applicant's 11-digit BVN.
2. Submit the request: Send the BVN and your internal end_user_id to the verification endpoint from your backend.
3. Receive the response: The API returns the verification result and available identity details.
4. Retrieve a previous verification: Use the verification ID to look up a past verification when needed.

The API does not require an applicant photograph to be uploaded or pre-hosted before submitting a BVN verification request.

2. API Authentication

VerifyDeck authenticates BVN verification requests using an API key.

Your secret API key is displayed once during signup.

Include this key in the X-API-Key HTTP header when making requests.

Authentication Header

X-API-Key: YOUR_API_KEY

Replace YOUR_API_KEY with your VerifyDeck secret API key.

API Key Security

The API is intended for server-to-server integration.

To protect your credentials:

• Store your API key securely on your backend.
• Do not expose the key in frontend JavaScript.
• Do not include the key in publicly accessible repositories.
• Make authenticated API requests from your backend rather than directly from the browser.

Use the HTTPS base URL provided in this documentation for API requests.

3. Verify a Bank Verification Number

POST /verify/bvn

Submit an applicant's BVN for verification and receive the available identity details associated with it.

Endpoint

POST https://api.verifydeck.com/verify/bvn

Request Headers

Request Body Parameters

Example Request Body

{ "end_user_id": "applicant-1", "bvn_number": "22345678901" }

The BVN in this example is a documentation placeholder.

Request Field Descriptions

end_user_id

A string identifying the applicant within your application.

bvn_number

The 11-digit Bank Verification Number submitted for verification.

The API expects this field as a string.

4. BVN Verification Response

HTTP 200 OK

The documented API response contains verification information and available identity details.

Response Fields

Understanding the Response

Verification ID

The verification_id uniquely identifies a verification record. It can be used to retrieve the record through the GET endpoint.

BVN Validation Result

The is_valid field returns a boolean representing the validation result.

Verification Status

The verification_status field returns a string representing the verification status.

Verification Score

The verification_score field returns an integer or null.

The API specification does not define the score range or scoring methodology.

Identity Information

The API response includes fields for the name, date of birth, phone number, and photograph URL associated with the BVN.

These fields are nullable. An integration should therefore allow them to contain null.

Failure Reason

The failure_reason field contains a string or null.

Provider

The provider field identifies the verification provider as a string.

Timestamps

The created_at and updated_at fields contain datetime values associated with the verification record.

5. Retrieve a Previous BVN Verification

GET /verify/bvn/{id}

Retrieve a past BVN verification using its ID.

Endpoint

GET https://api.verifydeck.com/verify/bvn/{id}

Path Parameter

Replace {id} with the verification ID returned by the BVN verification API.

The endpoint requires your secret API key in the X-API-Key header.

6. BVN Verification API Code Examples

Use the following examples to make a BVN verification request from your backend.

curl -X POST https://api.verifydeck.com/verify/bvn \
  -H "X-API-Key: $VERIFYDECK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "end_user_id": "applicant-1",
    "bvn_number": "22345678901"
  }'

const response = await fetch(
  "https://api.verifydeck.com/verify/bvn",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.VERIFYDECK_API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      end_user_id: "applicant-1",
      bvn_number: "22345678901"
    })
  }
);

const result = await response.json();

if (!response.ok) {
  throw new Error(
    `BVN verification request failed: ${response.status}`
  );
}

console.log(result);

This example uses the API key stored in the backend environment variable VERIFYDECK_API_KEY.

import os
import requests

url = "https://api.verifydeck.com/verify/bvn"

headers = {
    "X-API-Key": os.environ["VERIFYDECK_API_KEY"],
    "Content-Type": "application/json"
}

payload = {
    "end_user_id": "applicant-1",
    "bvn_number": "22345678901"
}

response = requests.post(
    url,
    headers=headers,
    json=payload,
    timeout=30
)

response.raise_for_status()

result = response.json()

print(result)

These examples demonstrate server-side requests using the documented endpoint, authentication header, and required request fields.

7. Integration Best Practices

Keep API Credentials Secure

Make requests from your backend and keep your VerifyDeck secret API key outside publicly accessible application code.

Validate BVN Input

Before submitting a verification request, check that the applicant's BVN contains 11 digits.

This is a recommended client-side or backend validation step, not a statement about undocumented VerifyDeck error behavior.

Handle Nullable Identity Fields

Some response fields may contain null.

Ensure your application can process these values without assuming that every identity field will be populated.

Store Verification References Where Needed

If your application needs to retrieve a past verification, retain its verification_id securely.

Handle API Responses

Check the HTTP response status when making requests and handle unsuccessful requests in your application.

Protect Personal Information

Treat BVNs and returned identity details as personal information. Apply appropriate security and data protection controls when collecting, transmitting, or storing this information.

8. Frequently Asked Questions

What is the VerifyDeck BVN Verification API?

The VerifyDeck BVN Verification API allows applications to submit a Bank Verification Number for validation and receive available identity details associated with it.

What is required to verify a BVN?

The API requires two request body fields: end_user_id and bvn_number.

How many digits must a BVN contain?

The documented request field requires an 11-digit BVN submitted as a string.

Does BVN verification require an image upload?

No. The BVN Verification API does not require a pre-hosted image.

How do I authenticate a BVN verification request?

Include your VerifyDeck secret API key in the X-API-Key header.

Can I integrate the BVN API directly into my frontend?

No. The API requires a secret key and is intended for server-to-server requests. Your backend should make the authenticated request.

What identity information can the API return?

The documented response includes fields for full name, date of birth, phone number, and photograph URL.

These fields may return null.

Can I retrieve a previously submitted BVN verification?

Yes. Use GET /verify/bvn/{id} with the verification ID.

Does the API return a verification score?

The response includes a verification_score field with the type integer | null. The score's range and calculation method are not specified in the supplied API contract.

What does the verification status indicate?

The API includes a verification_status string in its response. The specific possible values have not been defined in the supplied specification.

9. API Reference Summary

10. API Integration Checklist

• Before integrating the VerifyDeck BVN Verification API, ensure that:
• You have your VerifyDeck secret API key.
• Your application makes requests from a secure backend.
• Your API key is included in the X-API-Key header.
• Your requests use the documented HTTPS base URL.
• Your request body includes end_user_id.
• Your request body includes an 11-digit bvn_number string.
• Your application can process the documented response fields.
• Your application handles nullable identity fields.
• Your application can retain the verification ID when retrieval is needed.
• Your application handles unsuccessful HTTP requests.