> For the complete documentation index, see [llms.txt](https://docs.amala.cloud/amalacloud-api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amala.cloud/amalacloud-api-docs/business/nin-verification/advance-nin-verification.md).

# Advance NIN Verification

The Advance NIN Verification API allows you to verify an individual's details using their National Identification Number (NIN). This helps in identity validation and fraud prevention.

### Base URL

```
https://acs-uat-verifications.amala.cloud/
```

```
https://acs-prod-verifications.amala.cloud/
```

### Endpoint

```swift
POST https://acs-uat-verifications.amala.cloud/verification/api/v1/idv/advance/nin
```

### Request Headers

You can use either the API key or Bearer Token for Authorization

| Header          | Type               | Description                                        |
| --------------- | ------------------ | -------------------------------------------------- |
| `Content-Type`  | `application/json` | Specifies that the request body is in JSON format. |
| `Authorization` | `Bearer <token>`   | Bearer Token for authentication.                   |
| `x-api-key`     | `API-KEY`          | API Key for authentication                         |

### Request Body

The request body should contain **NIN details** in JSON format.

#### Example Request

```json
{
  "number": "12345678901",
  "firstName": "John",
  "lastName": "Doe",
  "reference": "REF123456",
  "serviceProviderCode": "SPC001"
}
```

#### Request Body Schema

| Field                 | Type   | Required | Description                                                     |
| --------------------- | ------ | -------- | --------------------------------------------------------------- |
| `number`              | string | ✅        | The **National Identification Number (NIN)** of the individual. |
| `firstName`           | string | ✅        | First name of the individual.                                   |
| `lastName`            | string | ✅        | Last name of the individual.                                    |
| `reference`           | string | ✅        | A unique transaction reference.                                 |
| `serviceProviderCode` | string | ✅        | Code identifying the service provider.                          |

### Responses

#### Success Response (200 OK)

If the NIN is valid, the API returns **user details** as per the `GetDetailsOfNINResponseApiResponse` schema.

```json
{
  "apiVersion": "1.0",
  "success": true,
  "code": "00",
  "message": "Verification successful",
  "requestId": "REQ-123456",
  "data": {
    "surname": "Doe",
    "firstName": "John",
    "middleName": "Michael",
    "gender": "Male",
    "birthDate": "1990-05-15",
    "telephoneno": "+2348012345678",
    "email": "john.doe@email.com",
    "employmentStatus": "Employed",
    "residenceAddress": "123 Example Street, Lagos",
    "residenceTown": "Ikeja",
    "residenceLga": "Ikeja",
    "residenceState": "Lagos",
    "nokSurname": "Smith",
    "nokFirstName": "Jane",
    "nokMiddlename": "Ann",
    "nokAddress1": "456 Guardian Street",
    "nokTown": "Abuja",
    "nokLga": "Garki",
    "nokPostalcode": "900001",
    "nokState": "FCT",
    "photo": "base64-encoded-image-data"
  }
}

```

#### Error Responses

| `400` | Bad Request (Invalid NIN format) | `{ "success": false, "message": "Invalid NIN format.", "code": "400" }` |
| ----- | -------------------------------- | ----------------------------------------------------------------------- |
|       |                                  |                                                                         |

| `401` | Unauthorized (Invalid API Key) | `{ "success": false, "message": "Unauthorized access.", "code": "401" }` |
| ----- | ------------------------------ | ------------------------------------------------------------------------ |

| `500` | Internal Server Error | `{ "success": false, "message": "Something went wrong.", "code": "500" }` |
| ----- | --------------------- | ------------------------------------------------------------------------- |

### Usage Example (cURL)

```bash
curl -X POST "https://acs-uat-verifications.amala.cloud/verification/api/v1/idv/advance/nin" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "number": "12345678901",
           "firstName": "John",
           "lastName": "Doe",
           "reference": "REF123456",
           "serviceProviderCode": "SPC001"
         }'

```