> 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-initiate.md).

# BVN Initiate

Initiates the verification process **BVN** (Bank Verification Number) for Nigeria and returns the **available verification methods** (`phone`, `phone_1`, `email`, `alternate_phone`) for sending the OTP.

### Endpoint

```
POST /kyc/nga/bvn/initiate
```

### 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**.                |
| `scope`   | string | **Yes**  | Query scope. Possible values: `identity`, `bank_accounts` |

#### Request example

```json
{
  "bvn": "12345678901",
  "scope": "identity"
}
```

### 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 session data and available methods. See table below.                                                              |

#### Response parameters — `data`

| Parameter    | Type   | Description                                              |
| ------------ | ------ | -------------------------------------------------------- |
| `session_id` | string | **Session ID** for the following verification steps.     |
| `methods`    | array  | Available methods for OTP verification. See table below. |

#### Response parameters — `data.methods[]`

| Parameter | Type   | Description                                                                                                                                |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `method`  | string | Verification method type. Possible values: `phone`, `phone_1`, `email`, `alternate_phone`                                                  |
| `hint`    | string | Full phrase indicating where the code will be sent, and includes the phone or email address **partially masked**. The exact text may vary. |

#### Service Result Code

The `serviceResultCode` indicates the overall result of the service execution:

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

#### Response example

```json
{
  "serviceResultCode": 200,
  "serviceTime": "1200",
  "serviceResultLog": "Success",
  "serviceTransactionId": "796a580b-67b5-4a6e-a19a-5b9145ad55cd",
  "data": {
    "session_id": "5f9b1a2c-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
    "methods": [
      {
        "method": "phone",
        "hint": "Sms with a verification code will be sent to phone 0803***3843"
      },
      {
        "method": "email",
        "hint": "An email with a verification code will be sent to j***doe@example.com"
      },
      {
        "method": "alternate_phone",
        "hint": "Sms with a verification code will be sent to your alternate phone number"
      }
    ]
  }
}
```

#### `400` Bad Request

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

```json
{
  "serviceResultCode": 400,
  "serviceResultLog": "Invalid BVN format. Please check the details and try again",
  "serviceTime": "120", 
  "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 %}