API Documentation

Every request is authenticated with two headers: X-Client-Id and X-Client-Secret, issued during onboarding. Keep your secret key confidential — server-to-server integration is recommended.

curl --location 'https://api.tasdeeqly.com/api/v1/messages' \
--header 'Content-Type: application/json' \
--header 'X-Client-Id: YOUR_CLIENT_ID' \
--header 'X-Client-Secret: YOUR_CLIENT_SECRET' \
--data '{
  "mobileNo": "+923001234567",
  "channel": "SMS",
  "smsType": "TRANSACTIONAL",
  "text": "Your order #12345 has been confirmed.",
  "reference": "ORDER-12345",
  "network": "UFONE"
}'

Sends an SMS or WhatsApp message to a single mobile number. channel is optional — if missing or null, Tasdeeqly treats the request as SMS. WhatsApp is supported where enabled for your account.

POST /api/v1/messages

{
  "mobileNo": "+923001234567",
  "channel": "SMS",
  "smsType": "TRANSACTIONAL",
  "text": "Your order #12345 has been confirmed.",
  "reference": "ORDER-12345",
  "network": "UFONE"
}

POST /api/v1/messages

{
  "mobileNo": "+923001234567",
  "channel": "WHATSAPP",
  "smsType": "TRANSACTIONAL",
  "text": "Your order #12345 has been confirmed.",
  "reference": "ORDER-12345"
}

HTTP/1.1 201 Created

{
  "reference": "ORDER-12345",
  "messageId": "MSG-3f9a1c2e-...",
  "statusCode": 2001,
  "statusMessage": "Message submitted successfully."
}

reference is returned unchanged. messageId is generated by Tasdeeqly and can be used for tracking and reconciliation. statusCode is a numeric code (see Error Handling for the full list) — 2001 corresponds to SUBMITTED. A successful request always returns HTTP 201 Created; the numeric statusCode in the body confirms the specific outcome.

Your account can be configured to allow transactional messages, promotional messages, or both.

V1 supports English/GSM-7 characters only. Unicode, Urdu, Arabic, and other character sets are not supported in V1.

Tasdeeqly does not automatically split messages in V1. A message above 612 characters is rejected before sending (MESSAGE_TOO_LONG).

Length is measured in GSM-7 septets, not raw character count. Extended-set characters (such as ^ { } [ ] ~ | €) cost 2 septets each, so a message using these characters can reach a unit boundary sooner than its visible character count suggests. Any character outside the supported GSM-7 set is rejected with UNSUPPORTED_CHARACTERS rather than being auto-converted.

The calculated number of units is deducted from the client's SMS balance and is fixed at submission time. WhatsApp messages are not subject to the SMS unit table above — every accepted WhatsApp message consumes a flat 1 WhatsApp unit, up to a maximum of 4,096 characters (rejected with MESSAGE_TOO_LONG beyond that).

Clients purchase communication bundles. A bundle may contain SMS units, WhatsApp units, or both. SMS and WhatsApp balances are managed separately. When a new bundle is purchased, its units are added to the client's existing balance.

Generates and delivers a one-time code to a mobile number, for use cases such as verifying a customer's mobile number during order or account creation.

POST /api/v1/otp/request

{
  "mobileNo": "+923001234567",
  "reference": "ORDER-12345",
  "network": "UFONE"
}

HTTP/1.1 201 Created

{
  "reference": "ORDER-12345",
  "messageId": "OTP-7c1e2a9b-...",
  "statusCode": 2002,
  "statusMessage": "OTP sent successfully.",
  "coolPeriod": 60,
  "maxAttempts": 3,
  "remainingAttempts": 2
}

The response returns the cooldown period (coolPeriod, in seconds), the configured resend limit (maxAttempts) and how many resend requests remain (remainingAttempts) so your UI can show the appropriate information.

Validate the code entered by the user against the mobile number and reference from the request step.

POST /api/v1/otp/verify

{
  "mobileNo": "+923001234567",
  "reference": "ORDER-12345",
  "otpCode": "482913"
}

