• Identity API

Deprecated endpoints

These are the deprecated endpoints from the previous version of Okra's Identity API.

post

Get identity by id

This operation enables you to retrieve an already verified user’s identity profile using the identity profile's record ID.

idstring

required

The unique ID of an identity record.

Example
"140afb3ddecee700130acbc4"

Responses

Request examples

{
  "id": "140afb3ddecee700130acbc4"
}

Response examples

OK

[
  {
    "status": "success",
    "message": "Identity retrieved successfully",
    "data": {
      "pagination": {
        "totalDocs": 1,
        "limit": 20,
        "hasPrevPage": false,
        "hasNextPage": false,
        "page": 1,
        "totalPages": 1,
        "pagingCounter": 1,
        "prevPage": null,
        "nextPage": null
      },
      "identity": [
        {
          "id": "6424acd0f58ff40013c7899e",
          "firstname": "OLUWATOBI",
          "middlename": "UFUOMA",
          "lastname": "JOSEPH",
          "fullname": "OLUWATOBI UFUOMA JOSEPH",
          "bvn": null,
          "customer": {
            "_id": "6424acd03bd4390012d6b050",
            "name": "OLUWATOBI UFUOMA JOSEPH"
          },
          "verification_country": "NG",
          "env": "production",
          "created_at": "2023-03-29T21:25:36.229Z",
          "aliases": [],
          "phone": [],
          "email": [],
          "address": [
            "21A GOLDEN PARK ESTATE SANGOTEDO, LAG, Nigeria"
          ],
          "next_of_kins": [],
          "nin": null,
          "photo_id": []
        }
      ]
    }
  }
]

Example of a success response for the get identity by ID operation.

post

Get identity by BVN

This operation enables you to retrieve an already verified user’s identity profile using their BVN.

bvnstring

required

The user's BVN.

Responses

Request examples

{
  "bvn": "string"
}

Response examples

OK

{
  "status": "success",
  "message": "Identity retrieved successfully",
  "data": {
    "id": "644acc50924488ad38676348",
    "firstname": "Fusuyi",
    "middlename": "Micheal",
    "lastname": "Tobi",
    "fullname": "Fusuyi Micheal Tobi",
    "dob": "1989-04-16",
    "bvn": "22165416979",
    "gender": "Male",
    "customer": {
      "_id": "6424c0638d3bc1046d4b0929",
      "name": "Fusuyi Micheal Tobi"
    },
    "verification_country": "NG",
    "created_at": "2023-04-27T19:26:07.519Z",
    "aliases": [],
    "phone": [
      "08038811523"
    ],
    "email": [],
    "address": [
      "23 Fusho Street king house Lagos"
    ],
    "nationality": "Nigeria",
    "lga_of_origin": "Ogbomosho North",
    "lga_of_residence": "Lagos Mainland",
    "state_of_origin": "Oyo State",
    "state_of_residence": "Lagos State",
    "marital_status": "Single",
    "next_of_kins": [],
    "nin": "97340343221",
    "photo_id": [
      {
        "url": "https://djrzfsrexmrry.cloudfront.net/MjIxNj.png",
        "image_type": "bvn_photo"
      }
    ],
    "enrollment": {
      "bank": "050",
      "branch": "100 Eng Macaulay",
      "registration_date": "Invalid Date"
    }
  }
}

Example of a success response for the get identity by BVN operation.

post

Get identity by NUBAN

This operation enables you to retrieve an already verified user’s identity profile using their NUBAN.

bankstring

required

The unique ID of a bank. Visit Okra's Coverage page for the list of bank IDs.

Example
"5d6fe57a4099cc4b210bbeb4"
nubanstring

required

The user's NUBAN.

Example
"0114542453"

Responses

Request examples

{
  "bank": "5d6fe57a4099cc4b210bbeb4",
  "nuban": "0114542453"
}

Response examples

OK

