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

post /identity/getById

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

HTTP bearer bearer

id

string

required

The unique ID of an identity record.

Example
"140afb3ddecee700130acbc4"

Request

{
  "id": "140afb3ddecee700130acbc4"
}

Response

Examples Schema

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.

Bad request error.

{
  "status": "error"
}

Unauthorized - This error occurs when your request does not have valid authentication credentials for the requested resource.

{
  "name": "APIError",
  "status": "error",
  "message": "Unauthorized - You don't have access to this route.",
  "extra": null
}

Unprocessable Entity error - occurs when the API cannot validate the contents of your request.

{
  "status": "error",
  "message": "bvn[1] length must be less than or equal to 11 characters long.",
  "data": {}
}

Service unavailable - This error indicates that the API is not ready to handle the request.

{
  "status": "error",
  "message": "Our data source has returned a timeout response. Please retry the request."
}

status

string

message

string

data

object (data)

pagination

object (pagination)

totalDocs

int

i32

The total number of results that match the request.

limit

int

i32

Returns the value of the limit parameter. Limit sets the number of results that the API returns in a single page. If you do not specify a value for limit, the API will limit the response to 10 results per page.

hasPrevPage

boolean

Shows when a previous page of results is available. This field always returns true when the value of page is greater than 1.

hasNextPage

boolean

Shows when a next page of results is available. When true, Okra recommends that you make subsequent requests to retrieve the following pages of results.

page

int

i32

Returns the number of the current page. For example, if you set page to 1 in your request, the API will return the first page of results in the response.

totalPages

int

i32

The total number of pages that the API returns.

pagingCounter

int

i32

The index number of the first result on the current page. For example, if the value of page is 2 and limit is set to 10, then pagingCounter returns 11.

prevPage

string or null

The number of previous result pages. If the value of page is 1 and there is no previous page, the value of prevPage is null.

nextPage

string or null

The number of following result pages. Each page consists of up to 100 items. If there are not enough results for an additional page, the value is null.

identity

array[object (Identity)]

The identity object

Identity

object (Identity)

id

string

Okra's unique identifier used to reference the identity profile.

firstname

string

The first name of the account owner.

middlename

string

The middlename name of the account owner.

lastname

string

The last name of the account owner.

fullname

string

The full name of the owner, as provided by the bank.

dob

string

The account owner's date of birth, as provided by the bank.

bvn

string

The bank verification number of the user.

gender

string

The gender of the account owner.

customer

object (customer)

_id

string

The unique identifier that references the user.

name

string

The user’s full name.

verification_country

string

The country where the user's identity was verified.

env

string

The API environment that returned the data.

aliases

array[string]

An array of alternative names.

string

phone

array[string]

The phone number of the user.

string

email

array[string]

The account owner's registered email address.

string

address

array[string]

The accounts owners registered address.

string

nationality

string

The user's nationality.

lga_of_origin

string

The local government area where the user originates from.

lga_of_residence

string

The local government area of the user's place of residence.

state_of_origin

string

The state where the user originates from.

state_of_residence

string

The state where the user has residence.

marital_status

string or null

The marital status of the account owner.

mothers_maiden

string or null

The maiden name of the account owner's mother.

next_of_kins

array[string]

The account owner person's closest living relative(s), as returned by the bank

string

score

number

This field shows how complete the user's identity profile is. score is calculated based on how many important data points, such as address and email, are returned by the user's bank. The resulting score is an integer between 0 and 100.

Example
"80"

watch_listed

boolean

This field shows whether the BVN connected to this identity profile is listed by the Central Bank of Nigeria for suspected fraudulent activities.

dti

number

The API calculates the debt-to-Income (DTI) ratio for a user, which is the percentage of total debt relative to total income, from the time the user’s account is created.

rc_number

string or null

The Registered Company Number of the account owner, as returned by the bank.

nin

string or null

The national identification number of the user.

photo_id

object (photo_id)

Example
{ "_id": "", "url": "", "image_type": "", "bank": "" }

_id

string

Okra's unique ID for the photo.

url

string

The url pointing to the image.

image_type

string

The image type format of the photo

bank

string

created_at

string

Indicates the date when the data point was first created. The timestamp value follows the ISO 8601 format.

last_updated

string or null

Indicates the date when the data point was last updated. The timestamp value follows the ISO 8601 format. The API only returns this field when the data point already exists.

enrollment

object (enrollment)

Lists details about the bank where the user is enrolled.

bank

string

The bank that recorded the user's identity.

branch

string

The branch of the bank that recorded the user's identity.

registration_date

string

The date when the bank created the user's identity record. The timestamp value follows the ISO 8601 format.

Example
"2017-06-13"

status

string

The status of your request.

message

string

A short description of the error.

data

string or null

total

string or null

name

string or null

Returns the type of the error.

status

string

The status of your request.

message

string

A short description of the error.

extra

string or null

status

string

The status of your request.

message

string

A short description of the error.

data

string or null

status

string

The status of your request.

message

string

A short description of the error.

Get identity by BVN

post /identity/getByBvn

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

HTTP bearer bearer

bvn

string

required

The user's BVN.

Request

{
  "bvn": "string"
}

Response

Examples Schema

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.

Bad request error.

{
  "status": "error",
  "message": "There is no identity available for this bvn",
  "data": {}
}

Unauthorized - This error occurs when your request does not have valid authentication credentials for the requested resource.

{
  "name": "APIError",
  "status": "error",
  "message": "Unauthorized - You don't have access to this route.",
  "extra": null
}

Unprocessable Entity error - occurs when the API cannot validate the contents of your request.

{
  "status": "error",
  "message": "bvn is required",
  "data": {}
}

Service unavailable - This error indicates that the API is not ready to handle the request.

{
  "status": "error",
  "message": "Our data source has returned a timeout response. Please retry the request."
}

status

string

message

string

data

object (data)

id

string

Okra's unique identifier used to reference the identity profile.

firstname

string

The first name of the account owner.

middlename

string

The middlename name of the account owner.

lastname

string

The last name of the account owner.

fullname

string

The full name of the owner, as provided by the bank.

dob

string

The account owner's date of birth, as provided by the bank.

bvn

string

The bank verification number of the user.

gender

string

The gender of the account owner.

customer

object (customer)

_id

string

The unique identifier that references the user.

name

string

The user’s full name.

verification_country

string

The country where the user's identity was verified.

env

string

The API environment that returned the data.

