Url: https://api.tawasolsms.com/white-ip.php?ip=1.2.3.4
Request Method: POST

IP Address Verification:
The IP Address Verification allows users to check whether their IP address is allowed or not. If the IP address is not allowed, an OTP will be sent to the registered mobile number. Users can then verify the OTP using the Verify OTP API to activate their IP address.

IP address status (Allowed, Not Allowed)
BODY formdata

The API requires the following parameters in the form-data body: If an IP address is available, use it; otherwise, capture the user's IP address.

Name Value Description
Ip 1.2.3.4 IP Address

Authorization

The username and password are required to access the API.

Name Value Description
username user1 username
password 123456 Password

Example Request:
URL: https://api.tawasolsms.com/white-ip.php?ip=1.2.3.4
 Method: POST
Example Response:

Response Success (Allowed IP)


{
"success": true,
"message": "Your IP: 1.2.3.4 are allowed to access this API",
"code": 200
}

Response Failed (Not Allowed IP)


{
"success": false,
"message": "You are not allowed to access this API. An OTP was sent to your registered mobile numbers.",
"code": 403
}

Url: https://api.tawasolsms.com/verify-otp.php
Request Method: POST

This API allows users to verify a received OTP and activate their IP address. It ensures that only authorized users can validate their IPs using a one-time password.

Verify OTP For Current IP
BODY formdata

This API allows you to verify the received OTP and activate your IP address.

Name Value Description
ip 1.2.3.4 ip address
otp 123456 OTP

Authorization: Basic Auth
Name Value Description
username user1 username
password 123456 password

Example Request:
url: https://api.tawasolsms.com/verify-otp.php
Method: POST
Example Response:

Response Success (201 - OK )


{
    "success": true,
    "message": "Your IP: 1.2.3.4 is already verified",
    "code": 200
    }

Response Failed (201, failed)


{
    "success": false,
    "message": "Invalid Otp",
    "code": 201
}

Url: https://api.tawasolsms.com/auth.php
Request Method:POST

Using the access key, then receive a Response that includes your JWT access-token, which you will then provide in the Authorization each API

OR

Using the username and password, then receive a Response that includes your JWT access-token, which you will then provide in the Authorization each API

Use either the App SID or Access Key, or use the Username and Password to request a token

Using the access key


Name Value Description
access_key cvSc4T8NW1T9yqZLXHVrMYe2qxxxx you can use access key

Using username and password


Name Value Description
username user you can use username and password
password 1234567 you can use username and password

Example Request:
Url: https://api.tawasolsms.com/auth.php
Method: POST
Example Response:

Response Success (200 - OK )


{
    "success": true,
    "code": 200,
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6IlNlbmRUV1NMIiwiYWNjZXNzX2tleSI6InU4Mm9qVmNOUlE3RUlOZCIsIlZhbGlkVGlsbCI6IjIwMjUtMDItMjggMTc6MTk6MzkiLCJUaW1lWm9uZSI6IkFzaWFcL1JpeWFkaCJ9.QaEEV0ZjntV2sufhj3iv44O7_TzFqEG4A-tGhOTUP5M",
    "created_at": "2025-02-28 11:19:39",
    "valid_till": "2025-02-28 17:19:39",
    "time_zone": "Asia/Riyadh"
}

Response Failed 


{
    "success": false,
    "code": 404,
    "message": "User not found"
}

Url: https://api.tawasolsms.com/index.php
Request Method: POST

Use messages endpoint to send Single or Bulk SMS, Authorized using token. When you send SMS messages using this API, the API will return to you the sent messages’ ID to track them later.

Send Message
BODY formdata

Name Value Description
access_key cvSc4T8NW1T9yqZLXHVrMYe2qIxxxx Application Id
Body Your URL is https://tawasolsms.com Message content
mno 966xxxxxxxx1,966xxxxxxxx2 Mobile number, International format
senderName Tawasol sender id

Example Request:
url: https://api.tawasolsms.com/index.php
Method: POST
Example Response:

Response Success (200 - OK )




{
    "success": "true",
    "message": "ok",
    "errorCode": "ER-00",
    "data": {
        "MessageID": [
            "2503201440003957381"
        ],
        "MessageContent": "Your URL is https://tawasolsms.com",
        "Status": "Sent",
        "totalSms": 1,
        "totalRecipients": 1,
        "Balance": "Not requested",
        "Recipient": "966xxxxxxxx1,966xxxxxxxx2",
        "TimeCreated": "2025-03-20 14:40:00"
    }
}