{
  "status": "success",
  "message": "Identity retrieved successfully",
  "data": {
    "id": "644acc50924488ad38676348",
    "firstname": "Fusuyi",
    "middlename": "Micheal",
    "lastname": "Tobi",
    "fullname": "Fusuyi Micheal Tobi",
    "dob": "1989-04-16",
    "bvn": "22165416979",
    "gender": "Male",
    "customer": {
      "_id": "6424c0638d3bc1046d4b0929",
      "name": "Fusuyi Micheal Tobi"
    },
    "verification_country": "NG",
    "created_at": "2023-04-27T19:26:07.519Z",
    "aliases": [],
    "phone": [
      "08038811523"
    ],
    "email": [],
    "address": [
      "23 Fusho Street king house Lagos"
    ],
    "nationality": "Nigeria",
    "lga_of_origin": "Ogbomosho North",
    "lga_of_residence": "Lagos Mainland",
    "state_of_origin": "Oyo State",
    "state_of_residence": "Lagos State",
    "marital_status": "Single",
    "next_of_kins": [],
    "nin": "97340343221",
    "photo_id": [
      {
        "url": "https://djrzfsrexmrry.cloudfront.net/MjIxNj.png",
        "image_type": "bvn_photo"
      }
    ],
    "enrollment": {
      "bank": "050",
      "branch": "100 Eng Macaulay",
      "registration_date": "Invalid Date"
    }
  }
}

Example of a success response for the get identity by NUBAN operation.

post

Get identity by NIN

This operation enables you to retrieve an already verified user’s identity profile using their NIN.

ninstring

required

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

Responses

Request examples

{
  "nin": "string"
}

Response examples

OK

{
  "status": "success",
  "message": "Identity retrieved successfully",
  "data": {
    "id": "644acc50924488ad38676348",
    "firstname": "Fusuyi",
    "middlename": "Micheal",
    "lastname": "Tobi",
    "fullname": "Fusuyi Micheal Tobi",
    "dob": "1989-04-16",
    "gender": "Male",
    "customer": {
      "_id": "6424c0638d3bc1046d4b0929",
      "name": "Fusuyi Micheal Tobi"
    },
    "verification_country": "NG",
    "created_at": "2023-04-27T19:26:07.519Z",
    "aliases": [],
    "phone": [
      "08038811523"
    ],
    "email": [],
    "address": [
      "23 Fusho Street king house Lagos"
    ],
    "nationality": "Nigeria",
    "lga_of_origin": "Ogbomosho North",
    "lga_of_residence": "Lagos Mainland",
    "state_of_origin": "Oyo State",
    "state_of_residence": "Lagos State",
    "marital_status": "Single",
    "next_of_kins": [],
    "nin": "97340343221",
    "photo_id": [
      {
        "url": "https://djrzfsrexmrry.cloudfront.net/MjIxNj.png",
        "image_type": "bvn_photo"
      }
    ],
    "enrollment": {
      "bank": "",
      "branch": "",
      "registration_date": "2024-03-20"
    }
  }
}

Example of a success response for the get identity by NIN operation.

post

Get identity by Phone Number

This operation enables you to retrieve an already verified user’s identity profile using their Phone Number.

phonestring

required

Phone number used to register for National Identification Number (NIN) issued by Nigeria's National Identity Management Commission (NIMC).

Responses

Request examples

{
  "phone": "string"
}

Response examples

OK

{
  "status": "success",
  "message": "Identity retrieved successfully",
  "data": {
    "id": "644acc50924488ad38676348",
    "firstname": "Fusuyi",
    "middlename": "Micheal",
    "lastname": "Tobi",
    "fullname": "Fusuyi Micheal Tobi",
    "dob": "1989-04-16",
    "gender": "Male",
    "customer": {
      "_id": "6424c0638d3bc1046d4b0929",
      "name": "Fusuyi Micheal Tobi"
    },
    "verification_country": "NG",
    "created_at": "2023-04-27T19:26:07.519Z",
    "aliases": [],
    "phone": [
      "08038811523"
    ],
    "email": [],
    "address": [
      "23 Fusho Street king house Lagos"
    ],
    "nationality": "Nigeria",
    "lga_of_origin": "Ogbomosho North",
    "lga_of_residence": "Lagos Mainland",
    "state_of_origin": "Oyo State",
    "state_of_residence": "Lagos State",
    "marital_status": "Single",
    "next_of_kins": [],
    "nin": "97340343221",
    "photo_id": [
      {
        "url": "https://djrzfsrexmrry.cloudfront.net/MjIxNj.png",
        "image_type": "bvn_photo"
      }
    ],
    "enrollment": {
      "bank": "",
      "branch": "",
      "registration_date": "2024-03-20"
    }
  }
}