aliases

array[string]

An array of alternative names.

string

phone

array[string]

The phone number of the user.

string

email

array[string]

The account owner's registered email address.

string

address

array[string]

The accounts owners registered address.

string

nationality

string

The user's nationality.

lga_of_origin

string

The local government area where the user originates from.

lga_of_residence

string

The local government area of the user's place of residence.

state_of_origin

string

The state where the user originates from.

state_of_residence

string

The state where the user has residence.

marital_status

string or null

The marital status of the account owner.

mothers_maiden

string or null

The maiden name of the account owner's mother.

next_of_kins

array[string]

The account owner person's closest living relative(s), as returned by the bank

string

score

number

This field shows how complete the user's identity profile is. score is calculated based on how many important data points, such as address and email, are returned by the user's bank. The resulting score is an integer between 0 and 100.

Example
"80"

watch_listed

boolean

This field shows whether the BVN connected to this identity profile is listed by the Central Bank of Nigeria for suspected fraudulent activities.

dti

number

The API calculates the debt-to-Income (DTI) ratio for a user, which is the percentage of total debt relative to total income, from the time the user’s account is created.

rc_number

string or null

The Registered Company Number of the account owner, as returned by the bank.

nin

string or null

The national identification number of the user.

photo_id

object (photo_id)

Example
{ "_id": "", "url": "", "image_type": "", "bank": "" }

_id

string

Okra's unique ID for the photo.

url

string

The url pointing to the image.

image_type

string

The image type format of the photo

bank

string

created_at

string

Indicates the date when the data point was first created. The timestamp value follows the ISO 8601 format.

last_updated

string or null

Indicates the date when the data point was last updated. The timestamp value follows the ISO 8601 format. The API only returns this field when the data point already exists.

enrollment

object (enrollment)

Lists details about the bank where the user is enrolled.

bank

string

The bank that recorded the user's identity.

branch

string

The branch of the bank that recorded the user's identity.

registration_date

string

The date when the bank created the user's identity record. The timestamp value follows the ISO 8601 format.

Example
"2017-06-13"

status

string

The status of your request.

message

string

A short description of the error.

data

string or null

name

string or null

Returns the type of the error.

status

string

The status of your request.

message

string

A short description of the error.

extra

string or null

status

string

The status of your request.

message

string

A short description of the error.

data

string or null

status

string

The status of your request.

message

string

A short description of the error.

Get identity by NUBAN

post /identity/getByNuban

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

HTTP bearer bearer

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"

Request

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

Response

Examples Schema

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.

Bad request error

[
  {
    "status": "string",
    "message": "string",
    "data": "string"
  }
]

Unauthorized - This error occurs when your request does not have valid authentication credentials for the requested resource.

{
  "name": "APIError",
  "status": "error",
  "message": "Unauthorized - You don't have access to this route.",
  "extra": null
}

Unprocessable Entity error - occurs when the API cannot validate the contents of your request.

{
  "status": "error",
  "message": "`nuban` is a required input and bank is required",
  "data": {}
}

Service unavailable - This error indicates that the API is not ready to handle the request.

{
  "status": "error",
  "message": "Our data source has returned a timeout response. Please retry the request."
}

status

string

message

string

data

object (data)

id

string

Okra's unique identifier used to reference the identity profile.

firstname

string

The first name of the account owner.

middlename

string

The middlename name of the account owner.

lastname

string

The last name of the account owner.

fullname

string

The full name of the owner, as provided by the bank.

dob

string

The account owner's date of birth, as provided by the bank.

bvn

string

The bank verification number of the user.

gender

string

The gender of the account owner.

customer

object (customer)

_id

string

The unique identifier that references the user.

name

string

The user’s full name.

verification_country

string

The country where the user's identity was verified.

env

string

The API environment that returned the data.

aliases

array[string]

An array of alternative names.

string

phone

array[string]

The phone number of the user.

string

email

array[string]

The account owner's registered email address.

string

address

array[string]

The accounts owners registered address.

string

nationality

string

The user's nationality.

lga_of_origin

string

The local government area where the user originates from.

lga_of_residence

string

The local government area of the user's place of residence.

state_of_origin

string

The state where the user originates from.

state_of_residence

string

The state where the user has residence.

marital_status

string or null

The marital status of the account owner.

mothers_maiden

string or null

The maiden name of the account owner's mother.

next_of_kins

array[string]

The account owner person's closest living relative(s), as returned by the bank

string

score

number

This field shows how complete the user's identity profile is. score is calculated based on how many important data points, such as address and email, are returned by the user's bank. The resulting score is an integer between 0 and 100.

Example
"80"

watch_listed

boolean

This field shows whether the BVN connected to this identity profile is listed by the Central Bank of Nigeria for suspected fraudulent activities.

dti

number

The API calculates the debt-to-Income (DTI) ratio for a user, which is the percentage of total debt relative to total income, from the time the user’s account is created.

rc_number

string or null

The Registered Company Number of the account owner, as returned by the bank.

nin

string or null

The national identification number of the user.

photo_id

object (photo_id)

Example
{ "_id": "", "url": "", "image_type": "", "bank": "" }

_id

string

Okra's unique ID for the photo.

url

string

The url pointing to the image.

image_type

string

The image type format of the photo

bank

string

created_at

string

Indicates the date when the data point was first created. The timestamp value follows the ISO 8601 format.

last_updated

string or null

Indicates the date when the data point was last updated. The timestamp value follows the ISO 8601 format. The API only returns this field when the data point already exists.

enrollment

object (enrollment)

Lists details about the bank where the user is enrolled.

bank

string

The bank that recorded the user's identity.

branch

string

The branch of the bank that recorded the user's identity.

registration_date

string

The date when the bank created the user's identity record. The timestamp value follows the ISO 8601 format.

Example
"2017-06-13"

Bad request error

array[Any Of]

Any Of

Bad request error

object (Bad request error)

This error occurs when the requested NUBAN does not exist.

status

string

The status of your request.

message

string

A short description of the error.

data

string or null

Bad request error

object (Bad request error)

This error occurs when there is no identity profile available for the customer associated with the requested NUBAN.

status

string

The status of your request.

message

string

A short description of the error.

data

string or null

name

string or null

Returns the type of the error.

status

string

The status of your request.

message

string

A short description of the error.

extra

string or null

status

string

The status of your request.

message

string

A short description of the error.

data

string or null

status

string

The status of your request.

