Before you integrate
Use the API from a trusted server over HTTPS. Create or manage credentials from your account’s API or OTP dashboard, keep them out of browser code and source control, and revoke or rotate any credential that may have been exposed. Access, account status, available balance, approved sender IDs and service configuration can affect whether a request is accepted.
The examples below document the application interface; they do not send messages or verify that a live provider is enabled on your account. Test only with an authorized test setup.
SMS sending endpoint
Method: POST · Path: /api/send.php · Content type: application/x-www-form-urlencoded.
Authenticate with the X-API-Key request header, or the api_key form field. Header authentication is preferred. Form fields are number (recipient), message (message text), type (non_masking or masking; defaults to non-masking), and optional sender_id. Masking requires a sender ID approved for the account. OTP traffic must use the dedicated OTP API, not this endpoint.
curl -X POST "https://your-domain.example/api/send.php" \
-H "X-API-Key: YOUR_SMS_API_KEY" \
--data-urlencode "number=01700000000" \
--data-urlencode "message=Your authorized message" \
--data-urlencode "type=non_masking"
A successful application response contains success, provider_response, sms_count and cost. Validation errors use HTTP 422, insufficient balance HTTP 402, authentication failures HTTP 401, provider/application send failures HTTP 502, and unexpected errors HTTP 500. Check both the HTTP status and JSON body. The provider response is not a delivery receipt; do not infer delivery from submission.
OTP API v1
The customer-backend OTP API uses separate, customer-scoped OTP keys. Send the key in Authorization: Bearer YOUR_OTP_API_KEY or X-API-Key. The key is secret and must never be embedded in a mobile app or browser.
POST /api/v1/otp/send — JSON {"phone":"01700000000","purpose":"login"}; purpose is optional.POST /api/v1/otp/verify — JSON {"request_id":"otp_...","otp":"..."}; successful verification is single-use.POST /api/v1/otp/resend — JSON {"request_id":"otp_..."}; subject to cooldown, rate limits and billing.GET /api/v1/otp/status/{request_id} — reads a request authorized for that customer and key.
Responses use JSON. Send returns a request reference and lifecycle information, not the OTP itself. Errors include a stable error code. Phone and request ownership, key scope/environment, service settings, limits and wallet balance are checked server-side. Current OTP documentation and account controls are available after signing in under OTP API Documentation and OTP Dashboard.
A status of submitted/provider_pending means the request was submitted or accepted by the configured transport; it does not establish delivery. Provider message-ID and DLR contracts are not represented as verified here.
Security and operational guidance
- Use HTTPS and keep API keys in a server-side secret store or protected environment configuration.
- Never log or expose API keys, passwords, OTP values, or unnecessary recipient/message data.
- Handle timeouts as potentially uncertain outcomes. Do not automatically retry SMS or OTP sends unless your application can safely account for duplicate sends and charges.
- Use status and account reports supported by the service; do not treat a provider submission response as a delivery report.
- Respect recipient consent, sender-ID approvals, rate limits, applicable law and the Usage Policy.
Contact support if you need account-specific API access or encounter an integration issue. Include a request or transaction reference where available, but never send a secret or OTP in a support message.