Identity

The /products/identities endpoint allows you to retrieve various account holder information on file with the bank, including names, emails, phone numbers, and addresses.

Note: This request may take some time to complete if identity was not specified as an initial product when creating the Record. This is because Okra must communicate directly with the institution to retrieve the data.

Identity Data Dictionary

Field

Description

id ObjectID

Unique Identity ID (Unique Okra Identifier)

firstname String

Customer First Name

middlename String

Customer Middle Name

lastname String

Customer Last Name

next_of_kins Identity Object

Customer Next of Kins

dob Date

Customer Date of Birth

verified String

BVN Validation status

score String

Unique Okra Score

dti String

Customer Debt to Credit Score

fullname String

Customer Fullname

company_name String

Company Name if Corporate Identity

nin String

Customer NIN Number

national_id String

Customer National ID Number

voters_id String

Customer Voter's ID Number

rc_number String

Company's Registered Company Number if Corporate Identity

phone Array of String

Customer Phone Number

last_login String

Customer Last Login via Okra

email Array of String

Customer Email address

address Array of String

Customer

photo_ids Array of Object

Customer's photo ID

env String

Okra API Env the transaction was pulled from production or production-sandbox

bank ObjectID

Unique Bank ID (Unique Okra Identifier)

customer ObjectID

Unique Customer ID (Unique Okra Identifier)

record Array of ObjectID

Unique Record ID (Unique Okra Identifier)

created_at Object

Date Balance was fetched

last_updated Object

Last Date Balance was fetched

Request

Field

Required

Description

accessToken String

yes

The same as your secret token

pdf

Boolean

no

To get .pdf format of the response

Retrieve Identity request

POST /products/identities
cURL
Node
Show Response
cURL
curl -X POST https://api.okra.ng/v1/products/identities
-H 'Content-Type: application/json'
-H 'Authorization: Bearer <AccessToken>'
Node
// Pull Identity data for a Record
const okra_client = require("okra-node")
okra_client.getIdentities(accessToken, {}, (err, results) => {
// Handle err
const identities = results.identities;
});
`
Show Response
{
"status": "success",
"message": "Identities successfully retrieved",
"data": {
"pagination": null,
"identities": [
{
"id": "",
"firstname": "",
"middlename": null,
"lastname": "",
"next_of_kins": [],
"dob": null,
"verified": false,
"score": "0",
"dti": null,
"fullname": "",
"nin": null,
"national_id": null,
"voters_id": null,
"rc_number": null,
"phone": [
"06593463757"
],
"owner": [
{
"_id": "",
"name": "",
"app_name": ""
}
],
"record": [
{
"_id": "",
"bank": "",
"env": "",
"owner": "",
"status": {
"process": {
"running": false,
"completed": true
}
}
}
],
"aliases": [
""
],
"env": "",
"bvn": "",
"customer": {
"_id": "",
"name": ""
},
"last_updated": "",
"email": [
"",
""
],
"address": [],
"mothers_maiden": null,
"photo_id": [],
"gender": null
}
]
}
}

Identity by Id

The /identity/getById endpoint allows you to retrieve various account holder information on file using the id.

Field

Required

Description

id

yes

The identity id

page

no

The page number

limit

no

The number of records to be returned

Retrieve Identity request

POST /identity/getById
cURL
Node
Show Response
cURL
curl -X POST https://api.okra.ng/v1/identity/getById
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <AccessToken>'
-d '{
"id":"5odfknfdsadnf"
}'
Node
// Pull Identity data by identity id
const okra_client = require("okra-node")
okra_client.getIdentityById(accessToken, {id:"5ee8b9d601ff99625b92aa9a"}, (err, results) => {
// Handle err
const identities = results.identity;
});
`
Show Response
{
"status": "success",
"message": "Identity retrieved succesfully",
"data": {
"pagination": {
"totalDocs": 1,
"limit": 20,
"hasPrevPage": false,
"hasNextPage": false,
"page": 1,
"totalPages": 1,
"pagingCounter": 1,
"prevPage": null,
"nextPage": null
},
"identity": [
{
"_id": "",
"aliases": [
"",
"",
""
],
"phone": [
"",
""
],
"email": [],
"verified": true,
"next_of_kins": [
""
],
"address": [
null,
""
],
"owner": [
{
"_id": "",
"name": ""
}
],
"record": null,
"bvn": "",
"firstname": "",
"lastname": "",
"fullname": "",
"dob": null,
"gender": null,
"marital_status": null,
"customer": {
"_id": "",
"name": ""
},
"env": "production",
"photo_id": [
{
"_id": "",
"url": "",
"image_type": "",
"bank": ""
}
],
"created_at": "2020-04-13T01:28:09.899Z",
"last_updated": "2020-09-15T10:44:21.645Z",
"__v": 2,
"middlename": "",
"score": "0",
"smileId": true,
"enrollment": {
"bank": "",
"branch": "",
"registration_date": ""
},
"level_of_account": "",
"lga_of_origin": "",
"lga_of_residence": "",
"nationality": "",
"state_of_origin": "",
"state_of_residence": "",
"watch_listed": "",
"rc_number": "",
"bvn_updated": false,
"ref_ids": [],
"smile_identity": {
"result_code": "",
"message": "",
"updatedFrom": "",
"updatedAt": "2020-09-10T01:54:29.994Z"
},
"employer": [],
"id": ""
}
]
}
}