message

string

A short description of the error.

Get identity by customer

post /identity/getByCustomer

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

HTTP bearer bearer

customer

string

required

The unique ID of a customer.

Example
"140afb3ddecee700130acbc4"

Request

{
  "customer": "140afb3ddecee700130acbc4"
}

Response

Examples Schema

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.

Bad request error.

{
  "status": "error"
}

Unauthorized - This error occurs when your request does not have valid authentication credentials for the requested resource.

{
  "name": "APIError",
  "status": "error",
  "message": "Unauthorized - You don't have access to this route.",
  "extra": null
}

Unprocessable Entity error - occurs when the API cannot validate the contents of your request.

{
  "status": "error",
  "message": "bvn[1] length must be less than or equal to 11 characters long.",
  "data": {}
}

Service unavailable - This error indicates that the API is not ready to handle the request.

{
  "status": "error",
  "message": "Our data source has returned a timeout response. Please retry the request."
}

status

string

message

string

data

object (data)

pagination

object (pagination)

totalDocs

int

i32

The total number of results that match the request.

limit

int

i32

Returns the value of the limit parameter. Limit sets the number of results that the API returns in a single page. If you do not specify a value for limit, the API will limit the response to 10 results per page.

hasPrevPage

boolean

Shows when a previous page of results is available. This field always returns true when the value of page is greater than 1.

hasNextPage

boolean

Shows when a next page of results is available. When true, Okra recommends that you make subsequent requests to retrieve the following pages of results.

page

int

i32

Returns the number of the current page. For example, if you set page to 1 in your request, the API will return the first page of results in the response.

totalPages

int

i32

The total number of pages that the API returns.

pagingCounter

int

i32

The index number of the first result on the current page. For example, if the value of page is 2 and limit is set to 10, then pagingCounter returns 11.

prevPage

string or null

The number of previous result pages. If the value of page is 1 and there is no previous page, the value of prevPage is null.

nextPage

string or null

The number of following result pages. Each page consists of up to 100 items. If there are not enough results for an additional page, the value is null.

identity

array[object (Identity)]

The identity object

Identity

object (Identity)

id

string

Okra's unique identifier used to reference the identity profile.

firstname

string

The first name of the account owner.

middlename

string

The middlename name of the account owner.

lastname

string

The last name of the account owner.

fullname

string

The full name of the owner, as provided by the bank.

dob

string

The account owner's date of birth, as provided by the bank.

bvn

string

The bank verification number of the user.

gender

string

The gender of the account owner.

customer

object (customer)

_id

string

The unique identifier that references the user.

name

string

The user’s full name.

verification_country

string

The country where the user's identity was verified.

env

string

The API environment that returned the data.

aliases

array[string]

An array of alternative names.

string

phone

array[string]

The phone number of the user.

string

email

array[string]

The account owner's registered email address.

string

address

array[string]

The accounts owners registered address.

string

nationality

string

The user's nationality.

lga_of_origin

string

The local government area where the user originates from.

lga_of_residence

string

The local government area of the user's place of residence.

state_of_origin

string

The state where the user originates from.

state_of_residence

string

The state where the user has residence.

marital_status

string or null

The marital status of the account owner.

mothers_maiden

string or null

The maiden name of the account owner's mother.

next_of_kins

array[string]

The account owner person's closest living relative(s), as returned by the bank

string

score

number

This field shows how complete the user's identity profile is. score is calculated based on how many important data points, such as address and email, are returned by the user's bank. The resulting score is an integer between 0 and 100.

Example
"80"

watch_listed

boolean

This field shows whether the BVN connected to this identity profile is listed by the Central Bank of Nigeria for suspected fraudulent activities.

dti

number

The API calculates the debt-to-Income (DTI) ratio for a user, which is the percentage of total debt relative to total income, from the time the user’s account is created.

rc_number

string or null

The Registered Company Number of the account owner, as returned by the bank.

nin

string or null

The national identification number of the user.

photo_id

object (photo_id)

Example
{ "_id": "", "url": "", "image_type": "", "bank": "" }

_id

string

Okra's unique ID for the photo.

url

string

The url pointing to the image.

image_type

string

The image type format of the photo

bank

string

created_at

string

Indicates the date when the data point was first created. The timestamp value follows the ISO 8601 format.

last_updated

string or null

Indicates the date when the data point was last updated. The timestamp value follows the ISO 8601 format. The API only returns this field when the data point already exists.

enrollment

object (enrollment)

Lists details about the bank where the user is enrolled.

bank

string

The bank that recorded the user's identity.

branch

string

The branch of the bank that recorded the user's identity.

registration_date

string

The date when the bank created the user's identity record. The timestamp value follows the ISO 8601 format.

Example
"2017-06-13"

status

string

The status of your request.

message

string

A short description of the error.

data

string or null

total

string or null

name

string or null

Returns the type of the error.

status

string

The status of your request.

message

string

A short description of the error.

extra

string or null

status

string

The status of your request.

message

string

A short description of the error.

data

string or null

status

string

The status of your request.

message

string

A short description of the error.

Get identity by date

post /identity/getByDate

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.

HTTP bearer bearer

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"

Request

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

Response

Examples Schema

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.

Bad request error.

{
  "status": "error"
}

Unauthorized - This error occurs when your request does not have valid authentication credentials for the requested resource.

{
  "name": "APIError",
  "status": "error",
  "message": "Unauthorized - You don't have access to this route.",
  "extra": null
}

Unprocessable Entity error - occurs when the API cannot validate the contents of your request.

{
  "status": "error",
  "message": "bvn[1] length must be less than or equal to 11 characters long.",
  "data": {}
}

Service unavailable - This error indicates that the API is not ready to handle the request.

{
  "status": "error",
  "message": "Our data source has returned a timeout response. Please retry the request."
}

status

string

message

string

data

object (data)

pagination

object (pagination)

totalDocs

int

i32

The total number of results that match the request.

limit

int

i32

Returns the value of the limit parameter. Limit sets the number of results that the API returns in a single page. If you do not specify a value for limit, the API will limit the response to 10 results per page.

hasPrevPage

boolean

Shows when a previous page of results is available. This field always returns true when the value of page is greater than 1.

hasNextPage

boolean

Shows when a next page of results is available. When true, Okra recommends that you make subsequent requests to retrieve the following pages of results.

page

int

i32

Returns the number of the current page. For example, if you set page to 1 in your request, the API will return the first page of results in the response.

