Getting started

1. Create an API key with the Identity scope

In the dashboard, go to Settings → Developers and create a key. Tick Identity → Run checks (identity.write) to call the check endpoints, and Read results (identity.read) to list and fetch past checks. Keys without an Identity scope get 403 from /v1/identity.

Hosted verification sessions (/v1/verify/sessions) work with any valid key.

2. Authenticate

Send your token in the Authorization header. The token is the Base64 encoding of clientId:clientSecret, which the dashboard shows when you create the key. Either Basic or Bearer works as the prefix.

Authorization: Basic <YOUR_TOKEN>

3. Fund your wallet

Each check is deducted from your Sendexa wallet when you make it. If the balance is too low you get 403 with code INSUFFICIENT_CREDITS and nothing runs. Top up under Wallet in the dashboard; every response includes what the check cost, and each charge appears in your wallet history.

4. Run a check

The simplest check returns the name a phone number is registered to:

curl -X POST 'https://api.sendexa.co/v1/identity/msisdn-name' \
  -H 'Authorization: Basic <YOUR_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "msisdn": "233241234567" }'

Response:

{
  "success": true,
  "code": "CHECK_COMPLETE",
  "message": "Successful",
  "requestId": "REQ-1791820800000",
  "timestamp": "2026-10-12T10:00:00.000Z",
  "data": {
    "checkId": "IDN-5f0c2a9e-7c1b-4f7e-9d2a-0b6c1e8f3a21",
    "isValid": null,
    "matchScore": null,
    "resultName": "KOFI MENSAH",
    "providerResponseCode": "0000",
    "cost": { "amount": 0.02, "currency": "USD" }
  }
}

Keep the checkId: you can fetch the same result later from GET /v1/identity/checks/:checkId.