API reference
Users
End-user records and their embedded wallets.
/api/v1/usersCreate a user and provision a wallet
Requires the wallets capability: end-user wallet issuance is granted per partner, and without it this answers 403. Idempotent on externalId: calling again returns the existing user rather than creating a second one. No wallet is ever issued without a verified identity, so a 202 is a normal outcome, not a failure. Where nTZS runs verification for your platform, a Tanzanian user needs nidaNumber and phone and may come back 202 kyc_pending_review; otherwise (and for non-TZ users) the user is created without verification and the 202 says what finishes it, typically kyc_attestation_required under a KYC reliance agreement.
Request body
externalIdstringrequiredYour own id for this user. The idempotency key for this endpoint.
emailstring (email)requirednamestringcountrystringdefault "TZ"ISO 3166-1 alpha-2. Defaults to TZ. Outside TZ no NIDA exists, and
phonemust be E.164.nidaNumberstring20-digit NIDA. Required for a TZ user when nTZS verifies identity for your platform; ignored otherwise. One NIDA backs at most one wallet per partner.
phonestringThe user's OWN mobile money line, verified as a pair with the NIDA. Required alongside
nidaNumber.
Responses
200The user already existed and was resolved.Show fieldsHide
idstring (uuid)externalIdstringemailstring (email)namestring | nullphonestring | nullwalletAddressstring | nullbalancenumberAlways 0 on this endpoint. Read balances with GET /v1/users/{id}.
kycStatusstringPresent only when an existing user still has no wallet (e.g.
pending_review).approvedpending_reviewrejectednone
201Created and verified, wallet issued.Show fieldsHide
idstring (uuid)externalIdstringemailstring (email)namestring | nullphonestring | nullwalletAddressstring | nullbalancenumberAlways 0 on this endpoint. Read balances with GET /v1/users/{id}.
kycStatusstringPresent only when an existing user still has no wallet (e.g.
pending_review).approvedpending_reviewrejectednone
202Created, but identity verification is still open, so no wallet yet.
codeiskyc_pending_revieworkyc_attestation_required, andnextStepsays what finishes it. Wait for thekyc.updatedwebhook rather than polling hard, then re-call with the sameexternalId.Show fieldsHideidstring (uuid)externalIdstringemailstring (email)namestring | nullphonestring | nullwalletAddressnullbalancenumberAlways 0.
kycStatusstringpending_reviewattestation_requiredcodestringkyc_pending_reviewkyc_attestation_requirednextStepstringkyc_attestationwhen you hold a KYC reliance grant (finish with POST /v1/users/{id}/kyc/attestation); otherwisecompliance_review.kyc_attestationcompliance_reviewmessagestringplatformWalletobjectPresent with
kyc_attestation_required: how to collect and pay for this user from your platform wallet in the meantime.messagestringendUserEndUserPlatform-wallet calls only: which of YOUR users this transaction is for.
referenceis your own id for them (opaque to us, at most 128 characters). Echoed on the webhooks for the transaction.referencestringrequirednamestringphonestringA valid Tanzanian number, when you have it.
- 400Invalid request. Identity failures use the sentence shape:
kyc_required,kyc_failed(malformed NIDA),phone_required,invalid_country,phone_invalid.SentenceError - 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
- 409
nida_already_registered: this NIDA already backs a wallet, or a verification under review, on your platform.SentenceError - 429Rate limited. Respect
Retry-Afterand back off exponentially.CodeError - 503
kyc_unavailable: the identity registry could not be reached. Nothing was created; retry shortly.SentenceError
curl -X POST "https://www.ntzs.co.tz/api/v1/users" \
-H "Authorization: Bearer $NTZS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalId": "usr_8f3a21",
"email": "user@example.com",
"country": "TZ",
"phone": "255712345678"
}'{
"id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"externalId": "usr_8f3a21",
"email": "user@example.com",
"name": "…",
"phone": "255712345678",
"walletAddress": "0x531B87EfdEBD19bfd05700DF6218d4786Cf2201C",
"balance": 10000
}/api/v1/users/{id}Read a user, their wallet and balances
Parameters
idstring (uuid)pathrequired
Responses
200The user.Show fieldsHide
idstring (uuid)externalIdstringYour own system's identifier for this user.
emailstring (email)phonestring | nullwalletAddressstring | nullNull while identity verification is still open. No wallet exists without a verified identity.
balanceTzsintegernTZS balance, whole shillings. 0 when there is no wallet or the chain read failed.
balanceUsdcnumberbalanceUsdtnumberkycStatusstringnonemeans no identity on file. Call POST /v1/users/{id}/kyc.approvedpending_reviewrejectednone
- 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
- 404No such user under your partner account.SentenceError
- 429Rate limited. Respect
Retry-Afterand back off exponentially.CodeError - 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
curl "https://www.ntzs.co.tz/api/v1/users/14e17d04-ec7f-4d99-91a3-dfbaca19fba1" \
-H "Authorization: Bearer $NTZS_API_KEY"{
"id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"externalId": "usr_8f3a21",
"email": "user@example.com",
"phone": "255712345678",
"walletAddress": "0x531B87EfdEBD19bfd05700DF6218d4786Cf2201C",
"balanceTzs": 10000,
"balanceUsdc": 10000,
"balanceUsdt": 10000,
"kycStatus": "approved"
}