Url: https://api.tawasolsms.com/index.php
Request Method: POST

Simple Single or Bulk SMS using SOAP included username and password. When you send SMS messages using this API, the API will return to you the sent messages’ ID to track them later.

Send Using SOAP
Authorization
Name Value Description
username user1 username
password 123456 password

PARAMS
Name Value Description
originator Tawasol Sender Id
recipientPhone 966xxxxxxxx1 Mobile number
smsText test sms Message content

Example Request:
Url:https://api.tawasolsms.com/index.php
Method: POST
Example Response:

Response Success (200 - OK )


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:pmm="http://pmmsoapmessenger.com/">
<soapenv:Header/>
<soapenv:Body>
    <pmm:SendSms>
        <pmm:user>
            <pmm:CustomerID>10008</pmm:CustomerID>
            <pmm:Name>SendXXXL</pmm:Name>
            <pmm:Language>en</pmm:Language>
            <pmm:Password>X0@12233</pmm:Password>
        </pmm:user>
        <pmm:originator>Tawasol</pmm:originator>
        <pmm:smsText>Call me later pls</pmm:smsText>
        <pmm:recipientPhone>966xxxx</pmm:recipientPhone>
        <pmm:messageType>Latin</pmm:messageType>
        <pmm:defDate>20150530120000</pmm:defDate>
        <pmm:blink>0</pmm:blink>
        <pmm:flash>0</pmm:flash>
        <pmm:Private>0</pmm:Private>
    </pmm:SendSms>
</soapenv:Body>
</soapenv:Envelope>

url: https://api.tawasolsms.com/index.php?user=user&pass=pass@123&sid=Tawasol&mno=966xxxxxxxx1&text=test sms&type=1
Request Method: GET

Simple Single or Bulk SMS using URL parametrs included username and password. When you send SMS messages using this API, the API will return to you the sent messages’ ID to track them later.

Send Using URL Parameters
PARAMS
Name Value Description
useruserusername
passpass@123password
sid Tawasol Sender Id
mno 966xxxxxxxx1 Mobile number
text test sms Message content
type 1 The type of message:
1 - English
2 - Unicode
3 - Special Character
4 - Arabic

Example Request:
Url: https://api.tawasolsms.com/index.php?user=user1&pass=pass@123&sid=Tawasol&mno=966xxxxxxxx1&text=test sms&type=1
Method: GET
Example Response:

Response Success (200 - OK )


{
    "success": "true",
    "message": "ok",
    "errorCode": "ER-00",
    "data": {
        "MessageID": [
            "2503201507578527991"
        ],
        "MessageContent": "test sms",
        "Status": "Sent",
        "totalSms": 1,
        "totalRecipients": 1,
        "Balance": "Not requested",
        "Recipient": "966xxxxxxxxx1",
        "TimeCreated": "2025-03-20 15:07:57"
    }
}

Url: https://api.tawasolsms.com/index.php
Request Method: POST

Use messages endpoint to send Single or Bulk SMS. When you send SMS messages using this API, the API will return to you the sent messages’ ID to track them later.

Send Message form or body
BODY formdata
Authorization
Token
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Name Value Description
Name Value Description
senderName Tawasol The name of the message sender
messageType 1 The type of message:
1 - English
2 - Unicode
3 - Special Character
4 - Arabic
messageText Your URL is: https://tawasolsms.com Message Content
recipients 966xxxxxxxx1 Mobile number

Example Request:
url:https://api.tawasolsms.com/index.php
Method: POST
Example Response:

Response Success (200 - OK )


{
    "success": "true",
    "message": "ok",
    "errorCode": "ER-00",
    "data": {
        "MessageID": [
            "2503201446406777571"
        ],
        "MessageContent": "Your URL is: https://tawasolsms.com",
        "Status": "Sent",
        "totalSms": 1,
        "totalRecipients": 1,
        "Balance": "Not requested",
        "Recipient": "966xxxxxxxx1",
        "TimeCreated": "2025-03-20 14:46:40"
    }
}

Url: https://api.tawasolsms.com/index.php
Request Method: POST

Use Bulk endpoint to send Bulk SMS . This can be achieved by sending an CSV file having the recipients phone numbers . When you send Bulk SMS request using this API, the API will return to you the Bulk ID to track them later.

Bulk Send using file
Authorization
Token
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

