• Identity API

Identity

The Okra Identity API helps you verify users' identities by retrieving KYC information from their banks. Check out the Identity API overview for more details.

post

NIN Verify

This operation enables you to to seamlessly verify user identities using their National Identification Number (NIN) issued by Nigeria's National Identity Management Commission (NIMC).

The base server URL for this endpoint is https://identity-api.okra.ng/v2/

ninstring

required

National Identification Number (NIN) issued by Nigeria's National Identity Management Commission (NIMC).

refreshboolean

You can request the API to refresh a user's identity profile by setting this parameter to true. Refreshing an existing identity profile means that any changes in personal details, like a new address or a change in the user's marital status will be reflected in the user's identity data. If there is no existing identity profile yet for a user with the requested NIN, the API creates a new one. If you set this parameter to false, the API creates a new identity profile based on the requested NIN.

testingboolean

When true, this setting redirects your API call to the Sandbox environment. The data you receive is sandbox data, not real user data. When testing is true, you will not be charged for using this endpoint operation.

successboolean

Use this setting in the Sandbox environment to test success and failure scenarios. When true, this setting forces a success response for the NIN name verify operation. When false, it forces a failure response.

includeRawImageboolean

Use this setting to request the Identity API to return a URL that points to the user's identity image.

Responses

Request examples

{
  "nin": "string",
  "refresh": true,
  "testing": true,
  "success": true,
  "includeRawImage": true
}

Response examples

OK

[
  {
    "success": true,
    "message": "Identity retrieved successfully",
    "data": {
      "identity": {
        "_id": "119f2879df9a02d86938bd4c",
        "nin": "11112899518",
        "address": [
          "22 Park ave"
        ],
        "aliases": [],
        "dob": "12-11-1984",
        "email": [
          "ptj@cool.com"
        ],
        "employer": [],
        "env": "production",
        "firstname": "Peter",
        "fullname": "Peter Timothy Jones",
        "gender": "Male",
        "lastname": "Jones",
        "lga_of_origin": "Lagos",
        "middlename": "Timothy",
        "nationality": "Nigeria",
        "next_of_kins": [],
        "phone": [
          "11167214869"
        ],
        "photo_id": [
          {
            "url": "https://1111rry.cloudfront.net/NTg5MTI4OTk1MTg%3D.png",
            "image_type": "nin_photo"
          }
        ],
        "record": [
          "119f28635eaaf5b6ad9580b1",
          "119f2a61b4c397ca36c6a899",
          "119f2a76b4c397ca36c6a8e2",
          "119f2dc6856e65ea39913e87",
          "11b1081afa7b550c9939d39b",
          "11b1120b9079f3edecd3e8c8",
          "11b4e0b5716570a15764c922"
        ],
        "state_of_origin": "Lagos",
        "customer": "1424b4263bd4390012d6b193"
      },
      "receipt": {
        "owner": "11d9288ea182d3d000cb7c486",
        "record": "16b4e0b5716570a15764c922",
        "customer": "1424b4263bd4390012d6b193",
        "billingStatus": true,
        "paid": true,
        "type": "api-call",
        "method": "wallet",
        "plan_term": "prepaid",
        "charge": 0.1,
        "charge_breakdown": {
          "vat": 0
        },
        "wallet_balance": 3.11,
        "currency": "Okra Credits",
        "addons": [],
        "billable_product": "identity",
        "billable_service": "nin-verify",
        "breakdown": {
          "discount": 0,
          "billable_product": {
            "product": "identity",
            "effective_credits": 0,
            "credits": 0.14,
            "status": true,
            "addon_products": []
          },
          "billable_products": [
            {
              "product": "identity",
              "effective_cost": 0,
              "cost": 0.14,
              "status": true,
              "addon_products": [],
              "_id": "16b4e0b5716570a15764c93d"
            }
          ],
          "source": "api",
          "limit": 24
        },
        "current_project": "147894a51ae7fdc703bcaaa6",
        "_id": "116b4e0b5716570a15764c93c",
        "created_at": "2024-08-08T15:13:57.554Z",
        "last_updated": "2024-08-08T15:13:57.554Z"
      }
    }
  }
]

Example of a success response for the NIN verify operation.

post

Nuban Name Verify

This operation enables you to retrieve a user’s full name using their NUBAN. This operation is ideal for use cases where a complete KYC profile is not necessary.

The base server URL for this endpoint is https://identity-api.okra.ng/v2/

nubanstring

required

The user's NUBAN.

bankstring

required

The unique bank ID used to identify the user's account holder bank. Visit Okra's Account data coverage page for the list of bank IDs.

refreshboolean

You can request the API to refresh a user's identity profile by setting this parameter to true. Refreshing an existing identity profile means that any changes in personal details, like a new address or a change in the user's marital status will be reflected in the user's identity data. If there is no existing identity profile yet for a user with the requested NIN, the API creates a new one. If you set this parameter to false, the API creates a new identity profile based on the requested NIN.

