Identity

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 the get identity operations for customers that you have already verified.

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

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

• 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

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

📘

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.