TextBit API Documentation
Documentation
Introduction
TextBit provides a reliable and secure OTP (One-Time Password) service for user authentication. Our API endpoints allow you to send and verify OTP messages to users' phone numbers.
Base URL
https://api.textbit.dev/
Authentication
All API requests must include your API key in the headers for authentication.
Headers
X-API-Key: your-api-key-hereCommon API Errors
The following error codes are common across all API endpoints. Each endpoint may also have additional specific error codes that are documented in their respective sections.
Common Error Codes
| Status Code | Reason | Description |
|---|---|---|
| 401 | missing_api_key | API key is missing from request |
| 404 | invalid_api_key | App not found (wrong API key) |
| 403 | invalid_scopes | App doesn't have valid scopes |
| 402 | insufficient_credits | Insufficient credits balance |
| 429 | rate_limit_exceeded | Rate limit exceeded |
| 500 | server_error | Internal server error |
Error Response Format
All error responses follow this standard format:
Send OTP Endpoint
Send a one-time password (OTP) to a specified phone number. The OTP will be valid for 5 minutes.
Request
Headers
| Key | Value | Required |
|---|---|---|
| X-API-Key | Your API key | ✅ |
| Content-Type | application/json | ✅ |
Body Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| phone_number | string | Phone number to receive the OTP in E.164 format (e.g. +250789123456) | ✅ |
Example Request
Responses
200Success
400Invalid Phone Format
Endpoint-Specific Error Codes
| Status Code | Reason | Description |
|---|---|---|
| 400 | invalid_phone_format | Rwandan phone number must be 10 digits (e.g., 078XXXXXXX) |
This endpoint also returns all common API errors.
Verify OTP Endpoint
Verify a previously sent one-time password (OTP) for a specific phone number. Users have a maximum of 3 attempts to verify an OTP.
Request
Headers
| Key | Value | Required |
|---|---|---|
| X-API-Key | Your API key | ✅ |
| Content-Type | application/json | ✅ |
Body Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| phone_number | string | Phone number for which the OTP was sent in E.164 format (e.g. +250789123456) | ✅ |
| otp | string | The OTP code entered by the user | ✅ |
Example Request
Responses
200Success
400Invalid OTP
404No Pending OTP
Endpoint-Specific Error Codes
| Status Code | Reason | Description |
|---|---|---|
| 404 | no_pending_otp | No pending OTP found for the provided phone number |
| 429 | max_attempts_reached | Too many failed verification attempts |
| 400 | invalid_otp | The OTP provided is invalid |
| 401 | otp_expired | The OTP has expired (valid for 5 minutes) |
This endpoint also returns all common API errors.
Rate Limits
TextBit API enforces rate limits to ensure fair usage and prevent abuse of the service. The current default rate limit is 30 requests per minute per API key.
OTP Expiration and Attempts
- •OTPs expire after 5 minutes
- •Users have a maximum of 3 attempts to verify an OTP
- •If you need different configurations for your use case, please contact us
Need Higher Limits?
If your application requires higher rate limits, please reach out to our team. We can provide custom rate limit configurations based on your specific needs.
Here are examples of how to use the TextBit API in different programming languages.
Phone Number Validation
TextBit API enforces strict phone number validation to ensure messages are sent to valid recipients. Understanding these validation rules will help you avoid errors and improve the success rate of your OTP delivery.
Supported Formats
E.164 Format (Recommended)
Format Pattern:
+[country code][number]Example: +250789123456
Format Rules:
- Must include country code
- Must start with '+'
- No spaces or special characters
Local Format (Only for Rwandan Numbers)
Format Pattern:
0[carrier code][number]Example: 0789123456
Format Rules:
- Must be exactly 10 digits
- Must start with '0'
- Second digit must be carrier code (7, 8, 9 for mobile)
Common Validation Errors
| Error Message | Reason | Solution |
|---|---|---|
| "Rwandan phone number must be 10 digits" | Local format number with incorrect length | Ensure number is exactly 10 digits (e.g., 0789123456) |
| "Invalid phone number format" | Phone number contains invalid characters | Remove spaces, dashes, or other special characters |
| "Missing country code" | International format used without country code | Add the appropriate country code (e.g., +250 for Rwanda) |
Country Support
While TextBit API primarily supports Rwandan phone numbers in both local and international formats, you can also use the service with international numbers in E.164 format. For optimal delivery rates, always use the E.164 international format (+[country code][number]) without spaces or special characters.
Best Practice
For consistent results across all countries, always store and transmit phone numbers in the E.164 format. If your application collects phone numbers in local format, convert them to E.164 before sending them to the API.
Message Templates
When creating an app in the TextBit dashboard, you can select from various message templates for your OTP communications. These templates help you deliver consistent and professional OTP messages to your users.
Template Selection
During the app creation process, you will be presented with multiple pre-designed OTP message templates to choose from. These templates include various formats such as standard verification messages, branded messages with your application name, security-focused templates, and login-specific messages.
Template Features
- All templates automatically include your OTP code
- Most templates can include your application name
- Templates are designed for optimal readability on mobile devices
- Security-focused templates include anti-phishing messaging
Need a Custom Template?
If the available templates don't meet your specific needs, please contact us to discuss custom template options for your business requirements.
Security Best Practices
Follow these best practices to ensure secure usage of the TextBit API:
API Security
Keep Keys Private
Never expose your API key in client-side code or public repositories. Store your keys securely in environment variables.
Separate Environments
Use different API keys for development, testing, and production environments to maintain better security and debugging.
Graceful Error Handling
Implement user-friendly error handling with clear messages. Map TextBit error codes to helpful user prompts (e.g., "Your verification code has expired. Please request a new one." instead of showing technical errors).
Remove Unused Keys
Delete API keys that are no longer needed. Unused keys present unnecessary security risks to your account.
OTP Implementation Best Practices
OTP Expiration Handling
- Display countdown timer: Show users how much time they have left to enter the OTP before it expires.
- Proactive expiration: Implement a client-side mechanism to detect when an OTP is about to expire and offer to resend before the user attempts verification.
- Clear messaging: When an OTP expires, clearly communicate this to users and provide a simple way to request a new one.
Retry Logic
- Track remaining attempts: Display the remaining verification attempts to users (they have 3 attempts before lockout).
- Exponential backoff: Implement increasing delay periods between retry attempts to mitigate brute force attacks.
- Alternative verification: After maximum failed attempts, offer alternative verification methods or account recovery options.
Payment Options
TextBit offers flexible payment options to accommodate users across different regions.
Standard Payment Methods
- Credit/Debit Cards: Visa, Mastercard, American Express
Alternative Payment Methods
MTN MoMo Virtual Card
Don't have a credit/debit card? MTN Mobile Money users can create a Mastercard-powered virtual card for online payments.
How to get your virtual card:
- Dial *182*2*6# on your MTN phone
- Confirm with your MoMo PIN
- Select "Virtual Card by MoMo"
- Select "Create card"
- Accept the Terms and Conditions
- You'll receive an SMS confirming your card creation
- To view your card details, dial *182*2*6# and select option 4
This virtual card works just like a regular Mastercard for online payments.
Billing Cycle
TextBit operates on a credit-based system:
- Pre-purchased credits that you can use for sending and verifying OTPs
- Credits never expire - purchase once and use them when you need them
- Each verification cycle uses 1.5 credits (1 for sending + 0.5 for verification)