Identity API

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.

Verify operations

Use any of the verify operations according to your business case. These operations can verify a new user and retrieve their identity details:

• 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 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.
• The nin-verify operation seamlessly verifies user's identities using their National Identification Number (NIN) issued by Nigeria's National Identity Management Commission (NIMC). The Okra NIN Verification API empowers you to address various KYC needs across diverse industries.
• The phone-verify operation seamlessly verifies user's identities using their Phone Number. This operation requires the phone number associated with the user's National Identification Number (NIN).

Get operations

Use 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,
• by their NIN,
• by their Phone,
• 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:

  1. Use a get operation to retrieve a user’s identity.

     For example, you can use Get identity by BVN or Get identity by NUBAN or Get identity by NIN or Get identity by Phone 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.

  2. 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 the get operations first to retrieve identity profiles for customers that you have already verified. You can track the customers that you have already verified using their BVN, NUBAN, or their customer ID.

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

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

Common 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

Common 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."
}