REST API v1

API Documentation

Public HTTP API for sending SMS, checking delivery status, and querying account balance.

Overview

All endpoints use GET requests against the versioned API base URL:

https://sms.retaillian.com/api/v1

Production origin: https://sms.retaillian.com

Authentication

Every request must include a valid API key as the apiKey query parameter. Keys are issued per SMS account through the customer portal after sign-in.

Example

?apiKey=550e8400-e29b-41d4-a716-446655449000

Invalid or missing keys return HTTP 401 with plain text: Invalid or missing API key. Missing required query parameters return HTTP 400 with a JSON error object.

Phone Number Format

Destination numbers must use the Pakistan mobile format:

923XXXXXXXXX

Country code 92 followed by 3 and 9 more digits
Example: 923001234567
Comma-separated lists are supported for multiple recipients on send requests

Response Formats

By default, responses are returned as JSON. Pass format=json explicitly or send Accept: application/json.

For XML responses, pass format=xml or send Accept: application/xml / Accept: text/xml.

JSON responses for known error codes include an additional friendlyMessage field with a human-readable explanation.

Endpoint Reference

GET

Send SMS

Send an SMS message to one or more recipients. Each successful send returns a unique transaction ID for delivery tracking.

Endpoint

Path

GET /api/v1/sms/send

Parameters

Parameter	Required	Description
apiKey	Yes	Your API key.
to	Yes	Destination number(s) in format 923XXXXXXXXX. Comma-separated for multiple recipients.
msg	Yes	Message content (URL-encode special characters).
lang	No	Message language: English or Urdu (case-insensitive). Defaults to English.
format	No	Response format: json (default) or xml.

Example Request

URL

GET https://sms.retaillian.com/api/v1/sms/send?apiKey=YOUR_API_KEY&to=923001234567&msg=Hello%20World&lang=English&format=json

Success Response (JSON)

JSON

{
  "corpsms": {
    "code": "300",
    "type": "Success",
    "response": "Message Sent to Telecom.",
    "transactionID": "12345"
  }
}

Error Response (JSON)

JSON

{
  "corpsms": {
    "code": "206",
    "type": "Error",
    "response": "Invalid destination number.",
    "transactionID": "0",
    "friendlyMessage": "Invalid destination number. Use format 923XXXXXXXXX."
  }
}

Success Response (XML)

Returned when format=xml.

XML

<?xml version="1.0" encoding="UTF-8" ?>
<corpsms>
  <code>300</code>
  <type>Success</type>
  <response>Message Sent to Telecom.</response>
  <transactionID>12345</transactionID>
</corpsms>

Delivery Status Values

Status	Description
Successful	Message delivered successfully.
UnSuccessful	Message delivery failed.

Error Code Reference

When an error occurs, the API returns a code field with one of the following values:

Code	Message
200	Invalid API credentials. Check your API key.
203	Your SMS account has expired. Contact support.
204	Invalid sender mask for this account.
206	Invalid destination number. Use format 923XXXXXXXXX.
208	A required parameter is missing.
209	Your account has been blocked or suspended.
210	Invalid language. Use English or Urdu.
211	Insufficient SMS credit. Top up your account.

Success Codes

Code	Message
100	Success (balance inquiry).
300	Message sent to telecom network.

cURL Examples

Send SMS

curl

curl "https://sms.retaillian.com/api/v1/sms/send?apiKey=YOUR_API_KEY&to=923001234567&msg=Hello&lang=English&format=json"

Delivery Status

curl

curl "https://sms.retaillian.com/api/v1/sms/status?apiKey=YOUR_API_KEY&transaction=12345&format=json"

Balance Inquiry

curl

curl "https://sms.retaillian.com/api/v1/sms/balance?apiKey=YOUR_API_KEY&format=json"

Support

For API key management, account access, and billing inquiries, sign in to the customer portal.

https://sms.retaillian.com/admin/login

For rate limits and enterprise pricing, contact your Retaillian representative.