Example of a success response for the get identity by NIN operation.

post

Get identity by customer

This operation enables you to retrieve an already verified user’s identity profiles using their customer ID.

customerstring

required

The unique ID of a customer.

Example
"140afb3ddecee700130acbc4"

Responses

Request examples

{
  "customer": "140afb3ddecee700130acbc4"
}

Response examples

OK

[
  {
    "status": "success",
    "message": "Identity retrieved successfully",
    "data": {
      "pagination": {
        "totalDocs": 2,
        "limit": 20,
        "hasPrevPage": false,
        "hasNextPage": false,
        "page": 1,
        "totalPages": 1,
        "pagingCounter": 1,
        "prevPage": null,
        "nextPage": null
      },
      "identity": [
        {
          "id": "64256211f58ff40013c789a4",
          "firstname": "ICONIC",
          "middlename": "LIVE",
          "lastname": "LTD",
          "fullname": "ICONIC LIVE SHOWBIZ PRODUCTION LTD",
          "bvn": null,
          "customer": {
            "_id": "6424b4263bd4390012d6b193",
            "name": "ICONIC LIVE SHOWBIZ PRODUCTION LTD"
          },
          "verification_country": "NG",
          "env": "production",
          "created_at": "2023-03-30T10:18:57.874Z",
          "aliases": [],
          "phone": [],
          "email": [],
          "address": [],
          "next_of_kins": [],
          "rc_number": null,
          "nin": null,
          "photo_id": []
        },
        {
          "id": "6424b426f58ff40013c7899f",
          "firstname": "ICONIC",
          "middlename": "LIVE",
          "lastname": "LTD",
          "fullname": "ICONIC LIVE SHOWBIZ PRODUCTION LTD",
          "bvn": null,
          "customer": {
            "_id": "6424b4263bd4390012d6b193",
            "name": "ICONIC LIVE SHOWBIZ PRODUCTION LTD"
          },
          "verification_country": "NG",
          "env": "production",
          "created_at": "2023-03-29T21:56:54.385Z",
          "aliases": [],
          "phone": [],
          "email": [],
          "address": [],
          "next_of_kins": [],
          "rc_number": null,
          "nin": null,
          "photo_id": []
        }
      ]
    }
  }
]

Example of a success response for the get identity by customer ID operation.

post

Get identity by date

This operation enables you to retrieve identity profiles for all users in a given date range. The dates you specify in your request filter results based on each identity profile's created_at value.

fromstring

required

Use this parameter to return identity profiles that were created after this date. The value should follow the standard YYYY-MM-DD ISO-8601 format.

Example
"2023-07-01"
tostring

required

Use this parameter to return identity profiles that were created before this date. The value should follow the standard YYYY-MM-DD ISO-8601 format.

Example
"2023-07-10"

Responses

Request examples

{
  "from": "2023-07-01",
  "to": "2023-07-10"
}

Response examples

OK

