Identity

Get the most of your business by instantly retrieving full bank-vetted identity profiles from users’ bank accounts.

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:

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 or Get identity by NIN 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 | NUBAN verification request

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

JSON | NUBAN verification response

{
  "data": {
    "bank": {
      "_id": "5d6fe57a4099cc4b210bbeb1",
      "slug": "first-bank-of-nigeria"
    },
    "identity": {
      "id": "13518bbdc067dcd0689f3489",
      "verification_country": "NG",
      "bvn": "11503327437",
      "lga_of_residence": "Illela",
      "address": [
        "Gidan Ruwa Area Illela"
      ],
      "marital_status": "Single",
      "next_of_kins": [],
      "state_of_origin": "Sokoto State",
      "lastname": "Smith",
      "state_of_residence": "Sokoto State",
      "fullname": "John Smith",
      "dob": "1983-08-13",
      "enrollment": {
        "branch": "Eng Illela Branch 416",
        "bank": "050",
        "registration_date": "2013-12-01"
      },
      "aliases": [],
      "photo_id": [
        {
          "image_type": "bvn_photo",
          "url": "https://df7b45oo546j4.cloudfront.net/MjI1MDMzMjc0Mzc%3D.png"
        }
      ],
      "phone": [
        "11037301100"
      ],
      "nationality": "Nigeria",
      "email": [],
      "firstname": "Smith",
      "gender": "Male",
      "lga_of_origin": "Illela",
      "customer": "13518bc41384bd001d8bb265"
    },
    "receipt": {
      "data": { "receipt": { "charge_breakdown": { "vat": 0
          },
          "last_updated": "2023-09-29T14:10:23.783Z",
          "method": "wallet",
          "billable_service": "nuban-verify",
          "charge": 0.055,
          "breakdown": {
            "source": "api",
            "discount": 0,
            "billable_product": {
              "credits": 0.055,
              "effective_credits": 0,
              "addon_products": [],
              "product": "identity",
              "status": true
            },
            "limit": "3",
            "billable_products": [
              {
                "addon_products": [],
                "_id": "1516dacf2a8b9b003accce30",
                "archived": false,
                "effective_cost": 0,
                "product": "identity",
                "cost": 0.055,
                "status": true
              }
            ]
          },
          "owner": "1eeb6b970dfe81086098d529",
          "current_project": "1ff633889e64635f2629df90",
          "wallet_balance": 436.2972,
          "_id": "1116dacf2a8b9b003accce2f",
          "created_at": "2023-09-29T14:10:23.783Z",
          "type": "api-call",
          "paid": true,
          "currency": "Okra Credits",
          "billable_product": "identity",
          "record": "1516dacd2a8b9b003accce09",
          "billingStatus": true,
          "addons": [],
          "customer": "13518bc41384bd001d8bb265",
          "plan_term": "prepaid"
        }
      },
      "msg": "Receipt has been successfully created",
      "status": true
    },
    "customer": "13518bc41384bd001d8bb265"
  },
  "message": "Identity retrieved successfully",
  "status": "success"
}

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