totalPages

int

i32

The total number of pages that the API returns.

pagingCounter

int

i32

The index number of the first result on the current page. For example, if the value of page is 2 and limit is set to 10, then pagingCounter returns 11.

prevPage

string or null

The number of previous result pages. If the value of page is 1 and there is no previous page, the value of prevPage is null.

nextPage

string or null

The number of following result pages. Each page consists of up to 100 items. If there are not enough results for an additional page, the value is null.

identity

array[object (Identity)]

The identity object

Identity

object (Identity)

id

string

Okra's unique identifier used to reference the identity profile.

firstname

string

The first name of the account owner.

middlename

string

The middlename name of the account owner.

lastname

string

The last name of the account owner.

fullname

string

The full name of the owner, as provided by the bank.

dob

string

The account owner's date of birth, as provided by the bank.

bvn

string

The bank verification number of the user.

gender

string

The gender of the account owner.

customer

object (customer)

_id

string

The unique identifier that references the user.

name

string

The user’s full name.

verification_country

string

The country where the user's identity was verified.

env

string

The API environment that returned the data.

aliases

array[string]

An array of alternative names.

string

phone

array[string]

The phone number of the user.

string

email

array[string]

The account owner's registered email address.

string

address

array[string]

The accounts owners registered address.

string

nationality

string

The user's nationality.

lga_of_origin

string

The local government area where the user originates from.

lga_of_residence

string

The local government area of the user's place of residence.

state_of_origin

string

The state where the user originates from.

state_of_residence

string

The state where the user has residence.

marital_status

string or null

The marital status of the account owner.

mothers_maiden

string or null

The maiden name of the account owner's mother.

next_of_kins

array[string]

The account owner person's closest living relative(s), as returned by the bank

string

score

number

This field shows how complete the user's identity profile is. score is calculated based on how many important data points, such as address and email, are returned by the user's bank. The resulting score is an integer between 0 and 100.

Example
"80"

watch_listed

boolean

This field shows whether the BVN connected to this identity profile is listed by the Central Bank of Nigeria for suspected fraudulent activities.

dti

number

The API calculates the debt-to-Income (DTI) ratio for a user, which is the percentage of total debt relative to total income, from the time the user’s account is created.

rc_number

string or null

The Registered Company Number of the account owner, as returned by the bank.

nin

string or null

The national identification number of the user.

photo_id

object (photo_id)

Example
{ "_id": "", "url": "", "image_type": "", "bank": "" }

_id

string

Okra's unique ID for the photo.

url

string

The url pointing to the image.

image_type

string

The image type format of the photo

bank

string

created_at

string

Indicates the date when the data point was first created. The timestamp value follows the ISO 8601 format.

last_updated

string or null

Indicates the date when the data point was last updated. The timestamp value follows the ISO 8601 format. The API only returns this field when the data point already exists.

enrollment

object (enrollment)

Lists details about the bank where the user is enrolled.

bank

string

The bank that recorded the user's identity.

branch

string

The branch of the bank that recorded the user's identity.

registration_date

string

The date when the bank created the user's identity record. The timestamp value follows the ISO 8601 format.

Example
"2017-06-13"

status

string

The status of your request.

message

string

A short description of the error.

data

string or null

total

string or null

name

string or null

Returns the type of the error.

status

string

The status of your request.

message

string

A short description of the error.

extra

string or null

status

string

The status of your request.

message

string

A short description of the error.

data

string or null

status

string

The status of your request.

message

string

A short description of the error.

Get identity by customer date

post /identity/getByCustomerDate

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.

HTTP bearer bearer

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

i32

required

The unique ID of a customer.

Example
1234567890

Request

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

Response

Examples Schema

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.

Bad request error.

{
  "status": "error"
}

Unauthorized - This error occurs when your request does not have valid authentication credentials for the requested resource.

{
  "name": "APIError",
  "status": "error",
  "message": "Unauthorized - You don't have access to this route.",
  "extra": null
}

Unprocessable Entity error - occurs when the API cannot validate the contents of your request.

{
  "status": "error",
  "message": "bvn[1] length must be less than or equal to 11 characters long.",
  "data": {}
}

Service unavailable - This error indicates that the API is not ready to handle the request.

{
  "status": "error",
  "message": "Our data source has returned a timeout response. Please retry the request."
}

status

string

message

string

data

object (data)

pagination

object (pagination)

totalDocs

int

i32

The total number of results that match the request.

limit

int

i32

Returns the value of the limit parameter. Limit sets the number of results that the API returns in a single page. If you do not specify a value for limit, the API will limit the response to 10 results per page.

hasPrevPage

boolean

Shows when a previous page of results is available. This field always returns true when the value of page is greater than 1.

hasNextPage

boolean

Shows when a next page of results is available. When true, Okra recommends that you make subsequent requests to retrieve the following pages of results.

page

int

i32

Returns the number of the current page. For example, if you set page to 1 in your request, the API will return the first page of results in the response.

totalPages

int

i32

The total number of pages that the API returns.

pagingCounter

int

i32

The index number of the first result on the current page. For example, if the value of page is 2 and limit is set to 10, then pagingCounter returns 11.

prevPage

string or null

The number of previous result pages. If the value of page is 1 and there is no previous page, the value of prevPage is null.

nextPage

string or null

The number of following result pages. Each page consists of up to 100 items. If there are not enough results for an additional page, the value is null.

identity

array[object (Identity)]

The identity object

Identity

object (Identity)

id

string

Okra's unique identifier used to reference the identity profile.

firstname

string

The first name of the account owner.

middlename

string

The middlename name of the account owner.

lastname

string

The last name of the account owner.

fullname

string

The full name of the owner, as provided by the bank.

dob

string

The account owner's date of birth, as provided by the bank.

bvn

string

The bank verification number of the user.

gender

string

The gender of the account owner.

customer

object (customer)

_id

string

The unique identifier that references the user.

name

string

The user’s full name.

verification_country

string

The country where the user's identity was verified.

env

string

The API environment that returned the data.

aliases

array[string]

An array of alternative names.

string

phone

array[string]

The phone number of the user.

string

email

array[string]

The account owner's registered email address.

string

address

array[string]

The accounts owners registered address.

string

nationality

string

The user's nationality.

lga_of_origin

string

The local government area where the user originates from.

lga_of_residence

string

The local government area of the user's place of residence.

state_of_origin

string

The state where the user originates from.

