English

Arad SMS API Documentation

Welcome to the Arad SMS API (Arad ITC) documentation. This guide is designed to help you integrate with our powerful SMS platform, which handles over 300 million messages daily, covering 60% of Iran's SMS traffic. Trusted by major organizations like Asiatech, ArianTel, Jiring, and leading banks such as Bank Mellat, Bank Sepah, Bank Melli, Bank Saderat and etc.

Introduction

The Arad SMS API offers a wide range of messaging services, allowing developers to send, manage, and track SMS communications efficiently. With robust infrastructure and advanced reporting capabilities, businesses can streamline their messaging workflows and ensure reliable delivery.

Developers can access these services by registering with the Arad SMS platform. Once registered, users can authenticate and start integrating the API into their applications.

For detailed API documentation and live testing, visit our Swagger Documentation.

Authentication

The Arad SMS API supports three methods of authentication:

Basic Authentication:
- This method encodes the username and password in Base64 and includes it in the Authorization header.
- Note: Due to security vulnerabilities, this method is not recommended.
Example:
```
Username: AradUser
Password: AradPassword

Base64("AradUser:AradPassword") => QXJhZFVzZXI6QXJhZFBhc3N3b3Jk

Authorization: Basic QXJhZFVzZXI6QXJhZFBhc3N3b3Jk
```

Bearer Token:

Obtain a token by calling the /connect/token endpoint with your credentials. The token is valid for 5 minutes.

Request:

POST https://api.aradvas.ir/connect/token
Content-Type: application/x-www-form-urlencoded

Body:
grant_type=password&username=YOUR_USERNAME&password=YOUR_PASSWORD&scope=ApiAccess

Response:

{
    "access_token": "Your token",
    "expires_at": "2022-08-01T05:02:37Z",
    "scope": "ApiAccess"
}

API Key:
- Generate an API Key from your dashboard and include it in the X-API-Key header.
Example:
```
X-API-Key: YOUR_API_KEY
```

To enable API access, ensure your IP address is registered with Arad. Contact support for IP whitelisting.

API Endpoints

API Access and Scopes

In the Arad SMS API, some endpoints require specific access levels defined by Scopes.

Scope: ApiAccess

This scope is used for sending messages and retrieving general delivery reports.

Endpoints:

/api/message/send
/api/message/GetDLR
/api/message/GetDLRByPartId
/api/message/GetMO
/api/message/GetMOByDate

Scope: ApiPatternAccess

This scope is used for sending pattern-based messages.

Endpoints:

/api/patternMessage/send
/api/patternMessage/sendMultiple

Scope: BulkApiAccess

This scope is used for bulk messaging and high-volume message processing.

Endpoints:

/api/message/bulk
/api/message/P2PBulk
/api/message/GetDLR
/api/message/GetDLRByPartId
/api/message/GetMO
/api/message/GetMOByDate

Scope: WhiteListAccess

This scope is used for sending messages to whitelisted numbers.

Endpoints:

/api/message/SendToWhiteList

Sending SMS

Send single or multiple SMS messages using the following endpoint:

Endpoint:

POST https://api.aradvas.ir/api/{apiversion}/message/send

Headers:

Authorization: Bearer {your access token} | Basic | ApiKey
Content-Type: application/json

Body Parameters:

Parameter	Type	Description
`SourceAddress`	string	Sender's number
`DestinationAddress`	string	Recipient's number
`MessageText`	string	Content of the SMS
`ValidityPeriod`	string	Expiry time of the message (1 min to 6 hours)
`TargetUDH`	array	Optional. Ports and reference number settings
`DataCoding`	int	Data coding (8 for Farsi, 1 for English)
`MessageClass`	string	Message type (Text, Binary, Email, Voice)
`ServiceID`	string	Value-added service ID
`Priority`	int	Message priority (0 to 7)
`UDH`	string	User-defined header for tagging messages

Sample Request:

[
  {
    "SourceAddress": "989000xxxx",
    "DestinationAddress": "9891xxxxxxxx",
    "MessageText": "Test message",
    "TargetUDH": ["port:5000", "referenceNumberType:16bit"]
  }
]

Sample Response:

{
  "message": "Successfully done.",
  "succeeded": true,
  "data": ["624ed1bbcd0efb1ef148e0a0"],
  "resultCode": 100
}

Bulk and P2P Messaging

Send bulk messages to multiple recipients with a single request.

Endpoint:

POST https://api.aradvas.ir/api/{apiversion}/message/bulk

Headers:

Authorization: Bearer {your access token} | Basic | ApiKey
Content-Type: application/json

Body Parameters:

Parameter	Type	Description
`SourceAddress`	string	Sender's number
`DestinationAddress`	array	List of recipients
`MessageText`	string	Content of the SMS
`TargetUDH`	array	Optional. Ports and reference number settings
`ValidityPeriod`	string	Expiry time of the message

