Identity API

Overview

Identity verification is an essential security step when authenticating users. Okra's real-time data service reduces risk and fraud by providing identity profiles directly from financial institutions. Okra’s Identity API allows users with online or mobile banking to validate their financial data ownership, enabling you to safely unlock your services. Once a user connects, the API can automatically retrieve their BVN, biometric photo, and full Know Your Customer (KYC) profile - no need to ask for BVN again.

How it works

The Okra Identity API helps you verify users' identities by accessing the information stored with their financial institution. The API retrieves a full LYC profile for an individual or corporate entity across all banks in Nigeria. You can access a user's full name, phone number, email address, mailing address, and many other details. Use this data to pre-fill account details and verify that the information provided by your user is correct.

The Identity API helps you to make the most of your business case by instantly retrieving a full identity profile, and enables you to authenticate your users’ accounts in real time.

Depending on your use case, the API can return data points like these:

Validated BVN
BVN identity photo
DTI (Debt-to-Income score)
Mother’s maiden name
Full name or company name
Gender
Date of birth
Email addresses
Mailing addresses
Phone numbers
Photo IDs

Okra's Identity API enables you to improve your product and decision-making processes. It can be used for identity verification for loan or credit decisioning, age or name verification, checking company background, and similar use cases.

How to use

This guide explains how you can retrieve your users' identity details with Okra's verify endpoints. Okra recommends that you leverage the Identity API in this order:

Use any of the verify operations according to your business case. These operations can verify a new user and retrieve their identity details:
1. the bvn-verify operation retrieves a user’s KYC profile from their financial institution using their Bank Verification Number
2. the bulk-bvn-verify operation retrieves identity profiles for up to 10 users in the same request
3. the nuban-verify operation retrieves a user’s KYC profile using their Nigerian Uniform Bank Account Number
4. the nuban-name-verify operation retrieves a user’s full name using their NUBAN. This operation is ideal for use cases where a complete KYC profile is not necessary.
5. the customer-verify operation retrieves a user’s identity profile using their customer ID. Okra suggests using this operation for customers who already connected their accounts, but do not have a verified identity yet. This operation requires the user’s BVN to be available in the user’s profile.
The responses from these operations contain identity-related details that you can use for user verification and other KYC purposes.
Use the get operations to retrieve the identity profiles of already verified users.

You can fetch your users’ identity profiles using identity ID, customer ID, and by date for a single user or for all users.

📘
Okra recommends that you use the verify operations to verify customers and retrieve their identity details only for the first time. These operations debit your Okra wallet after every successful verification. To avoid depleting your wallet, use the get identity operations for customers whom you have already verified.

Sample objects

These are sample requests and responses for verify operations:

curl -X POST https://api.okra.ng/v2/products/kyc/bvn-verify
-H 'Content-Type: application/json'
-d '{
  "bvn" : "22156153506"
}'

{
    "status": "success",
    "message": "Identity succesfully retrieved",
    "data": {
        "identity": {
            "fullname": "GAVIN BELSON",
            "id": "5da635898ytghi9876tgh",
            "bvn": "12331106253",
            "score": "0",
            "env": "production",
            "created_at": "2019-12-14T13:46:53.415Z",
            "last_updated": "2021-01-26T10:14:56.300Z",
            "aliases": [],
            "customer": {
                "_id": "5da635898ytghi9876tgh",
                "name": "GAVIN BELSON"
            },
            "dob": "1979-09-27",
            "gender": "M",
            "middlename": "MIDDLENAME",
            "firstname": "GAVIN",
            "lastname": "BELSON",
            "phone": [
                "2347088793567"
            ],
            "email": [],
            "address": [
                "4 AKANNI BASHORUN,LEKKI  LAGOS"
            ],
            "verified": true,
            "photo_id": [{..photo data..}
            ],
            "status": "failed"
        },
        "customer": "5da635898ytghi9876tgh",
        "account": "5da635898ytghi9876tgh",
        ........
        },
        ........
    }
}

