Resolve Identity

API reference for resolving identity numbers across supported countries.

Resolve an identity number to retrieve linked identifiers and profile information. The engine dispatches through the right per-country provider chain based on the identifier kind — see Identity Resolution Overview for the supported countries (NG, KE, GH, ZA) and identifier types.

Endpoint

POST /api/v1/identity/resolve

Scope: identity:resolve

Request body

Field	Type	Required	Description
`type`	`string`	Yes	Identity type: `bvn`, `nin`, `tin`, `voter`, `passport`, `phone`, `license`
`value`	`string`	Yes	The identity number to resolve
`resolveLinked`	`boolean`	No	If `true`, resolve all linked identifiers via the NIN hub. Default: `false`
`consent`	`object`	Yes	Consent proof (see below)
`consent.reference`	`string`	Yes	Your application's consent reference ID
`consent.obtainedAt`	`string`	Yes	ISO 8601 timestamp when consent was obtained

The consent field is mandatory. Requests without a valid consent reference are rejected with a BAD_REQUEST error. See Consent & NDPR for compliance details.

Response

{
  "success": true,
  "data": {
    "identifiers": {
      "nin": "12345678901",
      "bvn": "22345678901",
      "tin": "1234567890",
      "passport": "A12345678",
      "voter": "90F5B12345678901234",
      "phone": "+2348012345678",
      "license": "ABC12345DE67"
    },
    "profile": {
      "firstName": "Adaeze",
      "lastName": "Okonkwo",
      "dateOfBirth": "1990-05-15",
      "gender": "female"
    },
    "confidence": 0.95,
    "resolvedAt": "2026-04-05T14:30:00.000Z",
    "cached": false
  }
}

Field	Type	Description
`identifiers`	`object`	Resolved identity numbers (only populated fields are returned)
`profile`	`object`	Basic demographic information from the identity record
`confidence`	`number`	Match confidence score between 0 and 1
`resolvedAt`	`string`	ISO 8601 timestamp of resolution
`cached`	`boolean`	Whether the result was served from cache

When resolveLinked is false, only the input identifier and its directly resolved NIN are returned. Set resolveLinked: true to get all linked identifiers.

Examples

curl

curl -X POST https://api.platformxe.com/api/v1/identity/resolve \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "type": "bvn",
    "value": "22345678901",
    "resolveLinked": true,
    "consent": {
      "reference": "consent_ref_abc123",
      "obtainedAt": "2026-04-01T10:00:00.000Z"
    }
  }'

SDK

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

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

const result = await px.identity.resolve({
  type: 'bvn',
  value: '22345678901',
  resolveLinked: true,
  consent: {
    reference: 'consent_ref_abc123',
    obtainedAt: '2026-04-01T10:00:00.000Z',
  },
});

console.log(result.data.identifiers.nin);
// "12345678901"

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

console.log(result.data.confidence);
// 0.95

Resolve without linked identifiers

const result = await px.identity.resolve({
  type: 'nin',
  value: '12345678901',
  resolveLinked: false,
  consent: {
    reference: 'consent_ref_def456',
    obtainedAt: '2026-04-01T10:00:00.000Z',
  },
});

// Only NIN is returned since resolveLinked is false
console.log(result.data.identifiers.nin);
// "12345678901"

Error responses

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