BODY formdata
Name Value Description
senderName Tawasol The name of the message sender
messageType 3 The type of message:
1 - English
2 - Unicode
3 - Special Character
4 - Arabic
shortURL true Set to true if the messageText contains a URL and you want to shorten it
messageText Your file URL is https://tawasolsms.com/file.pdf Message Content
recipients None The CSV file that contains the intended recipients' phone numbers

Example Request:
url: https://api.tawasolsms.com/index.php
Method: POST
Example Response:

Response Success (200 - OK )


{
    "success": "true",
    "message": "ok",
    "errorCode": "ER-00",
    "data": {
        "MessageID": [
            "2503201449277567601"
        ],
        "MessageContent": "Your file url is https://tawasolsms.com/file.pdf",
        "Status": "Sent",
        "totalSms": 1,
        "totalRecipients": 1,
        "Balance": "Not requested",
        "Recipient": "966xxxxxxxx1",
        "TimeCreated": "2025-03-20 14:49:27"
    }
}

Url: https://api.tawasolsms.com/dlr.php?message_id=2503101521175975331
Request Method: GET

You can track any SMS you have sent using its ID by submitting the Get Message Details by ID API request. The API will return the details of the SMS message you want to track, such as the account ID that sent the SMS, SMS delivery status and the SMS sent date.

Getting Message Details
Authorization
Token
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

PARAMS
Name Value Description
message_id 2503101521175975331 Message Id

Example Request:
url: https://api.tawasolsms.com/dlr.php?message_id=2503101521175975331
Method: GET
Example Response:

Response Success (200 - OK )


{
    "success": true,
    "message_id": "2503101521175975331",
    "status": "DELIVRD",
    "message": "ok",
    "errorCode": "ER-00"
}

Url: https://api.tawasolsms.com/count.php
Request Method: GET

You can know the count of SMS messages you have sent during a certain period. The API will return an integer that represents the count of SMS messages sent during the provided date range in the API request.To use Get Sent Messages Count API, first submit an HTTP Request with the date range, then receive a Response that includes the count of SMS messages sent during the provided date range.

Getting Messages Count
Authorization
Token
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Authorization
Name Value Description
username user1 Username
password 123456 Password

Example Request:
url:https://api.tawasolsms.com/count.php
Method: GET
Example Response:

Response Success (200 - OK )


{
    "success": "true",
    "message": "ok",
    "errorCode": "ER-00",
    "data": {
        "Count": "14",
        "datetime": "2025-03-20 14:53:36"
    }
}

Url: https://api.tawasolsms.com/messages.php
Request Method: GET

You can track the messages you have sent during a certain period by submitting the Get Messages Details. The API will return an array of multiple records. Each record includes the details of an SMS message that was sent during the provided date range in the API request. You can also specify the number of SMS messages you want to receive per response page, as well as the response page index number you want to receive.

Retrieving SMS Messages
Example Request:
url: ttps://api.tawasolsms.com/messages.php
Method: GET
Authorization
Token
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

BODY formdata
Name Value
pageLength 10
pageNumber 1
fromDate 2025-03-11 00:00:00
toDate 2025-03-20 23:59:59

Example Response:

Response Success (200 - OK )


{
    "success": "true",
    "message": "ok",
    "errorCode": "ER-00",
    "fromDate": "2025-03-01 00:00:00",
    "toDate": "2025-03-11 00:00:00",
    "data": [
        {
            "msg_id": "2503101730240637891",
            "time": "2025-03-10 17:30:24",
            "sender": "Tawasol",
            "destination": "966xxxxxxxx1"
        },
        {
            "msg_id": "2503101730240537881",
            "time": "2025-03-10 17:30:24",
            "sender": "Tawasol",
            "destination": "966xxxxxxxx1"
        },
        {
            "msg_id": "2503101725437597871",
            "time": "2025-03-10 17:25:43",
            "sender": "Tawasol",
            "destination": "966xxxxxxxx1"
        },
        {
            "msg_id": "2503101659138517551",
            "time": "2025-03-10 16:59:13",
            "sender": "Tawasol",
            "destination": "966xxxxxxxx1"
        },
        {
            "msg_id": "2503101659138487541",
            "time": "2025-03-10 16:59:13",
            "sender": "Tawasol",
            "destination": "966xxxxxxxx2"
        },
        {
            "msg_id": "2503101657328787531",
            "time": "2025-03-10 16:57:32",
            "sender": "tawasolSMS",
            "destination": "966xxxxxxxx2"
        },
        {
            "msg_id": "2503101656557817521",
            "time": "2025-03-10 16:56:55",
            "sender": "tawasolSMS",
            "destination": "966xxxxxxxx2"
        },
        {
            "msg_id": "2503101655501817511",
            "time": "2025-03-10 16:55:50",
            "sender": "Tawasol",
            "destination": "966xxxxxxxx1"
        },
        {
            "msg_id": "2503101655501767501",
            "time": "2025-03-10 16:55:50",
            "sender": "Tawasol",
            "destination": "966xxxxxxxx2"
        },

    ],
    "pagination": {
        "total": 1356,
        "current_page": 1,
        "page_length": 10,
        "total_pages": 136
    }
}