curl -X POST https://api.okra.ng/v2/products/kyc/bvn-verify
-H 'Content-Type: application/json'
-d '{
     "bvn": "22156153506, 22191943425"
}

{
  "status": "success",
  "message": "Identities successfully retrieved",
  "data": {
    "identities": [
      {
        "id": "63d42aaac7c22922b4e4cfda",
        "firstname": "Doe",
        "middlename": "John",
        "lastname": "Handy",
        "fullname": "Doe John Handy",
        "dob": "1980-05-10",
        "bvn": "22156153506",
        "gender": "Male",
        "customer": "63d150669631c108b90076a0",
        "verification_country": "NG",
        "aliases": [],
        "phone": [
          "08060100006"
        ],
        "email": [
          "[email protected]"
        ],
        "address": [
          "9 Ajuwon Streeet Fagba B Stop Iju"
        ],
        "nationality": "Nigeria",
        "lga_of_origin": "Esan North",
        "lga_of_residence": "Oshodi",
        "state_of_origin": "Ogun State",
        "state_of_residence": "Lagos State",
        "marital_status": "Married",
        "next_of_kins": [],
        "nin": "76700000916",
        "photo_id": [
          {
            "url": "https://djrzfsrexmrry.cloudfront.net/MjIx.png",
            "image_type": "bvn_photo"
          }
        ],
        "enrollment": {
          "bank": "058",
          "branch": "Fek Alauz",
          "registration_date": "Invalid Date"
        }
      },
      {
        "id": "63d3a878c7c22922b4da34ab",
        "firstname": "Chinendu",
        "middlename": "Jim",
        "lastname": "Benz",
        "fullname": "Chinendu Jim Benz",
        "dob": "1980-10-01",
        "bvn": "22191943425",
        "gender": "Male",
        "customer": "60df8549c52f9ca67b071679",
        "verification_country": "NG",
        "aliases": [],
        "phone": [
          "08011111112"
        ],
        "email": [
          "[email protected]"
        ],
        "address": [
          "Bolinga Street Yagai Jalingo"
        ],
        "nationality": "Nigeria",
        "lga_of_origin": "Jalingo North",
        "lga_of_residence": "Jalingo",
        "state_of_origin": "Edo State",
        "state_of_residence": "Taraba State",
        "marital_status": "Single",
        "next_of_kins": [],
        "nin": "36007900033",
        "photo_id": [
          {
            "url": "https://djrzfsrexmrry.cloudfront.net/MjI.png",
            "image_type": "bvn_photo"
          }
        ],
        "enrollment": {
          "bank": "058",
          "branch": "Jalingo",
          "registration_date": "2019-01-10"
        }
      }
    ],
    "receipt": {
      "status": true,
      "msg": "Receipt has been successfully created",
      "data": {
        "receipt": {
          "adjustment": {
            "receipts": []
          },
          "charge_breakdown": {
            "vat": 0
          },
          "breakdown": {
            "discount": 0,
            "billable_products": []
          },
          "billingStatus": true,
          "adjusted": null,
          "adjusted_receipt": false,
          "paid": false,
          "fixed": false,
          "adjusted_type": null,
          "method": "wallet",
          "charge": 332,
          "wallet_balance": 31264106.69,
          "addons": [],
          "archived": false,
          "micro_lending": false,
          "ussd_pricing": false,
          "ussd_pricing_discount": 0,
          "micro_lending_discount": 0,
          "_id": "63d42ab97f9990236d45c27b",
          "plan_term": "postpaid",
          "owner": "5d9288ea182d3d000cb7c486",
          "type": "bvn-verify",
          "currency": "NGN",
          "plan": "payg",
          "plan_type": "5d96082bf170152c5c38fa16",
          "record": "63d42a9a7f9990236d45c274",
          "created_at": "2023-01-27T19:49:13.209Z",
          "last_updated": "2023-01-27T19:49:13.209Z",
          "__v": 0
        }
      }
    }
  }
}

Visit the API reference for a complete list of operations and sample responses.