Sample Request:

{
  "SourceAddress": "989000xxxx",
  "MessageText": "Test bulk message",
  "DestinationAddress": ["9891xxxxxxxx", "9891yyyyyyyy"],
  "TargetUDH": ["port:5000", "referenceNumberType:16bit"]
}

Sample Response:

{
  "message": "Successfully done.",
  "succeeded": true,
  "data": [
    "624ed1bbcd0efb1ef148e0a0",
    "624ed1bbcd0efb1ef148e0a1"
  ],
  "resultCode": 100
}

Send SMS via GET

To send a single SMS using the GET method, you can send requests to the following endpoint.

Endpoint:

GET https://api.aradvas.ir/api/{apiversion}/message/send

Required Parameters:

Parameter	Type	Description
`SourceAddress`	string	Sender's number
`DestinationAddress`	string	Recipient's number (comma-separated for multiple)
`MessageText`	string	Content of the SMS
`port`	int	Port (optional)
`referenceNumberType`	string	Reference number type (8bit or 16bit)

Sample Request:

https://api.aradvas.ir/api/message/send?SourceAddress=989000xxxx&DestinationAddress=98912xxxxxxx&MessageText=test&port=5000&referenceNumberType=16bit

Sample Response:

{
    "message": "Successfully done.",
    "succeeded": true,
    "data": [
        "62e760d2393e38af65bb9e4e"
    ],
    "resultCode": 100
}

Receiving Messages

Retrieve incoming messages (MO - Mobile Originated) from your account.

Endpoint:

GET https://api.aradvas.ir/api/{apiversion}/message/getmo

Headers:

Authorization: Bearer {your access token} | Basic | ApiKey

Optional Query Parameters:

Parameter	Type	Description
`returnId`	boolean	Return unique ID for each message
`startDateTime`	string	Filter messages received after this date
`endDateTime`	string	Filter messages received before this date

Sample Response (With Messages):

{
  "message": "Successfully done.",
  "succeeded": true,
  "data": [
    {
      "sourceAddress": "9891xxxxxxxx",
      "destinationAddress": "989000xxxx",
      "messageText": "Hello from user",
      "receiveDateTime": "2022-04-04T11:23:11.211Z"
    },
    {
      "sourceAddress": "9891yyyyyyyy",
      "destinationAddress": "989000xxxx",
      "messageText": "Another incoming message",
      "receiveDateTime": "2022-04-05T13:40:57.793Z"
    }
  ],
  "resultCode": 100
}

Sample Response (No Messages):

{
  "message": "Item not found!",
  "succeeded": false,
  "resultCode": 109
}

Delivery Reports

Retrieve the status of sent messages using delivery reports.

Endpoint:

GET https://api.aradvas.ir/api/{apiversion}/message/dlr

Headers:

Authorization: Bearer {your access token} | Basic | ApiKey

Optional Query Parameters:

Parameter	Type	Description
`messageId`	string	Unique ID of the sent message
`sourceAddress`	string	Sender's number
`destinationAddress`	string	Recipient's number
`status`	string	Filter by delivery status (delivered, failed)
`startDateTime`	string	Filter reports from this date
`endDateTime`	string	Filter reports up to this date

Sample Response (With Delivery Reports):

{
  "message": "Successfully done.",
  "succeeded": true,
  "data": [
    {
      "messageId": "624ed1bbcd0efb1ef148e0a0",
      "status": "delivered",
      "deliveryDateTime": "2022-04-04T12:00:00.000Z"
    },
    {
      "messageId": "624ed1bbcd0efb1ef148e0a1",
      "status": "failed",
      "deliveryDateTime": "2022-04-04T12:05:00.000Z"
    }
  ],
  "resultCode": 100
}

Sample Response (No Reports Found):

{
  "message": "Item not found!",
  "succeeded": false,
  "resultCode": 109
}

User Information

To retrieve user information including credit, dedicated numbers, and sending limits, use the following method:

Endpoint:

GET https://api.aradvas.ir/api/user/userinfo

Sample Response:

{
    "message": "Successfully done.",
    "succeeded": true,
    "data": {
        "userName": "username",
        "firstName": "name",
        "lastName": "family",
        "credit": 5000.0,
        "mps": 1000,
        "senderIds": [
            "989000xxxx",
            "9890001xxx"
        ]
    },
    "resultCode": 100
}

Pattern-Based Messaging

To use pattern-based messaging, you must first define and approve a Pattern in the dashboard. Then you can use the following method:

Endpoint:

POST https://api.aradvas.ir/api/PatternMessage/send

Required Parameters:

