Identity migration guide

Learn how you can migrate your product to use Okra's revamped Identity API.


Overview

In a recent update, we have released an updated version of the Identity API. This new version introduces three new API endpoints that replace all of the previous Identity API endpoints.

Since this is a breaking change, we have created this guide to help you with your migration to the new Identity API.

To ensure a smooth transition to the new endpoints, we are rolling out a phased migration process, enabling you to keep the old Identity endpoints active for a certain period.

List of changes

This secion gives you a summary of what has changed in this update.

New endpoints

Okra now provides identity verification using NIN and NUBAN through these endpoints:

Operations that retrieve already verified identity profiles are now merged into a single search endpoint:

New server URL

The base server URL for the Identity API is now https://identity-api.okra.ng/v2/

Updated response structure

Check out a 200 - successful response to understand the scope of the changes:

The API now returns these fields in a 200 - successful response:

{
  "success": {boolean},
  "message": {string},
  "data": {object}
}
  • Note that the status indicator field success now uses boolean data format.

The data object now returns only the identity and receipt objects:

{
  "data": {
    "identity": {object},
    "receipt": {object}
  }
}
  • Note that the contents of the identity objects may vary between endpoints. Check out the API reference to see the exact response schemas.

Deprecations

All verify routes from the previous version of the Identity API are now deprecated.

  • /products/kyc/nuban-name-verify
  • /products/kyc/customer-verify
  • /products/kyc/nin-verify

All get identity operations are now also deprecated in favor of the new search endpoint.

  • Get by identity ID
  • Get by BVN
  • Get by NUBAN
  • Get by NIN
  • Get by Phone number
  • Get by customer ID
  • Get for a single user
  • Get for all users

Migrate to the new endpoints

You can follow these steps to ensure that your implementation of Okra's Identity API works as expected.

  1. Update server URL

    Update the server URL for any function that uses the Identity API to the new URL:


    • https://identity-api.okra.ng/v2/

  2. Update endpoint paths

    Make sure that you update the endpoint paths that you use when calling the Identity API. The new routes are:



    All get identity operations from the previous version of the Identity API are now merged into the new search endpoint. Use this endpoint to retrieve the identity profiles of already verified users.

  3. Check request and response schemas

    All new identity endpoints come with updated request and response schemas. This means that the requests you need to send and the response data you receive may be different in the new version.


    While you can directly map functionalities between the old and new endpoints, the request and response schemas for these endpoints are not identical. Check out the API reference and make sure that these changes do not affect your implementation.

Need help?

If you have any questions or need assistance during this transition, feel free to reach out to our support team!

Was this page helpful?