SmartData KYC API

Integrate identity, mobile, health-insurance, and business verification into your application through a single SmartData API. You never call upstream providers directly.

Base URL

Sandbox URL

Quick Start

1

Try the sandbox

Use the sandbox API key and test NRC numbers below — no sign-up required.

2

Register your company

Complete KYB verification to get production credentials.

3

Generate production API keys

From your dashboard, generate sk_ prefixed keys with custom scopes and IP restrictions.

4

Go live

Switch from sandbox endpoints to production endpoints. Same request/response format.

Postman Collection

All endpoints pre-configured — sandbox + production. Import and start testing in seconds.

Download Collection

Content-Type: All requests must include the header Content-Type: application/json with a JSON request body.

Sandbox & Testing

Use the sandbox environment to develop and test your integration before going live. No registration required, no credits consumed.

Sandbox API Key

Use this key in the X-API-Key header for all sandbox requests:

sb_test_smartdata_sandbox_key_2025

Sandbox vs Production

	Sandbox	Production
Base URL	`/api/v1/sandbox/*`	`/api/v1/*`
API Key	`sb_test_...`	`sk_...`
Registration	Not required	Required + KYB approved
Credits	Free (unlimited)	Deducted per verification
Data	Deterministic test fixtures	Live government databases
Response	Includes `_sandbox: true`	No sandbox flag

Test NRC Numbers

Use any of these NRC numbers with the sandbox NRC Verify endpoint. Each returns unique personal details.

NRC Number	Name	Gender	Province	Status
100100/10/1	Mwamba Chanda Kapembwa	Male	Lusaka	Active
200200/20/1	Thandiwe Bwalya Mwale	Female	Copperbelt	Active
300300/30/1	Joseph Tembo Banda	Male	Southern	Active
400400/40/1	Grace Mutale Phiri	Female	Central	Active
500500/50/1	Daniel Mulenga Zulu	Male	Eastern	Active
600600/60/1	Esther Nakamba Lungu	Female	Northern	Active
700700/70/1	Peter Chisanga Mumba	Male	Luapula	Deceased
800800/80/1	Mary Chilufya Kasonde	Female	Western	Active
900900/90/1	James Kalaba Simwanza	Male	North-Western	Active
111111/11/1	Charity Mwila Sakala	Female	Muchinga	Active

Test Business Search Terms

Use any of these with the sandbox Business Verify endpoint.

Acme Corp Zanaco Trade Kings Shoprite COMP/2015/12345

Quick Test — cURL

Authentication

All API requests require an API key passed via the X-API-Key header.

Required Header

Name	Type	Description
X-API-Key	string required	Your API key. Sandbox: `sb_test_...` Production: `sk_...`

Sandbox Key

sb_test_smartdata_sandbox_key_2025

Free, no registration needed.

Production Key

sk_xxxxxxxxxxxxxxxxxxxxx

Generated from your dashboard.

Security: Never expose your production API key in client-side code (JavaScript, mobile apps). Always call the API from your backend server. Use IP whitelisting for production keys.

Example Request

Rate Limits

Every response includes rate limit headers so you can monitor your usage.

Response Headers

Header	Description
X-RateLimit-Limit	Maximum requests allowed per minute
X-RateLimit-Remaining	Requests remaining in current window
Retry-After	Seconds until the rate limit resets (only on 429)

Default: 60 requests/minute per API key. Custom limits can be set when generating a production key. Sandbox is limited to 60 requests/minute per IP.

Error Codes

When a request fails, the response body contains a structured error object.

Error Response Schema

{
  "success": false,
  "reference": "SD-REF-20260319-XXXX",
  "error": {
    "code": "SMARTDATA_NOT_FOUND",
    "message": "ID number not found in the national database."
  }
}

