Base URL

https://api.verifydeck.com

Endpoint

POST /v1/identity/nin/verify

Content-Type

application/json

Authentication

Bearer API_KEY

This is a sample API specification for VerifyDeck. The endpoint, fields and response structures below are illustrative and should be aligned with the actual backend implementation before publication.

1. How it works

1. Submit a NIN - Your application sends the customer's NIN to VerifyDeck through an authenticated API request.
2. Verification processing - VerifyDeck validates the request and submits the verification to its configured, authorized identity data provider.
3. Identity matching - The returned identity data is evaluated against the submitted details, where applicable.
4. Receive the result - VerifyDeck returns a structured response indicating the verification status and any permitted identity details.

2. Authentication

All API requests must include a valid API key in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Example:

curl -X POST "https://api.verifydeck.com/v1/identity/nin/verify" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nin": "12345678901"
  }'

Security

Never expose your API key in frontend JavaScript, mobile application code or publicly accessible repositories. Make API calls from your secure backend.

3. Request parameters

POST /v1/identity/nin/verify

Example request:

{
  "nin": "12345678901",
  "consent": true,
  "reference": "vd_nin_20260929_001"
}

The NIN value above is fictional and used for documentation purposes only.

4. Response

A successful API request returns an HTTP 200 OK response when verification processing is completed.

{
  "success": true,
  "message": "NIN verification successful",
  "data": {
    "verification_id": "ver_nin_8f92a1c4",
    "reference": "vd_nin_20260929_001",
    "nin": "********901",
    "status": "verified",
    "identity": {
      "first_name": "John",
      "middle_name": "Michael",
      "last_name": "Doe",
      "date_of_birth": "1995-04-12",
      "gender": "male",
      "phone_number": null
    },
    "match": {
      "status": "matched"
    },
    "verified_at": "2026-09-29T14:30:00Z"
  }
}

Illustrative response. Returned identity fields depend on provider capabilities, authorization and the actual VerifyDeck implementation.

Response fields

5. Verification statuses

A not_verified result is different from a failed result. The former is a verification outcome; the latter indicates that the verification process encountered an error.

6. Error responses

VerifyDeck uses standard HTTP status codes to communicate request and processing errors.

400 — Bad Request

The request is malformed or contains invalid parameters.

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request could not be processed."
  }
}

401 — Unauthorized

The API key is missing or invalid.

JSON

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "A valid API key is required."
  }
}

422 — Validation Error

The submitted NIN does not meet the required format.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "NIN must contain exactly 11 digits."
  }
}

429 — Too Many Requests

The client has exceeded the permitted request rate.

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later."
  }
}

502 — Provider Error

The upstream verification provider returned an error or an invalid response.

{
  "success": false,
  "error": {
    "code": "PROVIDER_ERROR",
    "message": "The verification provider could not process the request."
  }
}

These are proposed error formats; actual error codes and status handling should match the deployed API.

7. Code examples

Choose your preferred language to view an integration example.

const response = await fetch(
  "https://api.verifydeck.com/v1/identity/nin/verify",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VERIFYDECK_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      nin: "12345678901",
      consent: true,
      reference: "customer_001"
    })
  }
);

const result = await response.json();

if (!response.ok) {
  throw new Error(
    result.error?.message || "Verification failed"
  );
}

console.log(result.data.status);

import os
import requests

url = "https://api.verifydeck.com/v1/identity/nin/verify"

headers = {
    "Authorization": f"Bearer {os.environ['VERIFYDECK_API_KEY']}",
    "Content-Type": "application/json"
}

payload = {
    "nin": "12345678901",
    "consent": True,
    "reference": "customer_001"
}

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

response.raise_for_status()
result = response.json()

print(result["data"]["status"])

<?php
$url = "https://api.verifydeck.com/v1/identity/nin/verify";

$payload = [
    "nin" => "12345678901",
    "consent" => true,
    "reference" => "customer_001"
];

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("VERIFYDECK_API_KEY"),
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode($payload)
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

curl_close($ch);

$result = json_decode($response, true);

if ($status < 200 || $status >= 300) {
    throw new Exception("Verification failed");
}

echo $result["data"]["status"];

8. Best practices

• Obtain consent: Ensure that the individual has provided appropriate consent or another valid legal basis for identity verification.
• Protect personal data: Transmit NINs only over HTTPS and avoid logging full NINs or identity information.
• Secure your API key: Store credentials in environment variables or a secure secrets manager.
• Handle errors: Implement suitable retry logic for temporary network or provider failures. Avoid retrying requests indiscriminately.
• Use references: Generate unique transaction references to associate API responses with your internal customer records.
• Limit data retention: Store only the identity information required for your legitimate business purpose, in accordance with applicable data protection requirements.

9. Frequently asked questions

Can I verify a NIN without submitting a customer's personal details?

This sample endpoint uses the NIN as its primary input. Additional details may be required depending on the verification method and configured provider.

Does a successful API response guarantee the customer is the rightful NIN holder?

No. A successful NIN verification establishes the outcome returned by the authorized data source. Additional checks, such as facial verification or liveness detection, may be necessary to establish that the person presenting the NIN is its rightful holder.

Can I use this API for KYC onboarding?

NIN verification can be one component of a KYC workflow. Businesses should apply any additional identity, risk and compliance checks relevant to their use case.

What happens if the verification provider is unavailable?

The API should return an appropriate error response or a pending status, depending on whether the request can be safely retried or its result is still being processed.

Suggested documentation navigation for VerifyDeck:

• Introduction
• Authentication
• API Overview
• NIN Verification
• BVN Verification
• Facial Verification
• Liveness Detection
• Error Codes
• Rate Limits
• API Reference