Skip to main content
To validate an OTP, submit the OTP identifier or phone number, the developer app key and the code the user entered. Trim whitespace, ensure the code is numeric (if using numeric codes) and check length before calling the API. The same developer app used to request the code should be used to verify it. Example verification request: 
curl -X POST https://karibu.briq.tz/v1/otp/verify/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "otp_id": "otp_xyz789abc123def",
    "code": "123456",
    "developer_app_id": "dev_app_abc123xyz789"
  }'
A successful verification response indicates verified status and a timestamp; failures indicate invalid, expired, already-used codes or other errors. Handle both the success flag and verification status in your client logic, show clear and actionable messages to users, limit verification attempts to prevent brute force, and clear OTP state after success. If SMS delivery fails often in your region, prefer or offer the voice call delivery option since it tends to have higher delivery reliability. 
curl -X POST https://karibu.briq.tz/v1/otp/verify/ \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key_here" \
-d '{
  "otp_id": "otp_xyz789abc123def",
  "code": "123456",
  "developer_app_id": "dev_app_abc123xyz789"
}'

​
Request Parameters

ParameterTypeRequiredDescription
otp_idstringYesOTP ID from the original OTP request
codestringYesOTP code entered by the user
developer_app_idstringYesSame developer app ID used for requesting the OTP

​
Response Format

Valid Code: 
{
  "success": true,
  "message": "OTP verified successfully.",
  "data": {
    "verified_at": "2025-08-23T00:28:15.567264"
  },
  "status_code": 200
}
Invalid Code: 
{
  "success": false,
  "otp_id": "otp_xyz789abc123def",
  "verified": false,
  "error": "Invalid or expired OTP code"
}
Expired Code: 
{
  "success": false,
  "otp_id": "otp_xyz789abc123def",
  "verified": false,
  "error": "OTP code has expired"
}

​
Best Practices

​
Code Validation

  • Validate that the code contains only digits
  • Check code length before sending to API
  • Trim whitespace from user input
  • Handle case where user includes spaces in code

​
Security Considerations

  • Store OTP IDs securely (session storage, encrypted database)
  • Don’t expose OTP IDs in client-side logs
  • Implement maximum verification attempts
  • Clear OTP data after successful verification

​
User Experience

  • Show clear error messages for invalid codes
  • Provide option to request new OTP if expired
  • Display remaining time for code expiration
  • Allow users to resend OTP after reasonable delay

​
Error Handling

  • Check both success and verified fields in response
  • Provide clear error messages to users
  • Implement rate limiting to prevent brute force attacks
  • Log verification attempts for security monitoring
Common error codes and how to handle them:
Error CodeDescriptionRecommended Action
INVALID_CODECode doesn’t matchAllow retry, show attempts remaining
OTP_EXPIREDCode has expiredOffer to send new code
MAX_ATTEMPTS_EXCEEDEDToo many failed attemptsLock user out, require new OTP request
OTP_NOT_FOUNDInvalid request IDHandle as invalid request
ALREADY_VALIDATEDCode already usedTreat as invalid attempt
⌘I