Lookup Identity

API reference for raw single-ID data retrieval without cross-resolution.

Look up a single identity number and retrieve the associated profile data. Unlike the Resolve endpoint, lookup returns raw data from a single provider without cross-resolving linked identifiers through the NIN hub.

Endpoint

GET /api/v1/identity/lookup

Scope: identity:read

Query parameters

Parameter	Type	Required	Description
`type`	`string`	Yes	Identity type: `bvn`, `nin`, `tin`, `voter`, `passport`, `phone`, `license`
`value`	`string`	Yes	The identity number to look up

Response

{
  "success": true,
  "data": {
    "found": true,
    "type": "bvn",
    "value": "22345678901",
    "profile": {
      "firstName": "Adaeze",
      "lastName": "Okonkwo",
      "middleName": "Ngozi",
      "dateOfBirth": "1990-05-15",
      "gender": "female",
      "phone": "+2348012345678",
      "email": "adaeze@example.com",
      "address": "12 Marina Road, Lagos"
    },
    "raw": {
      "enrollmentDate": "2014-03-20",
      "registrationBranch": "Lagos Main",
      "levelOfAccount": "Level 3"
    },
    "provider": "primary",
    "retrievedAt": "2026-04-05T14:30:00.000Z",
    "cached": false
  }
}

Field	Type	Description
`found`	`boolean`	Whether a record was found
`type`	`string`	The identity type that was queried
`value`	`string`	The identity number that was queried
`profile`	`object`	Standardized profile data
`raw`	`object`	Additional provider-specific fields not in the standard profile
`provider`	`string`	Which provider in the fallback chain returned the data
`retrievedAt`	`string`	ISO 8601 timestamp of retrieval
`cached`	`boolean`	Whether the result was served from cache

Lookup results are cached in Redis with a 24-hour TTL. The cached field indicates whether the response came from cache. No PII is persisted to the database.

Examples

curl

curl -G https://api.platformxe.com/api/v1/identity/lookup \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d "type=bvn" \
  -d "value=22345678901"

SDK

import { PlatformXe } from '@caldera/platformxe-sdk';

const px = new PlatformXe({ apiKey: 'pxk_live_your_api_key_here' });

const result = await px.identity.lookup({
  type: 'bvn',
  value: '22345678901',
});

if (result.data.found) {
  console.log(result.data.profile.firstName);
  // "Adaeze"

  console.log(result.data.raw.enrollmentDate);
  // "2014-03-20"
} else {
  console.log('No record found');
}

Use lookup when you need raw profile data for a known identity number. Use Resolve when you need to cross-reference multiple linked identifiers, and Verify when you need to match against expected biographical data.

Error responses

Code	Description
`BAD_REQUEST`	Missing `type` or `value`, or invalid identity type
`NOT_FOUND`	No identity record found for the given type and value
`FORBIDDEN`	API key does not have the `identity:read` scope
`RATE_LIMITED`	Exceeded plan limit for identity lookup requests