Skip to content

API reference

Identity

KYC verification and partner attestation.

post/api/v1/users/{id}/kyc

Submit or re-submit identity details for a user

Retro-KYC for an existing user, or a re-attempt after a rejection. Runs the same NIDA + phone verification as user creation. Never touches an existing wallet or balance; a user who was waiting on review gets their wallet the moment this approves. Already approved → 200 alreadyVerified; already under review → 202, without re-running.

Parameters

  • idstring (uuid)pathrequired

Request body

  • nidaNumberstringrequired

    20-digit NIDA.

  • phonestringrequired

    The user's own mobile money line, verified as a pair with the NIDA.

Responses

  • 200Verified (or already verified).Show fields
    • idstring (uuid)
    • externalIdstring
    • kycStatusstring

      approved

    • walletAddressstring | null

      Present on a fresh approval.

    • alreadyVerifiedboolean

      Present (true) when the user was already approved; nothing was re-run.

  • 202Verification is open; the identity is with manual review.Show fields
    • idstring (uuid)
    • externalIdstring
    • kycStatusstring

      pending_review

    • codestring

      Absent when the user was already under review.

      kyc_pending_review

    • messagestring
  • 400Invalid request (kyc_required, kyc_failed, phone_required), or the verification rejected the identity, in which case the body also carries kycStatus: "rejected".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
  • 404No such user under your partner account.SentenceError
  • 409nida_already_registered: this NIDA already backs another user on your platform.SentenceError
  • 429Rate limited. Respect Retry-After and back off exponentially.CodeError
  • 501Test keys get not_available_in_test_mode: this endpoint is not simulated in the sandbox. Use a live key.CodeError
  • 503kyc_unavailable: the identity registry could not be reached. Retry shortly.SentenceError
Request
curl -X POST "https://www.ntzs.co.tz/api/v1/users/14e17d04-ec7f-4d99-91a3-dfbaca19fba1/kyc" \
  -H "Authorization: Bearer $NTZS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "nidaNumber": "19900101123450000123",
  "phone": "255712345678"
}'
Response · 200
{
  "id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
  "externalId": "usr_8f3a21",
  "kycStatus": "approved"
}
post/api/v1/users/{id}/kyc/attestation

Attest a KYC outcome you performed yourself

For partners operating under a reliance agreement: you verified the identity, you report the outcome, and the wallet is issued on the strength of it in the same call. Granted per partner; without the grant this answers 403 kyc_reliance_not_granted. An API key alone must never be able to manufacture a verified identity. Idempotent: attesting a user who is already approved returns 200 with alreadyVerified: true and the same wallet.

Parameters

  • idstring (uuid)pathrequired

Request body

  • decisionstringdefault "approved"

    approvedrejected

  • referencestringrequired

    Your own KYC case id for this verification, so the underlying record can be produced on request.

  • verifiedBystringrequired

    Who performed the verification: reviewer email, team or system identifier.

  • verifiedAtstringrequired

    ISO 8601 date or timestamp of the verification. Not in the future, and no more than 365 days old.

  • countrystringrequired

    ISO 3166-1 alpha-2 country of the identity document.

  • idTypestring

    Required on an approval; optional on a rejection.

    NATIONAL_IDPASSPORTDRIVERS_LICENSERESIDENCE_PERMITVOTER_ID

  • idNumberstring

    The document number as printed. Required on an approval. Spacing and punctuation are ignored when compared.

  • fullNamestring

    The holder's full name as on the document, with at least two name components. Required on an approval.

  • notesstring

    Required on a rejection: the reason, in words the customer can act on.

  • methodstring

    How the customer was verified. Send document_selfie_liveness for the standard flow and keep it consistent.

Responses

  • 200Recorded. An approval issues the wallet in this call.Show fields
    • idstring (uuid)
    • externalIdstring
    • kycStatusstring

      approvedrejected

    • caseIdstring (uuid)

      The KYC case the decision was recorded on. Absent when alreadyVerified.

    • walletAddressstring | null
    • walletPendingstring

      Present only when an approval could not issue the wallet: why it was skipped.

      kyc_not_approvednot_a_partner_userpartner_seed_missing

    • alreadyVerifiedboolean

      Present (true) when the user was already approved.

  • 400The attestation is incomplete or invalid: invalid_decision, reference_required, verified_by_required, verified_at_required, verified_at_future, verified_at_stale, invalid_country, invalid_id_type, invalid_id_number, invalid_full_name, notes_required.SentenceError
  • 401Missing, empty, or invalid API key. No machine-readable code is returned.BareError
  • 403kyc_reliance_not_granted: your account has no KYC reliance agreement.SentenceError
  • 404No such user under your partner account.SentenceError
  • 409identity_mismatch (the document number contradicts the identity already on file), identity_already_registered (it backs another user on your platform) or kyc_already_decided (a reviewer decided the case first; read the user back).SentenceError
  • 429Rate limited. Respect Retry-After and back off exponentially.CodeError
  • 501Test keys get not_available_in_test_mode: this endpoint is not simulated in the sandbox. Use a live key.CodeError
  • 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
Request
curl -X POST "https://www.ntzs.co.tz/api/v1/users/14e17d04-ec7f-4d99-91a3-dfbaca19fba1/kyc/attestation" \
  -H "Authorization: Bearer $NTZS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "decision": "approved",
  "reference": "NEDAPAY-KYC-88213",
  "verifiedBy": "compliance@yourapp.com",
  "verifiedAt": "2026-10-20T09:30:00Z",
  "country": "TZ",
  "idType": "NATIONAL_ID",
  "idNumber": "19900101123450000123",
  "fullName": "Amina Juma Hassan",
  "method": "document_selfie_liveness"
}'
Response · 200
{
  "id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
  "externalId": "usr_8f3a21",
  "kycStatus": "approved",
  "caseId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
  "walletAddress": "0x531B87EfdEBD19bfd05700DF6218d4786Cf2201C"
}