state_of_residence

string

The state where the user has residence.

marital_status

string or null

The marital status of the account owner.

mothers_maiden

string or null

The maiden name of the account owner's mother.

next_of_kins

array[string]

The account owner person's closest living relative(s), as returned by the bank

string

score

number

This field shows how complete the user's identity profile is. score is calculated based on how many important data points, such as address and email, are returned by the user's bank. The resulting score is an integer between 0 and 100.

Example
"80"

watch_listed

boolean

This field shows whether the BVN connected to this identity profile is listed by the Central Bank of Nigeria for suspected fraudulent activities.

dti

number

The API calculates the debt-to-Income (DTI) ratio for a user, which is the percentage of total debt relative to total income, from the time the user’s account is created.

rc_number

string or null

The Registered Company Number of the account owner, as returned by the bank.

nin

string or null

The national identification number of the user.

photo_id

object (photo_id)

Example
{ "_id": "", "url": "", "image_type": "", "bank": "" }

_id

string

Okra's unique ID for the photo.

url

string

The url pointing to the image.

image_type

string

The image type format of the photo

bank

string

created_at

string

Indicates the date when the data point was first created. The timestamp value follows the ISO 8601 format.

last_updated

string or null

Indicates the date when the data point was last updated. The timestamp value follows the ISO 8601 format. The API only returns this field when the data point already exists.

enrollment

object (enrollment)

Lists details about the bank where the user is enrolled.

bank

string

The bank that recorded the user's identity.

branch

string

The branch of the bank that recorded the user's identity.

registration_date

string

The date when the bank created the user's identity record. The timestamp value follows the ISO 8601 format.

Example
"2017-06-13"

status

string

The status of your request.

message

string

A short description of the error.

data

string or null

total

string or null

name

string or null

Returns the type of the error.

status

string

The status of your request.

message

string

A short description of the error.

extra

string or null

status

string

The status of your request.

message

string

A short description of the error.

data

string or null

status

string

The status of your request.

message

string

A short description of the error.

Verify customer

post /products/kyc/customer-verify

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.

HTTP bearer bearer

customer

string

required

The unique ID of a customer.

Example
"140afb3ddecee700130acbc4"

Request

{
  "customer": "140afb3ddecee700130acbc4"
}

Response

Examples Schema

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.

Bad request error.

{
  "status": "error"
}

Unauthorized - This error occurs when your request does not have valid authentication credentials for the requested resource.

{
  "name": "APIError",
  "status": "error",
  "message": "Unauthorized - You don't have access to this route.",
  "extra": null
}

Unprocessable Entity error - occurs when the API cannot validate the contents of your request.

{
  "status": "error",
  "message": "bvn[1] length must be less than or equal to 11 characters long.",
  "data": {}
}

Service unavailable - This error indicates that the API is not ready to handle the request.

{
  "status": "error",
  "message": "Our data source has returned a timeout response. Please retry the request."
}

status

string

message

string

data

object (data)

id

string or null

Okra's unique identifier used to reference the identity profile.

firstname

string

The first name of the account owner.

middlename

string

The middlename name of the account owner.

lastname

string

The last name of the account owner.

fullname

string

The full name of the owner, as provided by the bank.

dob

string

The account owner's date of birth, as provided by the bank.

bvn

string

The user's bank verification number.

gender

string

The gender of the account owner.

customer

string

Okra's unique identifier used to reference the user that the identity profile belongs to.

verification_country

string

The country where the user's identity was verified.

aliases

array[string]

An array of alternative names.

string

phone

array[string]

The phone number of the user.

string

email

array[string]

The account owner's registered email address.

string

address

array[string]

The accounts owners registered address.

string

nationality

string

The user's nationality.

lga_of_origin

string

The local government area where the user originates from.

lga_of_residence

string

The local government area of the user's place of residence.

state_of_origin

string

The state where the user originates from.

state_of_residence

string

The state where the user has residence.

marital_status

string or null

The marital status of the account owner.

next_of_kins

array[string]

The account owner person's closest living relative(s) as returned by the bank

string

nin

string or null

The national identification number of the user.

photo_id

object (photo_id)

Example
{ "_id": "", "url": "", "image_type": "", "bank": "" }

_id

string

Okra's unique ID for the photo.

url

string

The url pointing to the image.

image_type

string

The image type format of the photo

bank

string

enrollment

object (enrollment)

Lists details about the bank where the user is enrolled.

bank

string

The bank that recorded the user's identity.

branch

string

The branch of the bank that recorded the user's identity.

registration_date

string

The date when the bank created the user's identity record. The timestamp value follows the ISO 8601 format.

Example
"2017-06-13"

record

string

uuid

When the Identity API processes the identity profile of a user, it creates a new record. This field returns the record ID of the new record.

receipt

object (receipt)

status

string

The status of your request.

msg

string

The response message.

Example
"Receipt has been successfully created"

data

object (data)

adjustment

object (adjustment)

receipts

array[string]

Used during receipt adjustment. Returns an array of the receipts that Okra created in order to adjust this receipt.

string

charge_breakdown

object (charge_breakdown)

vat

int

i32

Returns the amount of value added tax charged on any deposit.

breakdown

object (breakdown)

Lists details about the charge for using a specific product.

discount

int

i32

Returns the amount of discount applied on the product costs.

billable_product

object (billable_product)

Returns a charge breakdown for the product billed in your Okra app implementation.

effective_credits

int

i32

The amount that is charged after discount.

credits

number

The amount that is charged before discount.

status

boolean

Returns the status of the product usage.

addon_products

array[string]

Returns an array of any additional products used.

string

product

string

Returns the name of the product that is billed, for example identity.

billable_products

array[object]

Returns a charge breakdown for the product billed in your Okra app implementation.

object

Returns a charge breakdown for the product billed in your Okra app implementation.

archived

boolean

Shows whether this record is archived.

_id

string

The unique ID of a receipt record.

effective_credits

int

i32

The amount that is charged after discount.

cost

number

The amount that is charged before discount.

status

boolean

Returns the status of the product usage.

addon_products

array[string]

Returns an array of any additional products used.

string

product

string

Returns the name of the product that is billed, for example identity.

source

string

The device or platform the record was carried on.

Enum
  • link
  • android
  • ios
  • rn-ios
  • rn-android
  • ionic
  • wordpress
  • vue
  • flutter
  • angular
  • integration
  • seeder
  • laravel
  • react
  • ussd
  • api
  • feature-phone

