Identity
Download SpecThe 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.
id
string
required
The unique ID of an identity record.
- Example
- "140afb3ddecee700130acbc4"
bearer
Request
{
"id": "140afb3ddecee700130acbc4"
}Response
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.
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
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
The status of your request.
message
string
A short description of the error.
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.
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
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
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"
Get identity by BVN
This operation enables you to retrieve an already verified user’s identity profile using their BVN.
bvn
string
required
The user's BVN.
bearer
Request
{
"bvn": "string"
}Response
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.
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
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
The status of your request.
message
string
A short description of the error.
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.
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
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
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"
Get identity by NUBAN
This operation enables you to retrieve an already verified user’s identity profile using their NUBAN.
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"
bearer
Request
{
"bank": "5d6fe57a4099cc4b210bbeb4",
"nuban": "0114542453"
}Response
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.
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
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
The status of your request.
message
string
A short description of the error.
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
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
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
Get identity by NIN
This operation enables you to retrieve an already verified user’s identity profile using their NIN.
nin
string
required
National Identification Number (NIN) issued by Nigeria's National Identity Management Commission (NIMC).
bearer
Request
{
"nin": "string"
}Response
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.
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Bad request error.
{
"status": "error",
"message": "There is no identity available for this nin",
"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": "nin 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
The status of your request.
message
string
A short description of the error.
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.
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
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.
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
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
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"
Get identity by Phone Number
This operation enables you to retrieve an already verified user’s identity profile using their Phone Number.
phone
string
required
Phone number used to register for National Identification Number (NIN) issued by Nigeria's National Identity Management Commission (NIMC).
bearer
Request
{
"phone": "string"
}Response
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.
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Bad request error.
{
"status": "error",
"message": "There is no identity available for this phone number",
"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": "phone 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
The status of your request.
message
string
A short description of the error.
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.
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
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.
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
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
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"
Get identity by customer
This operation enables you to retrieve an already verified user’s identity profiles using their customer ID.
customer
string
required
The unique ID of a customer.
- Example
- "140afb3ddecee700130acbc4"
bearer
Request
{
"customer": "140afb3ddecee700130acbc4"
}Response
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.
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
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
The status of your request.
message
string
A short description of the error.
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.
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
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
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"
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.
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"
bearer
Request
{
"from": "2023-07-01",
"to": "2023-07-10"
}Response
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.
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
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
The status of your request.
message
string
A short description of the error.
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.
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
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
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"
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.
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
bearer
Request
{
"from": "string",
"to": "string",
"customer": 1234567890
}Response
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.
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
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
The status of your request.
message
string
A short description of the error.
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.
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
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
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"
Verify customer
This operation enables you to retrieve a user’s identity profile using their customer ID. Okra suggests using this operation for customers who already connected their accounts, but do not have a verified identity yet. This operation requires the user’s BVN to be available in the user’s profile.
customer
string
required
The unique ID of a customer.
- Example
- "140afb3ddecee700130acbc4"
bearer
Request
{
"customer": "140afb3ddecee700130acbc4"
}Response
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.
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
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
The status of your request.
message
string
A short description of the error.
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.
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
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
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-unbilledmeans that the receipt is a duplicate of another receipt. Duplicate receipts should only be billed once.validatedmeans 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:
depositwhen you top up your wallet.api-callwhen you use paid endpoints. Check out the API reference for the list of paid endpoints.withdrawalwhen you withdraw from your wallet.plan-feefor subscription fee debits.refundwhen 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.
Nuban Verify
This operation enables you to retrieve a user’s KYC profile using their Nigerian Uniform Bank Account Number.
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.
bearer
Request
{
"nuban": "string",
"bank": "string",
"refresh": true,
"testing": true,
"success": true
}Response
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.
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
No schema
No content
Empty response
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."
}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.
status
string
The status of your request.
message
string
A short description of the error.
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.
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
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
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-unbilledmeans that the receipt is a duplicate of another receipt. Duplicate receipts should only be billed once.validatedmeans 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:
depositwhen you top up your wallet.api-callwhen you use paid endpoints. Check out the API reference for the list of paid endpoints.withdrawalwhen you withdraw from your wallet.plan-feefor subscription fee debits.refundwhen 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-unbilledmeans that the receipt is a duplicate of another receipt. Duplicate receipts should only be billed once.validatedmeans 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:
depositwhen you top up your wallet.api-callwhen you use paid endpoints. Check out the API reference for the list of paid endpoints.withdrawalwhen you withdraw from your wallet.plan-feefor subscription fee debits.refundwhen 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.
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.
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.
bearer
Request
{
"nuban": "string",
"bank": "string",
"success": true,
"no_bvn": true
}Response
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",
"owner": "1da6358130a943486f33dced",
"type": "api-call",
"billable_product": "identity",
"currency": "Okra Credits",
"record": "1530ef6deef4f5003ca82756",
"customer": "1530edc5c58381003baf71ff",
"current_project": "1ff62b99aea7a57a5c3baa01",
"billable_service": "nuban-name-verify",
"created_at": "2023-10-19T08:57:20.447Z",
"last_updated": "2023-10-19T08:57:20.447Z"
}
}
}
}
}
]Example of a success response for the NUBAN name verify operation.
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
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
The status of your request.
message
string
A short description of the error.
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.
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
message
string
data
object (data)
identity
object (identity)
Returns information about the identity of the user.
name
string
The user's full name.
nuban
string
The user's NUBAN.
bvn
string
The user's BVN.
isBvnVerified
boolean
Shows whether the user's BVN has been already verified through the Identity API.
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
array[string]
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.
string
uuid
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-unbilledmeans that the receipt is a duplicate of another receipt. Duplicate receipts should only be billed once.validatedmeans 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:
depositwhen you top up your wallet.api-callwhen you use paid endpoints. Check out the API reference for the list of paid endpoints.withdrawalwhen you withdraw from your wallet.plan-feefor subscription fee debits.refundwhen 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.
NIN Verify
This operation enables you to to seamlessly verify user identities using their National Identification Number (NIN) issued by Nigeria's National Identity Management Commission (NIMC).
nin
string
required
National Identification Number (NIN) issued by Nigeria's National Identity Management Commission (NIMC).
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 NIN, the API creates a new one. If you set this parameter to false, the API creates a new identity profile based on the requested NIN.
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.
bearer
Request
{
"nin": "string",
"refresh": true,
"testing": true
}Response
OK
[
{
"status": "success",
"message": "Identity retrieved successfully",
"data": {
"identity": {
"id": "65f3150be125eda0985d87fd",
"firstname": "Ciroma",
"middlename": "Chukwuma",
"lastname": "Adekunle",
"fullname": "Ciroma Chukwuma Adekunle",
"dob": "1999-10-11",
"gender": "M",
"customer": "6424acd03bd4390012d6b050",
"env": "production",
"aliases": [],
"phone": [],
"email": [],
"address": [],
"nationality": null,
"lga_of_origin": null,
"lga_of_residence": null,
"state_of_origin": null,
"state_of_residence": null,
"marital_status": null,
"next_of_kins": [],
"nin": "12345678910",
"photo_id": [
{
"url": "https://djrzfsrexmrry.cloudfront.net/OTk2NTY2NzkyOTE%3D.png",
"image_type": "nin_photo"
}
],
"enrollment": {
"bank": null,
"branch": null,
"registration_date": "2024-03-14"
}
},
"customer": "6424acd03bd4390012d6b050",
"receipt": {
"status": true,
"msg": "Receipt has been successfully created",
"data": {
"receipt": {
"charge_breakdown": {
"vat": 0
},
"breakdown": {
"billable_product": {
"effective_credits": 0,
"credits": 0,
"status": true,
"addon_products": [],
"product": "identity"
},
"discount": 0,
"billable_products": [
{
"effective_cost": 0,
"cost": 0,
"status": true,
"addon_products": [],
"_id": "65f3159fab89f73ab2ae0d15",
"archived": false,
"product": "identity"
}
],
"source": "api",
"limit": "3"
},
"billingStatus": true,
"paid": true,
"method": "wallet",
"charge": 0,
"wallet_balance": 0,
"addons": [],
"_id": "65f3159fab89f73ab2ae0d14",
"plan_term": "prepaid",
"owner": "5d9288ea182d3d000cb7c486",
"type": "api-call",
"billable_product": "identity",
"currency": "Okra Credits",
"record": "65f3158aab89f73ab2ae0cfd",
"customer": "6424acd03bd4390012d6b050",
"current_project": "63daf1486a1489002fd4818d",
"billable_service": "nuban-verify",
"created_at": "2024-03-14T15:19:59.199Z",
"last_updated": "2024-03-14T15:19:59.199Z"
}
}
}
}
}
]Example of a success response for the NIN verify operation.
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
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
}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."
}Service unavailable - This error indicates that the API is not ready to handle the request.
{
"status": "error",
"message": "Something went wrong from our provider. Please try again later"
}Bad request error.
[
{
"status": "error",
"message": "The provided NIN does not match any identity at this point.",
"data": null,
"total": null
}
]Returned when the nin provider did not return a valid identity response
Unprocessable Entity error - occurs when the API cannot validate the contents of your request.
[
{
"status": "error",
"message": "nin length must be at least 11 characters long",
"data": null,
"total": null
}
]Returned when the nin provided does not meet the required character length.
status
string
The status of your request.
message
string
A short description of the error.
status
string
The status of your request.
message
string
A short description of the error.
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.
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
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.
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.
aliases
array[string]
An array of alternative names.
string
phone
array[string]
The phone number of the user.
string
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
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"
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-unbilledmeans that the receipt is a duplicate of another receipt. Duplicate receipts should only be billed once.validatedmeans 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:
depositwhen you top up your wallet.api-callwhen you use paid endpoints. Check out the API reference for the list of paid endpoints.withdrawalwhen you withdraw from your wallet.plan-feefor subscription fee debits.refundwhen 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-unbilledmeans that the receipt is a duplicate of another receipt. Duplicate receipts should only be billed once.validatedmeans 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:
depositwhen you top up your wallet.api-callwhen you use paid endpoints. Check out the API reference for the list of paid endpoints.withdrawalwhen you withdraw from your wallet.plan-feefor subscription fee debits.refundwhen 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.
Phone Verify
This operation enables you to to seamlessly verify user identities using their phone number.
phone
string
required
Phone number used to register for National Identification Number (NIN) issued by Nigeria's National Identity Management Commission (NIMC).
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 Phone Number, the API creates a new one. If you set this parameter to false, the API creates a new identity profile based on the requested Phone Number.
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.
bearer
Request
{
"phone": "string",
"refresh": true,
"testing": true
}Response
OK
[
{
"status": "success",
"message": "Identity retrieved successfully",
"data": {
"identity": {
"id": "65f3150be125eda0985d87fd",
"firstname": "Ciroma",
"middlename": "Chukwuma",
"lastname": "Adekunle",
"fullname": "Ciroma Chukwuma Adekunle",
"dob": "1999-10-11",
"gender": "M",
"customer": "6424acd03bd4390012d6b050",
"env": "production",
"aliases": [],
"phone": [],
"email": [],
"address": [],
"nationality": null,
"lga_of_origin": null,
"lga_of_residence": null,
"state_of_origin": null,
"state_of_residence": null,
"marital_status": null,
"next_of_kins": [],
"nin": "12345678910",
"photo_id": [
{
"url": "https://djrzfsrexmrry.cloudfront.net/OTk2NTY2NzkyOTE%3D.png",
"image_type": "nin_photo"
}
],
"enrollment": {
"bank": null,
"branch": null,
"registration_date": "2024-03-14"
}
},
"customer": "6424acd03bd4390012d6b050",
"receipt": {
"status": true,
"msg": "Receipt has been successfully created",
"data": {
"receipt": {
"charge_breakdown": {
"vat": 0
},
"breakdown": {
"billable_product": {
"effective_credits": 0,
"credits": 0,
"status": true,
"addon_products": [],
"product": "identity"
},
"discount": 0,
"billable_products": [
{
"effective_cost": 0,
"cost": 0,
"status": true,
"addon_products": [],
"_id": "65f3159fab89f73ab2ae0d15",
"archived": false,
"product": "identity"
}
],
"source": "api",
"limit": "3"
},
"billingStatus": true,
"paid": true,
"method": "wallet",
"charge": 0,
"wallet_balance": 0,
"addons": [],
"_id": "65f3159fab89f73ab2ae0d14",
"plan_term": "prepaid",
"owner": "5d9288ea182d3d000cb7c486",
"type": "api-call",
"billable_product": "identity",
"currency": "Okra Credits",
"record": "65f3158aab89f73ab2ae0cfd",
"customer": "6424acd03bd4390012d6b050",
"current_project": "63daf1486a1489002fd4818d",
"billable_service": "nuban-verify",
"created_at": "2024-03-14T15:19:59.199Z",
"last_updated": "2024-03-14T15:19:59.199Z"
}
}
}
}
}
]Example of a success response for the NIN verify operation.
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
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
}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."
}Service unavailable - This error indicates that the API is not ready to handle the request.
{
"status": "error",
"message": "Something went wrong from our provider. Please try again later"
}Bad request error.
[
{
"status": "error",
"message": "The provided Phone does not match any identity at this point.",
"data": null,
"total": null
}
]Returned when the identity provider did not return a valid identity response
Unprocessable Entity error - occurs when the API cannot validate the contents of your request.
[
{
"status": "error",
"message": "phone length must be at least 11 characters long",
"data": null,
"total": null
}
]Returned when the phone number provided does not meet the required character length.
status
string
The status of your request.
message
string
A short description of the error.
status
string
The status of your request.
message
string
A short description of the error.
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.
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
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.
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.
aliases
array[string]
An array of alternative names.
string
phone
array[string]
The phone number of the user.
string
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
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"
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-unbilledmeans that the receipt is a duplicate of another receipt. Duplicate receipts should only be billed once.validatedmeans 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:
depositwhen you top up your wallet.api-callwhen you use paid endpoints. Check out the API reference for the list of paid endpoints.withdrawalwhen you withdraw from your wallet.plan-feefor subscription fee debits.refundwhen 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-unbilledmeans that the receipt is a duplicate of another receipt. Duplicate receipts should only be billed once.validatedmeans 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:
depositwhen you top up your wallet.api-callwhen you use paid endpoints. Check out the API reference for the list of paid endpoints.withdrawalwhen you withdraw from your wallet.plan-feefor subscription fee debits.refundwhen 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.
Was this page helpful?