Identity By options

The /identity/byOptions endpoint allows you to fetch identity info using the options metadata you provided when setting up the widget.

Field

Required

Description

options Object

yes

The metadata associated with the record

page

no

The page number

limit

no

The number of records to be returned

Retrieve Identity request

POST /identity/byOptions
cURL
Node
Show Response
cURL
curl -X POST https://api.okra.ng/v1/identity/byOptions
-H 'Content-Type: application/json'
-H 'Authorization: Bearer <AccessToken>'
-D '{
"page": 1,
"limit": 5,
"options":{"first_name": "Peter", "last_name": "Johnson"}
}
Node
// Pull Identity data by options
const okra_client = require("okra-node")
okra_client.getIdentityByOptions(accessToken, {options: {"first_name":"Faridah", "last_name":"Adedunmola"}}, (err, results) => {
// Handle err
const identities = results.identity;
});
`
Show Response
{
"status": "success",
"message": "Identity retrieved succesfully",
"data": {
"pagination": {
"totalDocs": 1,
"limit": 20,
"hasPrevPage": false,
"hasNextPage": false,
"page": 1,
"totalPages": 1,
"pagingCounter": 1,
"prevPage": null,
"nextPage": null
},
"identity": [
{
"enrollment": {
"bank": "",
"branch": "",
"registration_date": ""
},
"aliases": [
"",
null,
null,
null,
null
],
"phone": [
"",
""
],
"email": [
""
],
"verified": true,
"next_of_kins": [],
"address": [
""
],
"record": [""],
"bvn_updated": false,
"smileId": true,
"ref_ids": [],
"_id": "",
"bvn": "",
"__v": 0,
"created_at": "",
"customer": {
"_id": "",
"name": ""
},
"dob": "",
"env": "",
"firstname": "",
"fullname": "",
"gender": "",
"last_updated": "",
"lastname": "",
"marital_status": null,
"middlename": null,
"score": "50",
"level_of_account": "",
"lga_of_origin": "",
"lga_of_residence": "",
"nationality": "",
"photo_id": [
{
"_id": "",
"url": "",
"image_type": "",
"bank": ""
}
],
"state_of_origin": "",
"state_of_residence": "",
"watch_listed": ""
}
]
}
}

Identity by Customer

The /identity/getByCustomer endpoint allows you to retrieve various account holder information on file using the customer id.

Field

Required

Description

customer

yes

The customer id

page

no

The page number

limit

no

The number of records to be returned

Retrieve Identity request

POST /identity/getByCustomer
cURL
Node
Show Response
cURL
curl -X POST https://api.okra.ng/v1/identity/getByCustomer \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <AccessToken>'
Node
// Pull Identity data by customer id
const okra_client = require("okra-node")
okra_client.getIdentityByCustomer(accessToken, {customer:"5ee8b9d601ff99625b92aa9a"}, (err, results) => {
// Handle err
const identities = results.identity;
});
`
Show Response
{
"status": "success",
"message": "Identity retrieved succesfully",
"data": {
"pagination": {
"totalDocs": 1,
"limit": 20,
"hasPrevPage": false,
"hasNextPage": false,
"page": 1,
"totalPages": 1,
"pagingCounter": 1,
"prevPage": null,
"nextPage": null
},
"identity": [
{
"_id": "",
"aliases": [
"",
""
],
"phone": [
null
],
"email": [],
"verified": false,
"next_of_kins": [],
"address": [],
"record": null,
"bvn": "",
"firstname": "",
"lastname": "",
"fullname": "",
"customer": {
"_id": "",
"name": ""
},
"env": "production",
"photo_id": [
{}
],
"created_at": "2020-04-23T11:51:00.286Z",
"last_updated": "2020-09-15T13:33:19.757Z",
"__v": 1,
"dob": null,
"gender": null,
"marital_status": null,
"middlename": null,
"score": "0",
"smileId": true,
"bvn_updated": false,
"employer": [],
"ref_ids": [],
"smile_identity": {
"job_id": "",
"result_code": "",
"message": "",
"updatedFrom": "cron",
"updatedAt": "2020-09-09T15:01:22.171Z"
},
"id": ""
}
]
}
}