Parameter	Type	Description
`Destinations`	Array	List of recipient numbers
`Parameters`	Array	Parameters to replace in the pattern
`PatternId`	string	Pattern ID from the dashboard

Sample Request:

{
    "Destinations": ["9891xxxxxxx"],
    "Parameters": ["Mr.", "Saeed Saeedi", "Mellat"],
    "PatternId": "12345-pattern-id"
}

Sample Response:

{
    "message": "Successfully done.",
    "succeeded": true,
    "data": ["624ed1bbcd0efb1ef148e0a0"],
    "resultCode": 100
}

Utility Methods (Ping and IP Check)

IP Check

To check the user's IP, use the following method:

GET https://api.aradvas.ir/api/Tools/CheckIp

Response: Returns the user's IP address.

Ping Method

To check the server's health, use the following method:

GET https://api.aradvas.ir/api/Tools/Ping

Response: Returns `PONG`.

Error Codes

Here are the specific error codes for Arad SMS API:

Sending Errors

Code	Error	Description
0	Send Error	General error in sending message
-1	Not Enough Credit	Insufficient account balance
-2	Server Error	Server-side error
-3	DE ACTIVE Account	User account is deactivated
-4	Expired Account	User account has expired
-5	Invalid Username or Password	Incorrect username or password
-6	Authentication Failure	Authentication failed
-7	Server Busy	Server is currently busy
-8	Number At Blacklist	Recipient number is blacklisted
-9	Limited In Send Day	Daily sending limit exceeded
-10	Limited In Volume	Sending volume limit exceeded
-11	Invalid Sender Number	Invalid sender number
-12	Invalid Receiver Number	Invalid recipient number
-13	Invalid Destination Network	Invalid recipient network
-14	Unreachable Network	Recipient network is unreachable
-15	DE ACTIVE Sender Number	Sender number is deactivated
-16	Invalid Format of Sender Number	Incorrect format for sender number
-17	Tariff Not Found	No tariff found for the message
-18	Invalid IP Address	Sender IP address is invalid
-19	Invalid Pattern	Invalid message pattern
-20	Expired Sender Number	Sender number has expired
-21	Message Contains Link	Message contains a link
-22	Invalid Port	Invalid port specified
-23	Message Too Long	Message text is too long
-24	Filter Word	Message contains filtered words
-25	Invalid Reference Number Type	Incorrect reference number type
-26	Invalid Target UDH	Invalid UDH data
-27	Limited In Send Month	Monthly sending limit exceeded
-28	Data Coding Not Allowed	Data coding is not allowed
-29	Not Found Route	No route found for the message
-30	Message Contains Scripts	Message contains scripts
-31	Setting Not Found	Required settings not found
-32	Content Filter	Message content is filtered
-33	Invalid Character	Message contains invalid characters
-34	SMS Wallet Not Enough Credit	Insufficient SMS wallet credit
-35	Campaign Exists	The campaign already exists.
-36	Approver Not Found	The approver was not found.
-37	Due Date Less Than Current Date	The due date is earlier than the current date.
-38	Invalid Message Request ID	The message request ID is invalid.
-39	Message Request Not Waiting For Approve	The message request is not pending approval.
-40	Expire Date Less Than Due Date	The expiration date is earlier than the due date.
-41	Limited In Schedule	Scheduling limit exceeded.
-42	Too Many Requests	Too many requests sent in a short period.
-43	Cache Server Error	An error occurred in the cache server.

Delivery Status Codes

These codes represent the delivery status of your messages.

Code	Status	Description
1	Delivered	Message successfully delivered to the recipient's phone.
2	UnDelivered	Message was not delivered to the recipient.
3	Accepted	Message received by the service provider, pending send.
5	Rejected	Message rejected by the service provider.
7	ErrorInSending	An error occurred during message sending.
8	WaitingForSend	Message is waiting to be sent.
9	Sent	Message has been sent.
10	NotSent	Message was not sent.
11	Expired	Message expired before delivery.
14	BlackList	Recipient number is blacklisted.
15	SmsIsFilter	Message content was filtered.
16	Deleted	Message has been deleted.
29	Stored	Message has been stored.
32	Unknown	Delivery status is unknown.
33	Enroute	Message is en route; final status not determined.
34	Undeliverable	Message is undeliverable.
36	UnreachableNetwork	The recipient's network is unreachable.

API Return Codes

These codes indicate the API's response to your requests.