limit

string

Limit set on transaction if product is included

billingStatus

boolean

Shows whether the billing was successful.

adjusted

string or null

date

Returns the date when the receipt was adjusted.

Example
"2023-06-10"

adjusted_receipt

boolean

Shows whether a receipt was adjusted as a result of a refund or for overcharging.

adjusted_type

string or null

Shows the reason why a receipt was adjusted.

  • duplicate-unbilled means that the receipt is a duplicate of another receipt. Duplicate receipts should only be billed once.
  • validated means that receipt is verified to be a real API product call.
Enum
  • duplicate-unbilled
  • validated

paid

boolean

Shows whether the bill was paid for.

payment_amount

number

Returns the amount that is paid via the Payments solution.

method

string

Returns the billing method used in the receipt.

Enum
  • card
  • wallet
  • bank_transfer

charge

int

i32

Returns the amount that is charged.

wallet_balance

number

Shows the current credit balance available in a wallet.

addons

array[string]

Returns the list of add-on services that Okra charged for.

string

Enum
  • reconciliation
  • premium-support

archived

boolean

Shows whether this record is archived.

micro_lending

boolean

Shows whether the micro-lending pricing scheme was used.

ussd_pricing

boolean

Shows whether the USSD pricing scheme was used.

ussd_pricing_discount

int

i32

Returns any discount that was used on the USSD pricing.

micro_lending_discount

int

i32

Returns any discount that was used on the micro-lending pricing.

_id

string

The unique ID of a receipt record.

term

string

The payment term.

Enum
  • prepaid
  • postpaid

owner

string

The name of the account owner.

type

string

Returns the type of receipt. The API returns:

  • deposit when you top up your wallet.
  • api-call when you use paid endpoints. Check out the API reference for the list of paid endpoints.
  • withdrawal when you withdraw from your wallet.
  • plan-fee for subscription fee debits.
  • refund when you receive a refund on your wallet.
Enum
  • deposit
  • api-call
  • withdrawal
  • plan-fee
  • refund

currency

string

Returns the currency used in the bill.

Enum
  • NGN
  • USD
  • GBP
  • EUR
  • Okra Credits

record

string

Returns the record ID for the creation of this receipt.

created_at

string

Indicates the date and time when the receipt was created. The timestamp value follows the ISO 8601 format, for example 2022-11-20.

last_updated

string

Indicates the date and time when the receipt was last updated. The timestamp value follows the ISO 8601 format, for example 2022-11-20.

status

string

The status of your request.

message

string

A short description of the error.

data

string or null

total

string or null

name

string or null

Returns the type of the error.

status

string

The status of your request.

message

string

A short description of the error.

extra

string or null

status

string

The status of your request.

message

string

A short description of the error.

data

string or null

status

string

The status of your request.

message

string

A short description of the error.

Nuban Verify

post /products/kyc/nuban-verify

This operation enables you to retrieve a user’s KYC profile using their Nigerian Uniform Bank Account Number.

HTTP bearer bearer

nuban

string

required

The user's NUBAN.

bank

string

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.

refresh

boolean

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 NUBAN, the API creates a new one. If you set this parameter to false, the API creates a new identity profile based on the requested NUBAN.

testing

boolean

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.

success

boolean

Use this setting together with testing to test success and failure scenarios. When true, this setting forces a success response for the NUBAN verify operation. When false, it forces a failure response.

Request

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

Response

Examples Schema

OK

[
  {
    "status": "success",
    "message": "Identity retrieved successfully",
    "data": {
      "identity": {
        "id": "10af0add86f59d2ba42812a6",
        "firstname": "Peter",
        "middlename": "Daniel",
        "lastname": "Jones",
        "fullname": "Peter Daniel Jones",
        "dob": "1993-03-10",
        "bvn": "11160518297",
        "gender": "Male",
        "customer": "115d4cf777f4ef001ddb5c6e",
        "verification_country": "NG",
        "env": "production",
        "aliases": [
          "Peter Jones",
          "P D Jones"
        ],
        "phone": [
          "09011150567"
        ],
        "email": [
          "peter-jones@live-test.com"
        ],
        "address": [
          "111 A Golden Park Estate Sangotedo Ajah",
          "111 A Golden Park Est Lekki Epe Expressway Ogidan Lagos Lagos"
        ],
        "nationality": "Nigeria",
        "lga_of_origin": "Eti Osa",
        "lga_of_residence": "Eti Osa",
        "state_of_origin": "Lagos State",
        "state_of_residence": "Lagos State",
        "marital_status": "Single",
        "next_of_kins": [],
        "score": "66",
        "nin": null,
        "photo_id": [
          {
            "url": "https://dv7b45oo546j4.cloudfront.net/MjIyNjA1MTgyO12321.png",
            "image_type": "bvn_photo"
          }
        ],
        "enrollment": {
          "bank": "044",
          "branch": "Victoria Island Ajose Adeogun",
          "registration_date": "2013-11-28"
        }
      },
      "account": null,
      "bank": {
        "_id": "5d6fe57a4099cc4b210bbec0",
        "slug": "access-bank"
      },
      "customer": "115d4cf777f4ef001ddb5c6e",
      "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": "159e9150bc40f10046f1e833",
                  "archived": false,
                  "product": "identity"
                }
              ],
              "source": "api",
              "limit": "3"
            },
            "billingStatus": true,
            "paid": true,
            "method": "wallet",
            "charge": 1.2,
            "wallet_balance": 9950.8,
            "addons": [],
            "_id": "159e9150bc40f10046f1e832",
            "plan_term": "prepaid",
            "owner": "5da6358130a943486f33dced",
            "type": "api-call",
            "billable_product": "identity",
            "currency": "Okra Credits",
            "record": "159e9150bc40f10046f1e819",
            "customer": "115d4cf777f4ef001ddb5c6e",
            "current_project": "1ff62b99aea7a57a5c3baa01",
            "billable_service": "nuban-verify",
            "created_at": "2024-01-10T12:45:04.212Z",
            "last_updated": "2024-01-10T12:45:04.212Z"
          }
        }
      }
    }
  }
]

Example of a success response for the NUBAN verify operation.

No content

Empty response

Bad request error.

[
  {
    "status": "error",
    "message": "Could not match bank identifier {slug_value} with a valid bank",
    "data": null,
    "total": null
  }
]

Returned when the bank slug you provided is invalid.

