Documentation · Hakiki

Base URL

All endpoints are served under your environment's base URL, for example https://api.hakiki.co.tz. In local development the API runs at http://localhost:8080.

Authentication

Verification endpoints require an API key, issued to you per environment. Send it in the X-API-Key header on every request. Keep keys secret and server-side — never embed a production key in a browser or mobile app. Keys can be revoked at any time without breaking your audit history.

X-API-Key: your_secret_key

The verification flow

A verification names a subject (the person or business), the checks to run against connected sources, and the consent that authorises the lookup. The response returns an outcome for each check. Telco identity is live today; other sources report unsupported until their integration is connected.

POST /v1/verifications

curl -X POST https://api.hakiki.co.tz/v1/verifications \
  -H "content-type: application/json" \
  -H "X-API-Key: your_secret_key" \
  -d '{
    "subject": {
      "kind": "person",
      "reference": "255712345678",
      "full_name": "Amina Juma",
      "phone": "255712345678"
    },
    "checks": ["telco_identity", "nida"],
    "consent": { "method": "ussd_otp", "granted_at": "2026-06-27T08:00:00Z" }
  }'

Returns the verification with a result per requested check:

{
  "id": "be17eb4f-...",
  "status": "completed",
  "subject": { "kind": "person", "reference": "255712345678", ... },
  "results": [
    { "check": "telco_identity", "outcome": "match", "detail": "SIM registration matches subject identity" },
    { "check": "nida", "outcome": "unsupported", "detail": "Source not yet connected" }
  ],
  "created_at": "2026-06-27T08:00:01Z"
}

GET /v1/verifications/{id}

Fetch a previously created verification by its id.

Reference

Checks

telco_identity — identity against mobile-operator records (live)
nida — national ID via NIDA (coming soon)
brela — business registration via BRELA (coming soon)
tra — tax status via TRA (coming soon)

Outcomes

match — the source confirms the subject
no_match — the source has no matching record
pending — the lookup is still in progress
unsupported — the source is not yet connected

Getting access

API keys are issued to approved partners. Request access and our team will get you a sandbox key to start building against.