API reference
Identity
KYC verification and partner attestation.
/api/v1/users/{id}/kycSubmit 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
nidaNumberstringrequired20-digit NIDA.
phonestringrequiredThe user's own mobile money line, verified as a pair with the NIDA.
Responses
200Verified (or already verified).Show fieldsHide
idstring (uuid)externalIdstringkycStatusstringapprovedwalletAddressstring | nullPresent on a fresh approval.
alreadyVerifiedbooleanPresent (true) when the user was already approved; nothing was re-run.
202Verification is open; the identity is with manual review.Show fieldsHide
idstring (uuid)externalIdstringkycStatusstringpending_reviewcodestringAbsent when the user was already under review.
kyc_pending_reviewmessagestring
- 400Invalid request (
kyc_required,kyc_failed,phone_required), or the verification rejected the identity, in which case the body also carrieskycStatus: "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
- 409
nida_already_registered: this NIDA already backs another user on your platform.SentenceError - 429Rate limited. Respect
Retry-Afterand 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 - 503
kyc_unavailable: the identity registry could not be reached. Retry shortly.SentenceError
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"
}'{
"id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"externalId": "usr_8f3a21",
"kycStatus": "approved"
}/api/v1/users/{id}/kyc/attestationAttest 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"approvedrejectedreferencestringrequiredYour own KYC case id for this verification, so the underlying record can be produced on request.
verifiedBystringrequiredWho performed the verification: reviewer email, team or system identifier.
verifiedAtstringrequiredISO 8601 date or timestamp of the verification. Not in the future, and no more than 365 days old.
countrystringrequiredISO 3166-1 alpha-2 country of the identity document.
idTypestringRequired on an approval; optional on a rejection.
NATIONAL_IDPASSPORTDRIVERS_LICENSERESIDENCE_PERMITVOTER_IDidNumberstringThe document number as printed. Required on an approval. Spacing and punctuation are ignored when compared.
fullNamestringThe holder's full name as on the document, with at least two name components. Required on an approval.
notesstringRequired on a rejection: the reason, in words the customer can act on.
methodstringHow the customer was verified. Send
document_selfie_livenessfor the standard flow and keep it consistent.
Responses
200Recorded. An approval issues the wallet in this call.Show fieldsHide
idstring (uuid)externalIdstringkycStatusstringapprovedrejectedcaseIdstring (uuid)The KYC case the decision was recorded on. Absent when
alreadyVerified.walletAddressstring | nullwalletPendingstringPresent only when an approval could not issue the wallet: why it was skipped.
kyc_not_approvednot_a_partner_userpartner_seed_missingalreadyVerifiedbooleanPresent (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
- 403
kyc_reliance_not_granted: your account has no KYC reliance agreement.SentenceError - 404No such user under your partner account.SentenceError
- 409
identity_mismatch(the document number contradicts the identity already on file),identity_already_registered(it backs another user on your platform) orkyc_already_decided(a reviewer decided the case first; read the user back).SentenceError - 429Rate limited. Respect
Retry-Afterand 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
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"
}'{
"id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"externalId": "usr_8f3a21",
"kycStatus": "approved",
"caseId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"walletAddress": "0x531B87EfdEBD19bfd05700DF6218d4786Cf2201C"
}