[
  {
    "status": "success",
    "message": "Identity retrieved successfully",
    "data": {
      "pagination": {
        "totalDocs": 10,
        "limit": 20,
        "hasPrevPage": false,
        "hasNextPage": false,
        "page": 1,
        "totalPages": 1,
        "pagingCounter": 1,
        "prevPage": null,
        "nextPage": null
      },
      "identity": [
        {
          "id": "64256211f58ff40013c789a4",
          "firstname": "ICONIC",
          "middlename": "LIVE",
          "lastname": "LTD",
          "fullname": "ICONIC LIVE SHOWBIZ PRODUCTION LTD",
          "bvn": null,
          "customer": {
            "_id": "6424b4263bd4390012d6b193",
            "name": "ICONIC LIVE SHOWBIZ PRODUCTION LTD"
          },
          "verification_country": "NG",
          "env": "production",
          "created_at": "2023-03-30T10:18:57.874Z",
          "aliases": [],
          "phone": [],
          "email": [],
          "address": [],
          "next_of_kins": [],
          "rc_number": null,
          "nin": null,
          "photo_id": []
        },
        {
          "id": "64255c2cf58ff40013c789a3",
          "firstname": "ICONIC",
          "middlename": "LIVE",
          "lastname": ".",
          "fullname": "ICONIC LIVE SHOWBIZ PRODUCTIO  -999- .",
          "bvn": "22260518297",
          "customer": {
            "_id": "64255c2c3bd4390012d6bca6",
            "name": "ICONIC LIVE SHOWBIZ PRODUCTIO  -999- ."
          },
          "verification_country": "NG",
          "env": "production",
          "created_at": "2023-03-30T09:53:48.270Z",
          "aliases": [],
          "phone": [],
          "email": [],
          "address": [],
          "next_of_kins": [],
          "rc_number": null,
          "nin": null,
          "photo_id": []
        },
        {
          "id": "64255791f58ff40013c789a2",
          "firstname": "Netface",
          "middlename": "",
          "lastname": "Netface",
          "fullname": "Netface",
          "dob": "1992-10-27",
          "bvn": "22181798075",
          "customer": {
            "_id": "6424ac533bd4390012d6b016",
            "name": "Netface"
          },
          "verification_country": "NG",
          "env": "production",
          "created_at": "2023-03-30T09:34:09.350Z",
          "aliases": [],
          "phone": [],
          "email": [],
          "address": [
            "2 Adewole Kuku Street, Lekki Phase 1, Lagos"
          ],
          "next_of_kins": [],
          "rc_number": null,
          "nin": null,
          "photo_id": []
        },
        {
          "id": "64254e4bf58ff40013c789a1",
          "firstname": "ICONIC",
          "middlename": "LIVE",
          "lastname": "LTD",
          "fullname": "ICONIC LIVE SHOWBIZ PRODUCTIONS LTD",
          "bvn": null,
          "customer": {
            "_id": "64254e4b3bd4390012d6b971",
            "name": "ICONIC LIVE SHOWBIZ PRODUCTIONS LTD"
          },
          "verification_country": "NG",
          "env": "production",
          "created_at": "2023-03-30T08:54:35.202Z",
          "aliases": [],
          "phone": [],
          "email": [],
          "address": [],
          "next_of_kins": [],
          "rc_number": null,
          "nin": null,
          "photo_id": []
        },
        {
          "id": "6425160af58ff40013c789a0",
          "firstname": "OLUWATOBI",
          "middlename": "U.",
          "lastname": "JOSEPH",
          "fullname": "OLUWATOBI U. JOSEPH",
          "bvn": "22260518297",
          "customer": {
            "_id": "6425160a3bd4390012d6b365",
            "name": "OLUWATOBI U. JOSEPH"
          },
          "verification_country": "NG",
          "env": "production",
          "created_at": "2023-03-30T04:54:34.679Z",
          "aliases": [
            "undefined undefined"
          ],
          "phone": [],
          "email": [],
          "address": [],
          "next_of_kins": [],
          "score": "0",
          "nin": null,
          "photo_id": []
        },
        {
          "id": "6424c063cb979f08037e1e4f",
          "bvn": "22151247211",
          "customer": {
            "_id": "6424c0638d3bc1046d4b0929"
          },
          "created_at": "2023-03-29T22:49:07.007Z",
          "aliases": [],
          "phone": [],
          "email": [],
          "address": [],
          "next_of_kins": [],
          "photo_id": []
        },
        {
          "id": "6424b426f58ff40013c7899f",
          "firstname": "ICONIC",
          "middlename": "LIVE",
          "lastname": "LTD",
          "fullname": "ICONIC LIVE SHOWBIZ PRODUCTION LTD",
          "bvn": null,
          "customer": {
            "_id": "6424b4263bd4390012d6b193",
            "name": "ICONIC LIVE SHOWBIZ PRODUCTION LTD"
          },
          "verification_country": "NG",
          "env": "production",
          "created_at": "2023-03-29T21:56:54.385Z",
          "aliases": [],
          "phone": [],
          "email": [],
          "address": [],
          "next_of_kins": [],
          "rc_number": null,
          "nin": null,
          "photo_id": []
        },
        {
          "id": "6424acd0f58ff40013c7899e",
          "firstname": "OLUWATOBI",
          "middlename": "UFUOMA",
          "lastname": "JOSEPH",
          "fullname": "OLUWATOBI UFUOMA JOSEPH",
          "bvn": null,
          "customer": {
            "_id": "6424acd03bd4390012d6b050",
            "name": "OLUWATOBI UFUOMA JOSEPH"
          },
          "verification_country": "NG",
          "env": "production",
          "created_at": "2023-03-29T21:25:36.229Z",
          "aliases": [],
          "phone": [],
          "email": [],
          "address": [
            "21A GOLDEN PARK ESTATE SANGOTEDO, LAG, Nigeria"
          ],
          "next_of_kins": [],
          "nin": null,
          "photo_id": []
        },
        {
          "id": "6424ac53f58ff40013c7899d",
          "firstname": "Netface",
          "middlename": "",
          "lastname": "Netface",
          "fullname": "Netface",
          "dob": "1992-10-27",
          "bvn": "22181798075",
          "customer": {
            "_id": "6424ac533bd4390012d6b016",
            "name": "Netface"
          },
          "verification_country": "NG",
          "env": "production",
          "created_at": "2023-03-29T21:23:31.867Z",
          "aliases": [],
          "phone": [],
          "email": [],
          "address": [
            "2 Adewole Kuku Street, Lekki Phase 1, Lagos"
          ],
          "next_of_kins": [],
          "rc_number": null,
          "nin": null,
          "photo_id": []
        },
        {
          "id": "642459f1e855cc965b7cb32a",
          "firstname": "Edison",
          "middlename": "Maduabuchukwu",
          "lastname": "Obodo",
          "fullname": "Edison Maduabuchukwu Obodo",
          "dob": "1988-03-14",
          "bvn": "22188789177",
          "gender": "M",
          "customer": {
            "_id": "6424825c8e3711362e9ef0cd",
            "name": "Edison Maduabuchukwu Obodo"
          },
          "verification_country": "NG",
          "env": "production",
          "created_at": "2023-03-29T15:32:01.450Z",
          "aliases": [
            "Edison Obodo",
            "undefined undefined"
          ],
          "phone": [
            "08054916090"
          ],
          "email": [],
          "address": [
            "4 Akanni Bashorun Lekki Road 14 Lekki Phase 1 Lagos"
          ],
          "nationality": null,
          "lga_of_origin": null,
          "lga_of_residence": null,
          "state_of_origin": null,
          "state_of_residence": null,
          "marital_status": null,
          "next_of_kins": [],
          "score": "0",
          "nin": null,
          "photo_id": [],
          "enrollment": {
            "bank": null,
            "branch": null,
            "registration_date": "2023-03-30"
          }
        }
      ]
    }
  }
]