Identity by Date range

The /identity/getByDate endpoint allows you to retrieve various account holder information on file using a date range.

Field

Required

Description

from

yes

The start date eg 2020-12-25

to

yes

The end date eg 2020-12-29

page

no

The page number

limit

no

The number of records to be returned

Retrieve Identity request

POST /identity/getByDate
cURL
Node
Show Response
cURL
curl -X POST https://api.okra.ng/v1/identity/getByDate \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <AccessToken>'
-d '{
"to": "2020-03-01",
"from":"2020-01-01"
}'
Node
// Pull Identity data by date range
const okra_client = require("okra-node")
okra_client.getIdentityByDate(accessToken, {from:"2019-12-28", to:"2020-12-28"}, (err, results) => {
// Handle err
const identities = results.identity;
});
`
Show Response
{
"status": "success",
"message": "Identity retrieved succesfully",
"data": {
"pagination": {
"totalDocs": 20,
"limit": 20,
"hasPrevPage": false,
"hasNextPage": false,
"page": 1,
"totalPages": 1,
"pagingCounter": 1,
"prevPage": null,
"nextPage": null
},
"identity": [
{
"_id": "",
"smile_identity": {
"job_id": "",
"result_code": "",
"message": "",
"updatedFrom": "",
"updatedAt": "2020-09-09T15:03:19.418Z"
},
"aliases": [
"",
""
],
"phone": [],
"email": [],
"verified": false,
"next_of_kins": [],
"address": [],
"record": [
{
"_id": "",
"status": {
"transactions": {
"last_success_at": null,
"last_fail_at": null
},
"process": {
"running": false,
"completed": true
}
},
"owner": ""
}
],
"bvn_updated": false,
"smileId": true,
"ref_ids": [],
"bvn": "",
"firstname": "",
"middlename": null,
"lastname": "",
"fullname": "",
"customer": {
"_id": "",
"name": ""
},
"env": "production",
"photo_id": [],
"created_at": "2020-09-01T09:08:06.880Z",
"last_updated": "2020-09-09T15:03:19.418Z",
"__v": 0,
"id": ""
}
]
}
}

Identity by Customer and Date range

The /identity/getByDate endpoint allows you to an account holder information on file using a date range and customer id.

Field

Required

Description

from

yes

The start date eg 2020-12-25

to

yes

The end date eg 2020-12-29

page

no

The page number

limit

no

The number of records to be returned

customer

yes

The customer id

Retrieve Identity request

POST /identity/getByCustomerDate
cURL
Node
Show Response
cURL
curl -X POST https://api.okra.ng/v1/identity/getByCustomerDate \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <AccessToken>'
-d '{
"customer_id":"5odfknfdsadnf",
"to": "2020-03-01",
"from":"2020-01-01"
}'
Node
// Pull Identity data by date range
const okra_client = require("okra-node")
okra_client.getIdentityByCustomerDate(accessToken, {from:"2019-12-28", to:"2020-12-28"}, (err, results) => {
// Handle err
const identities = results.identity;
});
`
Show Response
{
"status": "success",
"message": "Identity retrieved succesfully",
"data": {
"pagination": {
"totalDocs": 1,
"limit": 20,
"hasPrevPage": false,
"hasNextPage": false,
"page": 1,
"totalPages": 1,
"pagingCounter": 1,
"prevPage": null,
"nextPage": null
},
"identity": [
{
"_id": null,
"bvn": "",
"__v": 1,
"address": [
""
],
"aliases": [
""
],
"created_at": "2020-05-31T18:54:18.423Z",
"customer": {
"_id": "",
"name": ""
},
"dob": "",
"email": [
""
],
"env": "production-sandbox",
"firstname": "",
"fullname": "",
"gender": "",
"last_updated": "2020-08-29T23:00:57.703Z",
"lastname": "",
"marital_status": null,
"middlename": null,
"phone": [
""
],
"photo_id": [
{}
],
"record": [
{}
],
"score": "0",
"smileId": false,
"bvn_updated": false,
"employer": [],
"next_of_kins": [],
"ref_ids": [],
"smile_identity": {
"updatedAt": "2020-08-26T11:49:52.884Z",
"updatedFrom": ""
},
"verified": false,
"id": "null"
}
]
}
}