Identity

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 KYC 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 the Identity API’s verify and get endpoint operations. Okra recommends that you leverage the Identity API using this simple process:

Use a get operation to retrieve a user’s identity.

For example, you can use Get identity by BVN or Get identity by NUBAN as an initial step. The next step depends on the response you receive:
- A successful response means that the user is already verified and the API returns the identity profile for you.
- An unsuccessful response means that the BVN is not found and the user is not yet verified.
If you receive an unsuccesful response, use a verify operation to verify the new user and retrieve their identity details.

Visit the API reference for the complete list of Identity endpoint operations, and the recommended best practices on how to make the most of the Identity API.

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 successfully retrieved",
    "data": {
      "id": "13febc0eddec1a7e5743b189",
      "firstname": "Ifeoma",
      "middlename": "Nkoyo",
      "lastname": "Odujobi",
      "fullname": "Ifeoma Nkoyo Odujobi",
      "dob": "1985-12-15",
      "bvn": "22333489596",
      "gender": "Female",
      "customer": "13febc0e6f13820012adbb96",
      "verification_country": "NG",
      "aliases": [],
      "phone": [
        "07034621631"
      ],
      "email": [
        "[email protected]"
      ],
      "address": [
        "No 10 Mbanugo Street Ikate Surulere"
      ],
      "nationality": "Nigeria",
      "lga_of_origin": "Idemili North",
      "lga_of_residence": "Surulere Lagos State",
      "state_of_origin": "Anambra State",
      "state_of_residence": "Lagos State",
      "marital_status": "Married",
      "next_of_kins": [],
      "nin": "54493326942",
      "photo_id": [
        {
          "url": "https://dv7b45oo546j4.cloudfront.net/MjIxNTM0ODk1OTY%3D.png",
          "image_type": "bvn_photo"
        }
      ],
      "enrollment": {
        "bank": "058",
        "branch": "Trans Amadi Port Harcourt",
        "registration_date": "Invalid Date"
      },
      "record": "13febc086f13820012adbb93",
      "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": 180,
            "wallet_balance": 40073.85,
            "addons": [],
            "archived": false,
            "micro_lending": false,
            "ussd_pricing": false,
            "ussd_pricing_discount": 0,
            "micro_lending_discount": 0,
            "_id": "12febc0e6f13820012adbb9a",
            "plan_term": "postpaid",
            "owner": "1da6358130a943486f33dced",
            "type": "bvn-verify",
            "currency": "NGN",
            "plan": "payg",
            "plan_type": "1da478aa9ce2295ff32a5131",
            "record": "13febc086f13820012adbb93",
            "created_at": "2023-03-01T02:44:30.404Z",
            "last_updated": "2023-03-01T02:44:30.404Z"
          }
        }
      }
    }
  }

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.