Example of a success response for the get identity by date operation.

post

Get identity by customer date

This operation enables you to retrieve an already verified user’s identity profiles using their customer ID and a given date range. The dates you specify in your request filter results based on each identity profile's created_at value.

fromstring

required

Use this parameter to return identity profiles that were created after this date. The value should follow the standard YYYY-MM-DD ISO-8601 format.

tostring

required

Use this parameter to return identity profiles that were created before this date. The value should follow the standard YYYY-MM-DD ISO-8601 format.

customerint

required

The unique ID of a customer.

Format
int32
Example
1234567890

Responses

Request examples

{
  "from": "string",
  "to": "string",
  "customer": 1234567890
}

Response examples

OK

[
  {
    "status": "success",
    "message": "Identity retrieved successfully",
    "data": {
      "pagination": {
        "totalDocs": 1,
        "limit": 20,
        "hasPrevPage": false,
        "hasNextPage": false,
        "page": 1,
        "totalPages": 1,
        "pagingCounter": 1,
        "prevPage": null,
        "nextPage": null
      },
      "identity": [
        {
          "id": "6424acd0f58ff40013c7899e",
          "firstname": "OLUWATOBI",
          "middlename": "UFUOMA",
          "lastname": "JOSEPH",
          "fullname": "OLUWATOBI UFUOMA JOSEPH",
          "bvn": null,
          "customer": {
            "_id": "6424acd03bd4390012d6b050",
            "name": "OLUWATOBI UFUOMA JOSEPH"
          },
          "verification_country": "NG",
          "env": "production",
          "created_at": "2023-03-29T21:25:36.229Z",
          "aliases": [],
          "phone": [],
          "email": [],
          "address": [
            "21A GOLDEN PARK ESTATE SANGOTEDO, LAG, Nigeria"
          ],
          "next_of_kins": [],
          "nin": null,
          "photo_id": []
        }
      ]
    }
  }
]

