> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/rest-api/identity-api/identity-api-reference/onboarding/kyc/nigeria/bvn-verification/bvn-details.md).

# BVN Details

Directly query the **complete BVN data** (Bank Verification Number) of Nigeria **without the OTP consent Flow**. It is an alternative to the 3-step BVN verification Flow ([BVN Initiate](/docs.facephi-en/rest-api/identity-api/identity-api-reference/onboarding/kyc/nigeria/bvn-verification/bvn-initiate.md), [BVN Send OTP](/docs.facephi-en/rest-api/identity-api/identity-api-reference/onboarding/kyc/nigeria/bvn-verification/bvn-send-otp.md), [BVN Verify OTP](/docs.facephi-en/rest-api/identity-api/identity-api-reference/onboarding/kyc/nigeria/bvn-verification/bvn-verify-otp.md)) when the holder's OTP validation is not required.

**Note:** each request is **billed even if the lookup fails**. It is recommended to validate the BVN format (**11 numeric digits**) on the client side before sending the request.

### Endpoint

```
POST /kyc/nga/bvn/details
```

### Authentication

| Type    | Location | Name          |
| ------- | -------- | ------------- |
| API Key | Header   | **x-api-key** |

### Request body

**Content-Type:** `application/json`

#### Parameters

| Parameter | Type   | Required | Description                                |
| --------- | ------ | -------- | ------------------------------------------ |
| `bvn`     | string | **Yes**  | Bank Verification Number of **11 digits**. |

#### Request example

```json
{
  "bvn": "12345678901"
}
```

### Responses

#### `200` Success

#### Response parameters

| Parameter              | Type    | Description                                                                                                                   |
| ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`    | integer | Code that indicates the **overall result** of the service execution. See [Service Result Code](#service-result-code)          |
| `serviceTime`          | string  | Processing time **(milliseconds)**.                                                                                           |
| `serviceResultLog`     | string  | Descriptive field of the result of the service execution. Includes details when there is an error or exception in the module. |
| `serviceTransactionId` | string  | Transaction identifier associated with the request processed by the API.                                                      |
| `data`                 | object  | Object with the complete BVN data. See table below.                                                                           |

#### Response parameters — `data`

**Note:** the object `data` is returned **without field mapping or normalization**. Field names and spelling are preserved exactly as received.

| Parameter           | Type    | Description                                                                                                                                  |
| ------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `bvn`               | string  | Bank Verification Number.                                                                                                                    |
| `first_name`        | string  | Name(s) of the holder.                                                                                                                       |
| `middle_name`       | string  | Middle name.                                                                                                                                 |
| `last_name`         | string  | Holder's last name(s).                                                                                                                       |
| `dob`               | string  | Date of birth.                                                                                                                               |
| `gender`            | string  | Gender.                                                                                                                                      |
| `email`             | string  | Registered email address.                                                                                                                    |
| `phone_number`      | string  | Registered phone number.                                                                                                                     |
| `phone_number_2`    | string  | Registered alternate phone number.                                                                                                           |
| `address`           | string  | Residential address.                                                                                                                         |
| `state_of_origin`   | string  | State of origin.                                                                                                                             |
| `lga_of_origin`     | string  | Local Government Area (LGA) of origin.                                                                                                       |
| `lga_of_Residence`  | string  | Local Government Area (LGA) of residence. The field is literally called `lga_of_Residence` (sic): spelling is preserved exactly as received. |
| `marital_status`    | string  | Marital status.                                                                                                                              |
| `nin`               | string  | National Identification Number associated with the BVN.                                                                                      |
| `nationality`       | string  | Nationality.                                                                                                                                 |
| `registration_date` | string  | BVN registration date.                                                                                                                       |
| `watch_listed`      | boolean | Indicates whether the holder is on **watchlist**.                                                                                            |
| `photoId`           | string  | Holder's photo in **Base64**.                                                                                                                |

#### Service Result Code

The `serviceResultCode` indicates the overall result of the service execution and reflects the **HTTP status code** of the response:

| serviceResultCode | Description                                                                       | HTTP Code |
| ----------------- | --------------------------------------------------------------------------------- | --------- |
| 200               | The service execution was successful, the module processed the request correctly. | 200       |

#### Response example

```json
{
  "serviceResultCode": 200,
  "serviceTime": "1400",
  "serviceResultLog": "Success",
  "serviceTransactionId": "e41h235i-34i2-1h3l-h86h-2i6812hj22jk",
  "data": {
    "bvn": "12345678901",
    "first_name": "JOHN",
    "middle_name": "PAUL",
    "last_name": "DOE",
    "dob": "15-Jan-1990",
    "gender": "Male",
    "email": "john.doe@example.com",
    "phone_number": "08012345678",
    "phone_number_2": "08087654321",
    "address": "123 Main Street, Lagos",
    "state_of_origin": "Lagos State",
    "lga_of_origin": "Lagos Island",
    "lga_of_Residence": "Ikeja",
    "marital_status": "Single",
    "nin": "09876543212",
    "nationality": "Nigeria",
    "registration_date": "01-Mar-2015",
    "watch_listed": false,
    "photoId": "base64encodedphoto..."
  }
}
```

#### `400` Bad Request

Error returned with the service envelope (`serviceResultCode` reflects the HTTP status code of the response):

```json
{
  "serviceResultCode": 400,
  "serviceResultLog": "Sorry, lookup failed. Please check the details and try again",
  "serviceTime": "151",
  "serviceTransactionId": "08ac9699-dc9e-4cdc-81d7-264f71838309"
}
```

#### `502` Bad Gateway

Returned when the service is temporarily unavailable or its response could not be interpreted. The body uses the service envelope with `serviceResultCode: 500`:

```json
{
  "serviceResultCode": 500,
  "serviceResultLog": "Service temporarily unavailable. Please try again later",
  "serviceTime": "3000",
  "serviceTransactionId": "38de2932-0f2h-7gff-14g0-597h04161632"
}
```

#### `504` Gateway Timeout

Timeout error **timeout**, returned with the service envelope:

```json
{
  "serviceResultCode": 504,
  "serviceResultLog": "Request timeout. Please try again",
  "serviceTime": "30000",
  "serviceTransactionId": "48ef3043-1g3i-8hgg-25h1-608i15272743"
}
```

{% hint style="info" %}
Authentication errors (`401`/`403`) are rejected by the **gateway before reaching the service** and **do not** use the envelope `serviceResultCode`. Platform validation errors use the format `application/problem+json`. See [Error handling](/docs.facephi-en/rest-api/identity-api/identity-api-reference/onboarding/kyc/nigeria.md#manejo-de-errores) for details on the three response formats.
{% endhint %}