HTTP/1.1 201 Created

{
  "reference": "ORDER-12345",
  "statusCode": 2003,
  "statusMessage": "OTP verified successfully.",
  "verifyMaxAttempts": 5,
  "remainingVerificationAttempts": 5
}

verifyMaxAttempts is the configured verification-attempt limit. On a successful verify, remainingVerificationAttempts reflects the full limit again; on a failed attempt (INVALID_OTP), the same field reports how many verification attempts remain before the reference is locked.

When the configured verification-attempt threshold is reached, further verify calls against that reference return OTP_VERIFICATION_LIMIT. Separately, if a mobile number is locked, the initial waiting period is 15 minutes; repeated exhaustion progressively increases the waiting period — 15, 30, 45, 60 minutes and onward — and any request made inside that window returns OTP_LOCKED.

If a mobile number becomes locked because the configured OTP attempt threshold has been exceeded, the client can request a reset for that mobile number.

POST /api/v1/otp/reset-mobile

{
  "mobileNo": "+923001234567"
}

HTTP/1.1 201 Created

{
  "statusCode": 2000,
  "statusMessage": "OTP state reset for this mobile number."
}

This response has no reference or messageId field — the reset is scoped to the client + mobile number, not a specific OTP request. Authentication identifies the client, so the reset applies only to that client's mobile number. It clears the active OTP lock/cooldown state so the client can request OTP again according to its configured policy, and does not affect other clients, previous OTP records, message history, or communication balances.

Tasdeeqly protects against accidental duplicate submissions after a message has been successfully submitted — automatically, with no special header required. The logical identity of a message is based on Client + Reference + Message.

If the same successfully submitted message is sent again, Tasdeeqly returns the existing result instead of submitting another message. If the original submission failed before succeeding, retrying is allowed.

If a network/operator communication route experiences a temporary failure, Tasdeeqly can automatically use an alternative available route where configured, without requiring any change to your integration. Fallback is handled transparently — you continue using the same API and don't need to know which communication route was used.

Tasdeeqly tracks standardized delivery status based on delivery information received from the communication network.

The network field is optional and can be sent with messages and OTP requests. It may be useful for operator-specific requirements, routing information, or future communication requirements. If your integration doesn't need it, you can omit the field.

{ "network": "UFONE" }

Tasdeeqly can provide white-label sender options for clients that require their own brand identity when messages are delivered. Depending on the supported channel, country, operator, and applicable commercial/regulatory requirements, this may include shortcode, sender masking, or other approved sender-ID arrangements — configured with Tasdeeqly during onboarding. Availability, sender format, approval requirements, and applicable charges vary by network and local regulations. White-label configuration does not change your API integration.

Tasdeeqly may temporarily suspend or degrade SMS or WhatsApp service globally, or for an individual client, for maintenance, operational issues, or service degradation. Your integration does not need to change — the API returns a standardized response (SERVICE_UNAVAILABLE) indicating the service is temporarily unavailable or degraded.

Every response body includes a numeric statusCode and a human-readable statusMessage. The numeric code is always consistent with the HTTP status of the response. On error, the response follows the same envelope shape:

{
  "statusCode": 4010,
  "statusMessage": "Invalid client credentials.",
  "code": "AUTHENTICATION_FAILED"
}

Message-lifecycle and success statuses that may also appear in statusCode: OK (2000), SUBMITTED (2001), OTP_SENT (2002), OTP_VERIFIED (2003), PENDING (2005), DELIVERED (2006). Provider-specific outcomes (for example a route-level rejection or timeout) may also surface as additional numeric codes configured per provider during onboarding.

Normal message:

1. Customer action / business event
2. Your backend calls Tasdeeqly
3. Tasdeeqly authenticates your client
4. Request and service permissions are validated
5. SMS length/units are calculated
6. Available balance is checked
7. Tasdeeqly processes the message
8. Tasdeeqly returns reference/requestId/messageId
9. Delivery information is processed
10. Final status becomes DELIVERED or FAILED