Code	Status	Description
100	Succeeded	The request was successfully processed.
101	Database Error	An error occurred in the database.
102	Repository Error	An error occurred in the repository layer.
103	Model Error	There is an error in the data model.
104	API Connection Attempt Failure	Failed to connect to the API.
105	Service Un-Available	The service is currently unavailable.
106	Confirm Email Failed	Email confirmation failed.
107	User Not Found	The user was not found.
108	Duplicate Error	The item already exists.
109	Not Found	The requested item was not found.
110	Unable To Create Result Api Error	Unable to create API response.
111	Auto Mapper Error	An error occurred during object mapping.
112	General Failure	A general failure occurred.
113	Web Service Error	An error occurred in a third-party web service.
114	Error Getting Token from Idp	Failed to retrieve token from identity provider (IdP).
115	Error Retrieving Data from AppSettings	Failed to retrieve data from application settings.
116	Header Error	The request headers were not correctly configured.
117	Bad Request Error	There was an issue with the request body.
118	Rate Limit Exceed Response	The user exceeded the allowed sending rate.
119	User Tariff Null	No tariff is assigned to the user.
120	Limit On Daily Submissions	The user has reached the daily sending limit.
121	Limit On Monthly Submissions	The user has reached the monthly sending limit.
122	Send To Whitelist Only	Sending is restricted to the whitelist only.
123	Enter Whitelist Template	Whitelist template name is required.
124	Enter Whitelist Message Text	Whitelist message text is required.
125	Whitelist Template Not Found	The specified whitelist template was not found.

Sample Requests

Here are some example requests to help you get started with the Arad SMS API.

1. Send Single SMS

POST https://api.aradvas.ir/api/{apiversion}/message/send
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Body:
[
  {
    "SourceAddress": "989000xxxx",
    "DestinationAddress": "9891xxxxxxxx",
    "MessageText": "Hello from Arad SMS !"
  }
]

2. Send Bulk SMS

POST https://api.aradvas.ir/api/{apiversion}/message/bulk
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Body:
{
  "SourceAddress": "989000xxxx",
  "MessageText": "Promotional offer from Arad!",
  "DestinationAddress": ["9891xxxxxxxx", "9891yyyyyyyy", "9891zzzzzzzz"]
}

3. Send P2P Bulk SMS

POST https://api.aradvas.ir/api/{apiversion}/message/P2PBulk
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Body:
{
  "SourceAddress": "989000xxxx",
  "Messages": [
    {
      "DestinationAddress": "9891xxxxxxxx",
      "MessageText": "Hello Ali! Your appointment is at 3 PM."
    },
    {
      "DestinationAddress": "9891yyyyyyyy",
      "MessageText": "Hello Sara! Your order #1234 has been shipped."
    }
  ]
}

4. Retrieve Incoming Messages (MO)

GET https://api.aradvas.ir/api/{apiversion}/message/getmo
Authorization: Bearer YOUR_ACCESS_TOKEN

5. Retrieve Delivery Reports

GET https://api.aradvas.ir/api/{apiversion}/message/dlr?messageId=624ed1bbcd0efb1ef148e0a0
Authorization: Bearer YOUR_ACCESS_TOKEN

Contact & Support

For further assistance or inquiries, please contact our support team:

Phone:

+98 31 91083200
+98 31 91083100

Email:

info@arad-itc.org

Web:

www.arad-itc.com

Our support team is available during business hours to assist with any technical issues or questions related to the API.

Thank you for using Arad SMS API. We look forward to helping you achieve seamless and reliable messaging solutions!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

English

Arad SMS API Documentation

Table of Contents

Introduction

Authentication

API Endpoints

API Access and Scopes

Scope: ApiAccess

Scope: ApiPatternAccess

Scope: BulkApiAccess

Scope: WhiteListAccess

Sending SMS

Bulk and P2P Messaging

Send SMS via GET

Receiving Messages

Delivery Reports

User Information

Pattern-Based Messaging

Utility Methods (Ping and IP Check)

IP Check

Ping Method

Response: Returns `PONG`.

Error Codes

Sending Errors

Delivery Status Codes

API Return Codes

Sample Requests

1. Send Single SMS

2. Send Bulk SMS

3. Send P2P Bulk SMS

4. Retrieve Incoming Messages (MO)

5. Retrieve Delivery Reports

Contact & Support

Clone this wiki locally

English

Arad SMS API Documentation

Table of Contents

Introduction

Authentication

API Endpoints

API Access and Scopes

Scope: ApiAccess

Scope: ApiPatternAccess

Scope: BulkApiAccess

Scope: WhiteListAccess

Sending SMS

Bulk and P2P Messaging

Send SMS via GET

Receiving Messages

Delivery Reports

User Information

Pattern-Based Messaging

Utility Methods (Ping and IP Check)

IP Check

Ping Method

Response: Returns PONG.

Error Codes

Sending Errors

Delivery Status Codes

API Return Codes

Sample Requests

1. Send Single SMS

2. Send Bulk SMS

3. Send P2P Bulk SMS

4. Retrieve Incoming Messages (MO)

5. Retrieve Delivery Reports

Contact & Support

Clone this wiki locally

Response: Returns `PONG`.