[
  {
    "status": "error",
    "message": "Could not match the nuban account to a valid identity. Please try to use BVN in order to find the identity.",
    "data": {}
  }
]

Returned when the NUBAN you provided is not tied to a valid identity profile.

[
  {
    "status": "error",
    "message": "Invalid identity, please try again in 15 minutes.",
    "data": {}
  }
]

Returned when you request the same invalid bank slug, or invalid NUBAN within 15 minutes after your previous request.

Unauthorized - This error occurs when your request does not have valid authentication credentials for the requested resource.

{
  "name": "APIError",
  "status": "error",
  "message": "Unauthorized - You don't have access to this route.",
  "extra": null
}

Unprocessable Entity error - occurs when the API cannot validate the contents of your request.

{
  "status": "error",
  "message": "bvn[1] length must be less than or equal to 11 characters long.",
  "data": {}
}

Service unavailable - This error indicates that the API is not ready to handle the request.

{
  "status": "error",
  "message": "Our data source has returned a timeout response. Please retry the request."
}

status

string

message

string

data

object (data)

identity

object (identity)

id

string or null

Okra's unique identifier used to reference the identity profile.

firstname

string

The first name of the account owner.

middlename

string

The middlename name of the account owner.

lastname

string

The last name of the account owner.

fullname

string

The full name of the owner, as provided by the bank.

dob

string

The account owner's date of birth, as provided by the bank.

bvn

string

The user's bank verification number.

gender

string

The gender of the account owner.

customer

string

Okra's unique identifier used to reference the user that the identity profile belongs to.

verification_country

string

The country where the user's identity was verified.

aliases

array[string]

An array of alternative names.

string

phone

array[string]

The phone number of the user.

string

email

array[string]

The account owner's registered email address.

string

address

array[string]

The accounts owners registered address.

string

nationality

string

The user's nationality.

lga_of_origin

string

The local government area where the user originates from.

lga_of_residence

string

The local government area of the user's place of residence.

state_of_origin

string

The state where the user originates from.

state_of_residence

string

The state where the user has residence.

marital_status

string or null

The marital status of the account owner.

next_of_kins

array[string]

The account owner person's closest living relative(s) as returned by the bank

string

nin

string or null

The national identification number of the user.

photo_id

object (photo_id)

Example
{ "_id": "", "url": "", "image_type": "", "bank": "" }

_id

string

Okra's unique ID for the photo.

url

string

The url pointing to the image.

image_type

string

The image type format of the photo

bank

string

enrollment

object (enrollment)

Lists details about the bank where the user is enrolled.

bank

string

The bank that recorded the user's identity.

branch

string

The branch of the bank that recorded the user's identity.

registration_date

string

The date when the bank created the user's identity record. The timestamp value follows the ISO 8601 format.

Example
"2017-06-13"

record

string

uuid

When the Identity API processes the identity profile of a user, it creates a new record. This field returns the record ID of the new record.

receipt

object (receipt)

status

string

The status of your request.

msg

string

The response message.

Example
"Receipt has been successfully created"

data

object (data)

adjustment

object (adjustment)

receipts

array[string]

Used during receipt adjustment. Returns an array of the receipts that Okra created in order to adjust this receipt.

string

charge_breakdown

object (charge_breakdown)

vat

int

i32

Returns the amount of value added tax charged on any deposit.

breakdown

object (breakdown)

Lists details about the charge for using a specific product.

discount

int

i32

Returns the amount of discount applied on the product costs.

billable_product

object (billable_product)

Returns a charge breakdown for the product billed in your Okra app implementation.

effective_credits

int

i32

The amount that is charged after discount.

credits

number

The amount that is charged before discount.

status

boolean

Returns the status of the product usage.

addon_products

array[string]

Returns an array of any additional products used.

string

product

string

Returns the name of the product that is billed, for example identity.

billable_products

array[object]

Returns a charge breakdown for the product billed in your Okra app implementation.

object

Returns a charge breakdown for the product billed in your Okra app implementation.

archived

boolean

Shows whether this record is archived.

_id

string

The unique ID of a receipt record.

effective_credits

int

i32

The amount that is charged after discount.

cost

number

The amount that is charged before discount.

status

boolean

Returns the status of the product usage.

addon_products

array[string]

Returns an array of any additional products used.

string

product

string

Returns the name of the product that is billed, for example identity.

source

string

The device or platform the record was carried on.

Enum
  • link
  • android
  • ios
  • rn-ios
  • rn-android
  • ionic
  • wordpress
  • vue
  • flutter
  • angular
  • integration
  • seeder
  • laravel
  • react
  • ussd
  • api
  • feature-phone

limit

string

Limit set on transaction if product is included

billingStatus

boolean

Shows whether the billing was successful.

adjusted

string or null

date

Returns the date when the receipt was adjusted.

Example
"2023-06-10"

adjusted_receipt

boolean

Shows whether a receipt was adjusted as a result of a refund or for overcharging.

adjusted_type

string or null

Shows the reason why a receipt was adjusted.

  • duplicate-unbilled means that the receipt is a duplicate of another receipt. Duplicate receipts should only be billed once.
  • validated means that receipt is verified to be a real API product call.
Enum
  • duplicate-unbilled
  • validated

paid

boolean

Shows whether the bill was paid for.

payment_amount

number

Returns the amount that is paid via the Payments solution.

method

string

Returns the billing method used in the receipt.

Enum
  • card
  • wallet
  • bank_transfer

charge

int

i32

Returns the amount that is charged.

wallet_balance

number

Shows the current credit balance available in a wallet.

addons

array[string]

Returns the list of add-on services that Okra charged for.

string

Enum
  • reconciliation
  • premium-support

archived

boolean

Shows whether this record is archived.

micro_lending

boolean

Shows whether the micro-lending pricing scheme was used.

ussd_pricing

boolean

Shows whether the USSD pricing scheme was used.

ussd_pricing_discount

int

i32

Returns any discount that was used on the USSD pricing.

micro_lending_discount

int

i32

Returns any discount that was used on the micro-lending pricing.

_id

string

The unique ID of a receipt record.

term

string

The payment term.

Enum
  • prepaid
  • postpaid

owner

string

The name of the account owner.

type

string

Returns the type of receipt. The API returns:

  • deposit when you top up your wallet.
  • api-call when you use paid endpoints. Check out the API reference for the list of paid endpoints.
  • withdrawal when you withdraw from your wallet.
  • plan-fee for subscription fee debits.
  • refund when you receive a refund on your wallet.
