The Okra Identity API helps you verify users' identities by accessing the information stored with their financial institution. The API retrieves a full KYC profile for an individual or corporate account across all banks in Nigeria.
For a complete guide on how the Identity API works and how you can use it, visit the Identity guide.
Operations
The Identity API has 2 types of operations: verify
and get
.
Okra recommends that you use the
verify
operations to verify customers and retrieve their identity details only for the first time. These operations debit your Okra wallet after every successful verification. To avoid depleting your wallet, use theget
identity operations for customers that you have already verified.
Verify
operations
Verify
operationsUse any of the verify
operations according to your business case. These operations can verify a new user and retrieve their identity details:
- The
bvn-verify
operation retrieves a user’s KYC profile from their financial institution using their Bank Verification Number. - The
bulk-bvn-verify
operation retrieves identity profiles for up to 10 users in the same request. - The
nuban-verify
operation retrieves a user’s KYC profile using their Nigerian Uniform Bank Account Number. - The
nuban-name-verify
operation retrieves a user’s full name using their NUBAN. This operation is ideal for use cases where a complete KYC profile is not necessary. - the
customer-verify
operation retrieves a user’s identity profile using their customerID
. 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.
Get
operations
Get
operationsUse the get
operations to retrieve the identity profiles of already verified users. You can fetch your users’ identity profiles:
- by their identity
ID
, - by their BVN,
- by their NUBAN,
- using their customer
ID
, - by date for a single user,
- or by date for all users.
Best practices
-
To avoid duplicate API calls for the same user, Okra recommends that you leverage the Identity API using this simple process:
-
Use a
get
operation to retrieve a user’s identity.For example, you can use Get identity by BVN or Get identity by NUBAN as an initial step. The next step depends on the response you receive:
- A successful response means that the user is already verified and the API returns the identity profile for you to use.
- An unsuccessful response means that the BVN is not found and the user is not yet verified.
-
If you receive an unsuccesful response, use a
verify
operation to verify the new user and retrieve their identity details.This process is simple, but important.
get
endpoint operations are free to use.verify
endpoint operations are paid operations that debit your Okra wallet. To avoid depleting your wallet, use theget
operations first to retrieve identity profiles for customers that you have already verified. You can track the customers that you have already verified using theirBVN
,NUBAN
, or their customerID
.
-
-
Okra recommends that you implement:
- front-end validation to prevent your users from accidentally triggering multiple
verify
requests in short succession through the onboarding flow. - a queue to wait for the results of a successful identity verification request. This can prevent duplicate
verify
requests for the same user.
- front-end validation to prevent your users from accidentally triggering multiple
-
You can use the Bulk BVN verify operation to verify up to 10 users in a single API call.
Error handling
The Identity API follows Okra’s standard API error conventions. There are some error responses that are unique to the Identity API.
503 timeout
errors
503 timeout
errorsCommon causes
The verify
operations can return a 503 timeout
error when a data source returns a timeout response. Some identity verification processes that time out eventually do finish successfully, therefore Okra strongly recommends that you implement an automatic retry for your requests to the verify
operations.
Troubleshooting
Add a short delay to your automatic retries to ensure that you handle 503 timeout
errors successfully.
Sample response
{
"status": "error",
"message": "Our data source has returned a timeout response. Please retry the request. "
}
nuban-verify
timeout errors
nuban-verify
timeout errorsCommon causes
The nuban-verify
operation can return timeout errors when a NUBAN can not be verified to retrieve the identity data within the given timeout range that Okra enforces. The causes of this timeout can be due to:
- provider downtime or provider timeout issues,
- or the BVN linked to the requested account cannot be verified.
When a BVN cannot be verified, the possible reasons are:
- the requested account is not linked to a BVN,
- or the BVN is fraudulent.
Troubleshooting
Add a 1 hour delay to your automatic retries to ensure that you handle these timeout errors successfully.
Sample responses
This error occurs when the NUBAN can not be verified to retrieve the identity data within the given timeout range:
{
"status": "error",
"message": "Could not match the nuban account to a valid identity."
}
This error occurs when you repeat the same nuban-verify
request within 1 hour with the same result:
{
"status": "error",
"message": "Invalid identity, please try again in 1 hour."
}
Okra always returns errors with a corresponding error code, or a descriptive error message. Visit the Error documentation for a complete list of errors. If you encounter an error that is not documented, get in touch with Okra’s support team.