testingboolean

When true, this setting redirects your API call to the Sandbox environment. The data you receive is sandbox data, not real user data. When testing is true, you will not be charged for using this endpoint operation.

successboolean

Use this setting in the Sandbox environment to test success and failure scenarios. When true, this setting forces a success response for the NIN name verify operation. When false, it forces a failure response.

includeRawImageboolean

Use this setting to request the Identity API to return a URL that points to the user's identity image.

Responses

Request examples

{
  "nuban": "string",
  "bank": "string",
  "refresh": true,
  "testing": true,
  "success": true,
  "includeRawImage": true
}

Response examples

OK

[
  {
    "success": true,
    "message": "Account Retrieved successfully",
    "data": {
      "identity": {
        "name": "Phoebe Buffay",
        "nuban": "06*****4"
      },
      "receipt": {
        "status": true,
        "msg": "Receipt has been successfully created",
        "data": {
          "receipt": {
            "charge_breakdown": {
              "vat": 0
            },
            "breakdown": {
              "billable_product": {
                "effective_credits": 0,
                "credits": 1.2,
                "status": true,
                "addon_products": [],
                "product": "identity"
              },
              "discount": 0,
              "billable_products": [
                {
                  "effective_cost": 0,
                  "cost": 1.2,
                  "status": true,
                  "addon_products": [],
                  "_id": "1530ef70eef4f5003ca8276a",
                  "archived": false,
                  "product": "identity"
                }
              ],
              "source": "api",
              "limit": "3"
            },
            "billingStatus": true,
            "paid": true,
            "method": "wallet",
            "charge": 0.7,
            "wallet_balance": 2079.1,
            "addons": [],
            "_id": "1530ef70eef4f5003ca82769",
            "plan_term": "prepaid",
            "owner": "1da6358130a943486f33dced",
            "type": "api-call",
            "billable_product": "identity",
            "currency": "Okra Credits",
            "record": "1530ef6deef4f5003ca82756",
            "customer": "1530edc5c58381003baf71ff",
            "current_project": "1ff62b99aea7a57a5c3baa01",
            "billable_service": "nuban-name-verify",
            "created_at": "2023-10-19T08:57:20.447Z",
            "last_updated": "2023-10-19T08:57:20.447Z"
          }
        }
      }
    }
  }
]

Example of a success response for the NUBAN name verify operation.

post

Search for identity

This operation enables you to retrieve an already verified user’s identity profile using their NIN, BVN, NUBAN, identity record ID, or customer ID.

- When searching for an identity profile, you must use at least one request parameter.
- The base server URL for this endpoint is https://identity-api.okra.ng/v2/

bvnstring

The user's BVN.

Example
"22165416979"
nubanstring

The user's NUBAN.

Example
"0000014579"
ninstring

National Identification Number (NIN) issued by Nigeria's National Identity Management Commission (NIMC).

Example
"97340343221"
idstring

The unique ID of an identity record.

Example
"140afb3ddecee700130acbc4"
customerstring

The unique ID of a customer.

Example
"140afb3ddecee700130acbc4"

Responses

Request examples

{
  "bvn": "22165416979",
  "nuban": "0000014579",
  "nin": "97340343221",
  "id": "140afb3ddecee700130acbc4",
  "customer": "140afb3ddecee700130acbc4"
}

Response examples

OK

[
  {
    "success": true,
    "message": "Identity Retrieved successfully",
    "data": {
      "identity": {
        "name": "John Peters",
        "nuban": "0007673912"
      },
      "receipt": {
        "owner": "1d9288ea182d3d000cb7c486",
        "record": "16b4e083716570a15764c8cf",
        "customer": "16b1333219759508ce42564b",
        "billingStatus": true,
        "paid": true,
        "type": "api-call",
        "method": "wallet",
        "plan_term": "prepaid",
        "charge": 0.14,
        "charge_breakdown": {
          "vat": 0
        },
        "wallet_balance": 76.9800000000001,
        "currency": "Okra Credits",
        "addons": [],
        "billable_product": "identity",
        "billable_service": "nuban-name-verify",
        "breakdown": {
          "discount": 0,
          "billable_product": {
            "product": "identity",
            "effective_credits": 0,
            "credits": 0.14,
            "status": true,
            "addon_products": []
          },
          "billable_products": [
            {
              "product": "identity",
              "effective_cost": 0,
              "cost": 0.14,
              "status": true,
              "addon_products": [],
              "_id": "16b4e083716570a15764c8ec"
            }
          ],
          "source": "api",
          "limit": 24
        },
        "current_project": "147894a51ae7fdc703bcaaa6",
        "_id": "16b4e083716570a15764c8eb",
        "created_at": "2024-08-08T15:13:07.690Z",
        "last_updated": "2024-08-08T15:13:07.690Z"
      }
    }
  }
]

Example of a success response for the Search identity operation.

Was this page helpful?