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.

Get identity by id

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

post /identity/getById
id string

required

The unique ID of an identity record.

Example
"140afb3ddecee700130acbc4"

Requests

{
  "id": "140afb3ddecee700130acbc4"
}

Responses

ExamplesSchema

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.

Get identity by BVN

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

post /identity/getByBvn
bvn string

required

The user's BVN.

Requests

{
  "bvn": "string"
}

Responses

ExamplesSchema

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.

Get identity by NUBAN

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

post /identity/getByNuban
bank string

required

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

Example
"5d6fe57a4099cc4b210bbeb4"
nuban string

required

The user's NUBAN.

Example
"0114542453"

Requests

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

Responses

ExamplesSchema

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.

Get identity by NIN

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

post /identity/getByNin
nin string

required

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

Requests

{
  "nin": "string"
}

Responses

ExamplesSchema

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.

Get identity by Phone Number

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

post /identity/getByPhone
phone string

required

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

Requests

{
  "phone": "string"
}

Responses

ExamplesSchema

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.

Get identity by customer

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

post /identity/getByCustomer
customer string

required

The unique ID of a customer.

Example
"140afb3ddecee700130acbc4"

Requests

{
  "customer": "140afb3ddecee700130acbc4"
}

Responses

ExamplesSchema

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.

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.

post /identity/getByDate
from string

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"
to string

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"

Requests

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

Responses

ExamplesSchema

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.

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.

post /identity/getByCustomerDate
from string

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.

to string

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.

customer int

required

The unique ID of a customer.

Format
i32
Example
1234567890

Requests

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

Responses

ExamplesSchema

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.