Enum
  • deposit
  • api-call
  • withdrawal
  • plan-fee
  • refund

currency

string

Returns the currency used in the bill.

Enum
  • NGN
  • USD
  • GBP
  • EUR
  • Okra Credits

record

string

Returns the record ID for the creation of this receipt.

created_at

string

Indicates the date and time when the receipt was created. The timestamp value follows the ISO 8601 format, for example 2022-11-20.

last_updated

string

Indicates the date and time when the receipt was last updated. The timestamp value follows the ISO 8601 format, for example 2022-11-20.

account

string

The user's account ID.

bank

object (bank)

Returns information about the bank that holds the user's account.

_id

string

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.

slug

string

The unique human-readable slug used to identify the user's account holder bank. Visit Okra's Account data coverage page for the list of bank slugs.

customer

string

Okra's unique identifier used to reference the user that the identity profile belongs to.

record

string

uuid

When the Identity API processes the identity profile of a user, it creates a new record. This field returns the record ID of the new record.

receipt

object (receipt)

status

string

The status of your request.

msg

string

The response message.

Example
"Receipt has been successfully created"

data

object (data)

adjustment

object (adjustment)

receipts

array[string]

Used during receipt adjustment. Returns an array of the receipts that Okra created in order to adjust this receipt.

string

charge_breakdown

object (charge_breakdown)

vat

int

i32

Returns the amount of value added tax charged on any deposit.

breakdown

object (breakdown)

Lists details about the charge for using a specific product.

discount

int

i32

Returns the amount of discount applied on the product costs.

billable_product

object (billable_product)

Returns a charge breakdown for the product billed in your Okra app implementation.

effective_credits

int

i32

The amount that is charged after discount.

credits

number

The amount that is charged before discount.

status

boolean

Returns the status of the product usage.

addon_products

array[string]

Returns an array of any additional products used.

string

product

string

Returns the name of the product that is billed, for example identity.

billable_products

array[object]

Returns a charge breakdown for the product billed in your Okra app implementation.

object

Returns a charge breakdown for the product billed in your Okra app implementation.

archived

boolean

Shows whether this record is archived.

_id

string

The unique ID of a receipt record.

effective_credits

int

i32

The amount that is charged after discount.

cost

number

The amount that is charged before discount.

status

boolean

Returns the status of the product usage.

addon_products

array[string]

Returns an array of any additional products used.

string

product

string

Returns the name of the product that is billed, for example identity.

source

string

The device or platform the record was carried on.

Enum
  • link
  • android
  • ios
  • rn-ios
  • rn-android
  • ionic
  • wordpress
  • vue
  • flutter
  • angular
  • integration
  • seeder
  • laravel
  • react
  • ussd
  • api
  • feature-phone

limit

string

Limit set on transaction if product is included

billingStatus

boolean

Shows whether the billing was successful.

adjusted

string or null

date

Returns the date when the receipt was adjusted.

Example
"2023-06-10"

adjusted_receipt

boolean

Shows whether a receipt was adjusted as a result of a refund or for overcharging.

adjusted_type

string or null

Shows the reason why a receipt was adjusted.

  • duplicate-unbilled means that the receipt is a duplicate of another receipt. Duplicate receipts should only be billed once.
  • validated means that receipt is verified to be a real API product call.
Enum
  • duplicate-unbilled
  • validated

paid

boolean

Shows whether the bill was paid for.

payment_amount

number

Returns the amount that is paid via the Payments solution.

method

string

Returns the billing method used in the receipt.

Enum
  • card
  • wallet
  • bank_transfer

charge

int

i32

Returns the amount that is charged.

wallet_balance

number

Shows the current credit balance available in a wallet.

addons

array[string]

Returns the list of add-on services that Okra charged for.

string

Enum
  • reconciliation
  • premium-support

archived

boolean

Shows whether this record is archived.

micro_lending

boolean

Shows whether the micro-lending pricing scheme was used.

ussd_pricing

boolean

Shows whether the USSD pricing scheme was used.

ussd_pricing_discount

int

i32

Returns any discount that was used on the USSD pricing.

micro_lending_discount

int

i32

Returns any discount that was used on the micro-lending pricing.

_id

string

The unique ID of a receipt record.

term

string

The payment term.

Enum
  • prepaid
  • postpaid

owner

string

The name of the account owner.

type

string

Returns the type of receipt. The API returns:

  • deposit when you top up your wallet.
  • api-call when you use paid endpoints. Check out the API reference for the list of paid endpoints.
  • withdrawal when you withdraw from your wallet.
  • plan-fee for subscription fee debits.
  • refund when you receive a refund on your wallet.
Enum
  • deposit
  • api-call
  • withdrawal
  • plan-fee
  • refund

currency

string

Returns the currency used in the bill.

Enum
  • NGN
  • USD
  • GBP
  • EUR
  • Okra Credits

record

string

Returns the record ID for the creation of this receipt.

created_at

string

Indicates the date and time when the receipt was created. The timestamp value follows the ISO 8601 format, for example 2022-11-20.

last_updated

string

Indicates the date and time when the receipt was last updated. The timestamp value follows the ISO 8601 format, for example 2022-11-20.

No schema

status

string

The status of your request.

message

string

A short description of the error.

data

string or null

total

string or null

name

string or null

Returns the type of the error.

status

string

The status of your request.

message

string

A short description of the error.

extra

string or null

status

string

The status of your request.

message

string

A short description of the error.

data

string or null

status

string

The status of your request.

message

string

A short description of the error.

Nuban Name Verify

post /products/kyc/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.

HTTP bearer bearer

nuban

string

required

The user's NUBAN.

bank

string

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.

success

boolean

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_bvn

boolean

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.

Request

{
  "nuban": "string",
  "bank": "string",
  "success": true,
  "no_bvn": true
}

Response

Examples Schema

OK

[
  {
    "status": "success",
    "message": "Account Retrieved successfully",
    "data": {
      "identity": {
        "bvn": "222********0",
        "name": "Phoebe Buffay",
        "nuban": "06*****4",
        "isBvnVerified": true
      },
      "bank": {
        "_id": "5d6fe57a4099cc4b210bbec0",
        "slug": "access-bank"
      },
      "customer": "1530edc5c*****71ff",
      "record": [
        "1530ef6deef4f5003ca82756"
      ],
      "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