Code	HTTP	Description
SMARTDATA_ACCESS_DENIED	401 / 403	Invalid key, expired, or IP blocked
SMARTDATA_RATE_LIMITED	429	Too many requests — slow down
SMARTDATA_INSUFFICIENT_BALANCE	402	Top up your account balance
SMARTDATA_NOT_FOUND	404	ID or business not found in database
SMARTDATA_COUNTRY_NOT_AVAILABLE	403	Country not enabled on your plan
SMARTDATA_SCOPE_NOT_PERMITTED	403	API key lacks the required scope
SMARTDATA_SERVICE_UNAVAILABLE	503	Temporary outage — retry later

POST /api/v1/nrc/verify Sandbox: /api/v1/sandbox/nrc/verify

Verify NRC

Verify a National Registration Card (NRC) number and retrieve personal details from the national database.

Request Body

Parameter	Type	Description
nrc_number	string required	The NRC number (e.g. `100100/10/1`)
country	string optional	ISO 3166-1 alpha-2 code. Defaults to `ZM`

Success Response 200

{
  "success": true,
  "reference": "SD-REF-20260319-XXXX",
  "id_number": "100100/10/1",
  "data": {
    "full_name": "Mwamba Chanda Kapembwa",
    "first_name": "Mwamba",
    "last_name": "Kapembwa",
    "middle_name": "Chanda",
    "date_of_birth": "1985-03-15",
    "gender": "Male",
    "nationality": "Zambian",
    "province": "Lusaka",
    "district": "Lusaka",
    "status": "Active",
    "is_active": true
  },
  "message": "Verification successful."
}

POST /api/v1/business/verify Sandbox: /api/v1/sandbox/business/verify

Business Verify

Look up a business by registration number or name from the PACRA database.

Request Body

Parameter	Type	Description
search_term	string required	Business name or registration number to search
country	string optional	ISO 3166-1 alpha-2 code. Defaults to `ZM`

Response Fields (data)

Includes PACRA sector (ISIC) fields when returned by the registry: isic_code, isic_title, isic_description, nature_of_business.

Success Response 200

{
  "success": true,
  "reference": "SD-REF-20260319-XXXX",
  "data": {
    "company_name": "Acme Corp Ltd",
    "registration_number": "120251026371",
    "status": "Registered",
    "company_type": "Company",
    "date_of_registration": "2020-01-15",
    "nature_of_business": "Technology",
    "isic_code": "6201",
    "isic_title": "Computer programming",
    "isic_description": "Computer programming",
    "isic_classification": "6201"
  },
  "message": "Business lookup successful."
}

POST /api/v1/mobile/verify

Mobile Verify

Look up a Zambian mobile number through SmartData. Upstream sources are not exposed to API clients.

Request

{ "msisdn": "0973790404" }

Success Response

{
  "success": true,
  "reference": "SD-REF-20260826-XXXX",
  "msisdn": "0973790404",
  "data": {
    "first_name": "andrew",
    "last_name": "simwizi",
    "full_name": "andrew simwizi",
    "nrc": "263327711",
    "status": "SUBS",
    "verified": true
  }
}

POST /api/v1/health-insurance/verify

Health Insurance Lookup

Look up employee, beneficiary, member, or dependent registration by NRC. Employer lookup is POST /api/v1/health-insurance/employer.

Request

{
  "lookup_type": "employee_status",
  "national_id": "299352/24/1"
}

Success Response

{
  "success": true,
  "reference": "SD-REF-20260826-XXXX",
  "lookup_type": "employee_status",
  "identifier": "299352/24/1",
  "data": { "status": "Registered", "name": "Jane Banda" }
}

SANDBOX

Try NRC Verify

Send a live request to the sandbox API right from your browser. No registration needed.

NRC Number *

Country Code

Request

Waiting...

Response

—

Click "Send Request" to try it out

SANDBOX

Try Business Verify

Send a live request to the sandbox Business API from your browser.

Search Term *

Country Code

Request

Waiting...

Response

—

Click "Send Request" to try it out