Example of a success response for the get identity by customer and date operation.

post

Verify customer

This operation enables you to retrieve 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.

customerstring

required

The unique ID of a customer.

Example
"140afb3ddecee700130acbc4"

Responses

Request examples

{
  "customer": "140afb3ddecee700130acbc4"
}

Response examples

OK

[
  {
    "status": "success",
    "message": "Identity successfully retrieved",
    "data": {
      "id": "63ff2cfcddec1a7e578447fa",
      "firstname": "Raimot",
      "middlename": "Olorunwa",
      "lastname": "Hassan",
      "fullname": "Raimot Olorunwa Hassan",
      "dob": "1999-05-20",
      "bvn": "22701486899",
      "gender": "Female",
      "customer": "63ff2cfc03f5d6017604fba6",
      "verification_country": "NG",
      "aliases": [],
      "phone": [
        "09160040731"
      ],
      "email": [],
      "address": [
        "33 Omu Town Omu Ijebu"
      ],
      "nationality": "Nigeria",
      "lga_of_origin": "Odogbolu",
      "lga_of_residence": "Odogbolu",
      "state_of_origin": "Ogun State",
      "state_of_residence": "Ogun State",
      "marital_status": "Single",
      "next_of_kins": [],
      "nin": null,
      "photo_id": [
        {
          "url": "https://dv7b45oo546j4.cloudfront.net/MjI3MDE0ODY4OTk%3D.png",
          "image_type": "bvn_photo"
        }
      ],
      "enrollment": {
        "bank": "044",
        "branch": null,
        "registration_date": "2022-07-04"
      },
      "record": "63ff2d196f13820012ae09bb",
      "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": "63ff2d1d6f13820012ae09c1",
            "plan_term": "postpaid",
            "owner": "5da6358130a943486f33dced",
            "type": "customer-verify",
            "currency": "NGN",
            "plan": "payg",
            "plan_type": "5da478aa9ce2295ff32a5131",
            "record": "63ff2d196f13820012ae09bb",
            "created_at": "2023-03-01T10:46:53.242Z",
            "last_updated": "2023-03-01T10:46:53.242Z",
            "__v": 0
          }
        }
      }
    }
  }
]

Example of a success response for the customer 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.

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.

successboolean

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

no_bvnboolean

Use this setting in the Sandbox environment to force the API to return a user's BVN in the response payload. When true, the API does not return the user's BVN, enabling you to test the scenario when the users BVN is not attached to their NUBAN. When false, the API returns the user's BVN.

Responses

Request examples

{
  "nuban": "string",
  "bank": "string",
  "success": true,
  "no_bvn": 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

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).

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.

Responses

Request examples

{
  "nin": "string",
  "refresh": true,
  "testing": 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.

Was this page helpful?