Okra IDs

Dive deep into the different IDs that Okra uses and learn how you can ensure data continuity in your app.

This guide helps you understand the most important IDs that the Okra API uses, and offer some general best practices on how you can ensure data continuity in you applications.

The Okra API uses universal unique identifiers (uuids) to identify specific data properties and records. These IDs are used across multiple endpoints to refer to the same information. For example, you can use a customer id to retrieve a user’s KYC profile, then use the same customer id to retrieve the user’s account balance for their connected accounts.

Customer ID

DescriptionUsed inBest practices
This ID uniquely identifies a single user, like a name.- webhook responses
- onSuccess callback payloads
- API request and response payloads
- the Okra Dashboard		Okra recommends that you save customer IDs in your DB. This enables you to identify users in your workflows, and to retrieve data for specific users through endpoints like Get identity by customer, or Get transactions by customer.

Account ID

DescriptionUsed inBest practices
This ID uniquely identifies a user's connected account, and the bank it belongs to.- webhook responses
-onSuccess callback payloads
- API request and response payloads		Okra recommends that you save account IDs in your DB.

In the onSuccess callback payload, the connected boolean shows when a specific account is connected to your application. Use it to confirm that you are saving the correct account ID.

Product IDs

DescriptionUsed inBest practices
These IDs uniquely identify product records for a connected user within your application.

All Okra products have an ID, for example a connected user's data profile can contain transaction IDs, payment IDs, balance IDs, and so on.		- webhook responses
- onSuccess callback payloads
- API request and response payloads		Okra recommends that you save product IDs in your DB.

When a user connects their accounts via the Okra app, the API processes the user's account data. The API creates new records for every product that you set up when initializing the Okra app. Use the IDs of these product records to retrieve the data that the API processed.

For example, you set up an app and enable the Identity product. When a user connects their account in that app instance, the API creates an Identity record. You can use the Identity record's id to retrieve the Identity profile of that user.

Record ID

DescriptionUsed inBest practices
This ID uniquely identifies the data record that the API creates during a user's account connection.

The Okra API creates new records every time a user connects their account - even for returning users. A record contains all data retrieved for the user in a specific account connection session. Think of this process like creating a snapshot of available user data that is tied to an account connection. Each snapshot is a record with a unique record ID.		- webhook responses
- onSuccess callback payloads
- API request and response payloads		Okra recommends that you save record IDs in your DB.

Use record IDs to identify data from specific account connection sessions.

Bank ID

DescriptionUsed inBest practices
This ID uniquely identifies the bank where the customer has an account. Visit Okra's Coverage page for the list of bank IDs.- API request and response payloadsOkra recommends that you save bank IDs in your DB.

Use bank IDs to retrieve data from endpoints like NUBAN verify, Get identity by NUBAN, Get transactions by bank, and so on.

Custom IDs and metadata

The Okra API enables you to pass in custom IDs and key-value pairs when you set up your Okra app.

For example, each user in your application has a unique ID like user-123. You can define this ID as an option when building your app through the buildWithOptions method. When a user links their account in this app, the API returns the custom ID you defined, along with the standard Okra IDs. You can use this custom ID to retrieve data by options on specific endpoints like Get balance by options, or Get payments by options.

Example snippets for custom IDs

{
	"options":{
		"my_app_environment":"sandbox",
		"my_app_id":"12345678"
	}
}
{
	"meta":{
		"my_tracking_ID":"ID_12345678"
	}
}

Visit the Embed your app guide to understand how to set up your app using the buildWithOptions method. Check out the App properties for more details on how to set up metadata and tracking.

Need help?

  1. If you encounter any errors during your integration journey, check out the Error documentation.
  2. If you have any questions about Okra's products or way of working, get in touch with the Support team.
  3. If you have technical questions or need help with your code, join Okra's Developer Community on Slack.

Was this page helpful?

On this page