Skip to content

API reference

Users

End-user records and their embedded wallets.

post/api/v1/users

Create 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

  • externalIdstringrequired

    Your own id for this user. The idempotency key for this endpoint.

  • emailstring (email)required
  • namestring
  • countrystringdefault "TZ"

    ISO 3166-1 alpha-2. Defaults to TZ. Outside TZ no NIDA exists, and phone must be E.164.

  • nidaNumberstring

    20-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.

  • phonestring

    The 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 fields
    • idstring (uuid)
    • externalIdstring
    • emailstring (email)
    • namestring | null
    • phonestring | null
    • walletAddressstring | null
    • balancenumber

      Always 0 on this endpoint. Read balances with GET /v1/users/{id}.

    • kycStatusstring

      Present only when an existing user still has no wallet (e.g. pending_review).

      approvedpending_reviewrejectednone

  • 201Created and verified, wallet issued.Show fields
    • idstring (uuid)
    • externalIdstring
    • emailstring (email)
    • namestring | null
    • phonestring | null
    • walletAddressstring | null
    • balancenumber

      Always 0 on this endpoint. Read balances with GET /v1/users/{id}.

    • kycStatusstring

      Present 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. code is kyc_pending_review or kyc_attestation_required, and nextStep says what finishes it. Wait for the kyc.updated webhook rather than polling hard, then re-call with the same externalId.Show fields
    • idstring (uuid)
    • externalIdstring
    • emailstring (email)
    • namestring | null
    • phonestring | null
    • walletAddressnull
    • balancenumber

      Always 0.

    • kycStatusstring

      pending_reviewattestation_required

    • codestring

      kyc_pending_reviewkyc_attestation_required

    • nextStepstring

      kyc_attestation when you hold a KYC reliance grant (finish with POST /v1/users/{id}/kyc/attestation); otherwise compliance_review.

      kyc_attestationcompliance_review

    • messagestring
    • platformWalletobject

      Present with kyc_attestation_required: how to collect and pay for this user from your platform wallet in the meantime.

    • messagestring
    • endUserEndUser

      Platform-wallet calls only: which of YOUR users this transaction is for. reference is your own id for them (opaque to us, at most 128 characters). Echoed on the webhooks for the transaction.

    • referencestringrequired
    • namestring
    • phonestring

      A 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
  • 409nida_already_registered: this NIDA already backs a wallet, or a verification under review, on your platform.SentenceError
  • 429Rate limited. Respect Retry-After and back off exponentially.CodeError
  • 503kyc_unavailable: the identity registry could not be reached. Nothing was created; retry shortly.SentenceError
Request
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"
}'
Response · 200
{
  "id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
  "externalId": "usr_8f3a21",
  "email": "user@example.com",
  "name": "…",
  "phone": "255712345678",
  "walletAddress": "0x531B87EfdEBD19bfd05700DF6218d4786Cf2201C",
  "balance": 10000
}
get/api/v1/users/{id}

Read a user, their wallet and balances

Parameters

  • idstring (uuid)pathrequired

Responses

  • 200The user.Show fields
    • idstring (uuid)
    • externalIdstring

      Your own system's identifier for this user.

    • emailstring (email)
    • phonestring | null
    • walletAddressstring | null

      Null while identity verification is still open. No wallet exists without a verified identity.

    • balanceTzsinteger

      nTZS balance, whole shillings. 0 when there is no wallet or the chain read failed.

    • balanceUsdcnumber
    • balanceUsdtnumber
    • kycStatusstring

      none means 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-After and back off exponentially.CodeError
  • 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
Request
curl "https://www.ntzs.co.tz/api/v1/users/14e17d04-ec7f-4d99-91a3-dfbaca19fba1" \
  -H "Authorization: Bearer $NTZS_API_KEY"
Response · 200
{
  "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"
}