API reference
Lookup
Resolve who is behind a number, till or bill account before paying.
post
/api/v1/lookup/recipient-nameResolve the registered name behind a mobile number
For the "Sending to: JOHN DOE" line before a user confirms. Fail-soft: name: null means no confirmation was available: show the raw number and continue, never block. Rate limited to 30/min per partner and audited per call.
Request body
phoneNumberstringrequiredTanzanian mobile number.
2557XXXXXXXX,07XXXXXXXXand+2557XXXXXXXXare all accepted.
Responses
200Resolved, or
name: nullwhen unconfirmed.Show fieldsHidephonestringnetworkstringvodacomairteltigohalotelttclunknownnamestring | null
- 400Invalid request.CodeError
- 401Missing, empty, or invalid API key. No machine-readable code is returned.BareError
- 403Forbidden: a missing capability, unapproved KYB, a source IP outside your allowlist, or a frozen wallet.CodeError
- 429Rate limited. Respect
Retry-Afterand back off exponentially.CodeError - 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
Request
curl -X POST "https://www.ntzs.co.tz/api/v1/lookup/recipient-name" \
-H "Authorization: Bearer $NTZS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phoneNumber": "255712345678"
}'Response · 200
{
"phone": "255712345678",
"network": "vodacom",
"name": "…"
}post
/api/v1/lookup/merchant-nameResolve the trading name behind a till or bill account
Fail-soft like the recipient lookup. Bill validation is amount-aware, so send amountTzs when known. Upstream can take ~25s, so debounce and never put this on a keystroke. Rate limited to 60/min per partner.
Request body
kindstringrequiredlipabillpayNumberstringutilityCodestringutilityRefstringamountTzsintegerWhole Tanzanian shillings. Never a decimal.
Responses
200Resolved, or
name: nullwith areason.Show fieldsHidekindstringlipabilltargetstringnamestring | nullreasonstring
- 400Invalid request.CodeError
- 401Missing, empty, or invalid API key. No machine-readable code is returned.BareError
- 403Forbidden: a missing capability, unapproved KYB, a source IP outside your allowlist, or a frozen wallet.CodeError
- 429Rate limited. Respect
Retry-Afterand back off exponentially.CodeError - 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
Request
curl -X POST "https://www.ntzs.co.tz/api/v1/lookup/merchant-name" \
-H "Authorization: Bearer $NTZS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"kind": "lipa"
}'Response · 200
{
"kind": "lipa",
"target": "…",
"name": "…",
"reason": "…"
}post
/api/v1/lookup/qrResolve a scanned TANQR payload to a destination
Request body
payloadstringrequiredThe raw scanned QR string.
Responses
- 200The destination the code resolves to.object
- 400Invalid request.CodeError
- 401Missing, empty, or invalid API key. No machine-readable code is returned.BareError
- 403Forbidden: a missing capability, unapproved KYB, a source IP outside your allowlist, or a frozen wallet.CodeError
- 429Rate limited. Respect
Retry-Afterand back off exponentially.CodeError - 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
Request
curl -X POST "https://www.ntzs.co.tz/api/v1/lookup/qr" \
-H "Authorization: Bearer $NTZS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"payload": "…"
}'