Url:https://api.tawasolsms.com/balance.php
Request Method: GET

Through Get Your Current Balance API, you can directly retrieve your current account balance. You can also get the current balance.

Getting Account Balance
Example Request:
url: https://api.tawasolsms.com/balance.php
Method: GET

Authorization
Name Value
token xxxxxxxxxxxxxxxxxxx

Example Response:

Response Success (200 - OK )


{
    "success": "true",
    "message": "ok",
    "errorCode": "ER-00",
    "data": {
        "Username": "user",
        "Balance": "986"
    }
}

Url: https://api.tawasolsms.com/index.php
Request Method: POST

Personalized SMS is a type of Short Messages that generated from rendering a template , A template is a text that contains a special text that contains variables, Those variable got substituted at the runtime.

Personalized Send
Example Request:
url:https://api.tawasolsms.com/index.php
Method: POST
BODY formdata
Name Value Description
senderName Tawasol Sender Id
messageText Hi {{Name}}, your Salary is {{Salary}} Message Content
recipients 966xxxxxxxx1,966xxxxxxxx2 The intended recipients’ phone numbers (comma-separated)
replacementList employeeX,500$ An array of variable lists. The delimiter between each variable list is ';' and between variables is ','

Example Response:

Response Success (200 - OK )


{
    "success": "true",
    "message": "ok",
    "errorCode": "ER-00",
    "data": {
        "MessageID": [
            "2404161120325302182",
            "2404161120325332192"
        ],
        "MessageContent": "Hi employeeX your Salary is 500$",
        "Status": "Sent",
        "totalSms": 2,
        "totalRecipients": 2,
        "Balance": "178023",
        "Recipient": "966xxxxxxxx1,966xxxxxxxx2",
        "TimeCreated": "2024-04-16 11:19:13",
        "bulkId": "Bulk661e3481739a7"
    }
}

Url: https://api.tawasolsms.com/index.php Request Method: POST

Use Personalized Bulk endpoint to send Bulk SMS with different message text. The Endpoint accepts CSV file contains recipient numbers with corresponding message text.

Personalized Bulk Send using file
Example Request:
url:https://api.tawasolsms.com/index.php
Method: POST
Authorization
Token
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

BODY formdata
Name Value Description
senderName Tawasol The name of the message sender
recipients None The CSV file that contains the intended recipients' phone numbers and message content for each number.

Example Response:

Response Success (200 - OK )


{
    "success": "true",
    "message": "ok",
    "errorCode": "ER-00",
    "data": {
        "Balance": "178017",
        "faileds": [],
        "sendErrors": [],
        "bulkId": "Bulk661e34fe556ac",
        "totalRecipients": 3,
        "totalSms": 3,
        "messages": [
            {
                "MessageID": [
                    "2404161122388024072"
                ],
                "MessageContent": "Hello world test message",
                "Status": "Sent",
                "totalSms": 1,
                "Recipient": "966xxxxxxxx1",
                "TimeCreated": "2024-04-16 11:21:19"
            },
            {
                "MessageID": [
                    "2404161122400384102"
                ],
                "MessageContent": "Hello world test message 31",
                "Status": "Sent",
                "totalSms": 1,
                "Recipient": "966xxxxxxxx2",
                "TimeCreated": "2024-04-16 11:21:20"
            },
            {
                "MessageID": [
                    "2404161122402094112"
                ],
                "MessageContent": "Hello world test message 311",
                "Status": "Sent",
                "totalSms": 1,
                "Recipient": "966xxxxxxxx3",
                "TimeCreated": "2024-04-16 11:21:20"
            }
        ]
    }
}