Download API SPEC

API Reference

With our REST, easy, and smart “SMS” APIs we allow you to integrate SMS at your app and get started in seconds, With Taqnyat, building a solution with SMS capabilities never been easier, a few lines of code will enable the SMS to create a magnificent app fit with your business needs.

In the below guide, we'll walk you through and explain how Taqnyat SMS API work:

APIs Features:

Connecting to taqnyat.sa API is simple & easy, you can do it using HTML forms, which will send the data as POST, or send data to API URL directly using Query String, which will send the data as "GET". If you want to send a large amount of data, we recommend that you use the first method, which is POST; because the second method GET does not support sending a large amount of data. Besides, you can send data in JSON, a full description of the JSON Data method will be in this document.

taqnyat.sa also returns the data in the most common format, which is JSON.

When you connect to taqnyat.sa API through HTTP/HTTPS protocols, the SMS data must be in a certain format as follows: Sender Name must be encoded using URL-Encoding and message text must be in UTF-8 encodings:


Before you go

  1. We recommended the one who is going to use this documentation or APIs to have programming skills.
  2. The testing cost is nothing because we offer a free startup balance of 1 SAR for any trial account.
  3. Cost calculation for messaging depends on how many messages you will send and how many destinations it will be receiving the messages.
  4. If you want to try to send SMS API, we advise you to send scheduled SMS, so you can check if they reached “Scheduled SMS Archive” in your taqnyat.sa account, then you may delete the SMS to spare the cost and get your balance back.
  5. When you send SMS through API, mobile numbers that will receive the SMS must be in international format without 00 or symbol (+)
  6. You must have an active sender name before you go, you may contact support@taqnyat.sa or account manager to get more details about the requirements and how to activate your Sender Name.



Base URL

All URLs resources in the SMS documentation have the base URL
https://api.taqnyat.sa/


Authentication

To use our API, you will need a unique Bearer token generated from your account at our platform by following the below steps Setup Bearer token

For REST API Bearer token must be submitted withen the header Authorization.


If you failed to authenticate the request, response header with error 401 expected to return.
You need to make sure passing the correct credential.

Setup Bearer token

With Taqnyat you can set up your bearer token in seconds using the below steps:

  1. Login to your account at Taqnyat.
  2. Select Application from Developer section.
  3. Press the add button on the top right corner.
  4. Choose a suitable name for your application.
  5. Select the services you want this app to include , in our case SMS.
  6. Hit the confirm button to submit your application.
  7. Copy the Bearer Tokens.

×




Let us Get started:

To use taqnyat.sa API, you should have a taqnyat.sa account, here is an explanation of how you can register, checking your current balance, request a recharge for your balance through a “request recharge form” in taqnyat.sa website.

  1. Registration process: You can register on taqnyat.sa website through the following link: Contact and go to Sales tab ,fill the form and hit send.

  2. Check your balance: You can check your current balance from the website after you logged at the dashboard.

  3. Balance Topup: After your login to your https://www.taqnyat.sa account, you can request recharging your balance, through the request top-up form, you can access it through the balance top-up tab located in the left top corner. Fill all the required data in the form and we will top up your account within two hours at most after we validate the deposit.

  4. Using bearer Tokens: bearer Tokens will have a unique value generated in the taqnyat.sa user account , because it provides a more secure connection with the API.

  5. Setup API settings: taqnyat.sa provides security settings that allows you to control SMS sending through API. You can enable or disable sending SMS through API from your account, grant permission to specific IP’s to be allowed to send SMS message through API using your account, and grant permission to specific countries to be allowed to send SMS message through API using your account.



System

System resources are used to retrieve info about the system.


Status

...

This method used to retrieve status for one or multiple services in the system.
Authorization is not required .

GET ​/system/status
Here are some examples of HTTP API:
https://api.taqnyat.sa/system/status

if the request submitted successfully header status of 200 will be return as follows:

{
    statusCode: 200,
    status: {
        service: "none",
        description: "All Services are Operational"
    }
}

if the request return header 405 , you are using RESTFull API and have used unauthorized method for example
if the System resource allow only get , and you used post error 405 expected to return.

{
    "statusCode": 405,
    "message": "Method Not Allowed"
}





Account

Account resources are used to retrieve info about you account.


Balance

This resource is used to retrieve Status, balance, and other info about your account.
Authorization is required.

GET /account/balance

Here are some examples of HTTP API:

https://api.taqnyat.sa/account/balance?
    bearerTokens=xxxxxxxxxxxxxxxxxxxxxxxxxx

if the request submitted successfully header status of 200 will be return as follows:

{
    "statusCode": 200,
    "accountStatus": "active",
    "accountExpiryDate": "23-08-2021",
    "balance": "2044.000",
    "currency": "SAR"
}

if the request return header 401 , you are using wrong bearer Tokens
make sure to follow the steps in above to setup your bearer Token Setup Bearer token


{
    "statusCode": 401,
    "message": "invalid credentials information"
}

if the request return header 405 , you are using RESTFull API and have used unauthorized method for example
if the System resource allow only get , and you used post error 405 expected to return.

{
    "statusCode": 405,
    "message": "Method Not Allowed"
}




Messages

Messages resources are used to deal with messages.


Message Without Template

This resource used to send message(s) from your account.

Authorization is required .


POST /v1/messages

Parameter Description Required
recipients Array of international format without 00 or symbol (+) Yes
body The Content of the message Yes
sender Pre Define sender name at your account Yes
scheduledDatetime Schedule the message to send later IE: 2020-09-30T14:26 No

Here is some example of HTTP API:

https://api.taqnyat.sa/v1/messages?
    bearerTokens=xxxxxxxxxxxxxxxxxxxxxxxxxx&
    sender=test&
    recipients=966500000000,966500000000&
    body=bodyTest

if the request submitted successfully header status of 201 will be return as follows:

{
    "statusCode": 201,
    "messageId": 5452899970,
    "cost": 0.026,
    "currency": "SAR",
    "totalCount": 1,
    "msgLength": 1,
    "accepted": "[966500000000,]",
    "rejected": "[]"
}

if the request return header 401 , you are using wrong bearer Tokens
make sure to follow the steps in above to setup your bearer Token Setup Bearer token

{
    "statusCode": 401,
    "message": "invalid credentials information"
}

if the request return header 405 , you are using RESTFull API and have used unauthorized method for example
if the System resource allow only get , and you used post error 405 expected to return.

{
    "statusCode": 405,
    "message": "Method Not Allowed"
}

if the request return header 400 , its mean the request has not submitted successfully and the error code in the response will explain the issue
you can scroll down to the error list to understand what type of error you have.






Messaging Template

This resource is used to send messages using a template.

Send a JSON request with Content-Type: application/json; charset=UTF-8. Include your API token in the Authorization header as a Bearer token.


Authorization is required .


POST /v1/messages

Parameter Description Required
recipients Array of international phone numbers without 00 or (+), for example ["966500000000"]. Yes
templateName Name of the template to use. Yes
sender Sender name predefined in your account. Yes
campaignName Name of the campaign. No
variables Object containing template variable names and their values, for example {"code":"1234"}. Conditional

Example JSON request:

curl --location 'https://api.taqnyat.sa/v1/messages' \
--header 'Content-Type: application/json; charset=UTF-8' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data '{
  "sender": "Taqnyat",
  "recipients": [
    "966500000000"
  ],
  "campaignName": "Campaign-Name",
  "templateName": "Template-Name",
  "variables": {
    "code": "1234"
  }
}'

if the request submitted successfully header status of 201 will be return as follows:

{
    "statusCode": 201,
    "messageId": 5452899970,
    "cost": 0.026,
    "currency": "SAR",
    "totalCount": 1,
    "msgLength": 1,
    "accepted": "[966********,]",
    "rejected": "[]"
}

if the request return header 401 , you are using wrong bearer Tokens
make sure to follow the steps in above to setup your bearer Token Setup Bearer token

{
    "statusCode": 401,
    "message": "invalid credentials information"
}

if the request return header 405 , you are using RESTFull API and have used unauthorized method for example
if the System resource allow only get , and you used post error 405 expected to return.

{
    "statusCode": 405,
    "message": "Method Not Allowed"
}

if the request return header 400 , its mean the request has not submitted successfully and the error code in the response will explain the issue
you can scroll down to the template error list to understand what type of error you have.






Schedule (POST)

POST /v1/messages

Parameter Description Required
recipients Array of international format without 00 or symbol (+) Yes
body The Content of the message Yes
sender Pre Define sender name at your account Yes
scheduledDatetime Schedule the message to send later IE: 2020-09-30T14:26 Yes
deleteId this id will be used to selete the schedule message No

Here is some example of HTTP API:

https://api.taqnyat.sa/v1/messages?
    bearerTokens=xxxxxxxxxxxxxxxxxxxxxxxxxx&
    sender=test&
    recipients=966500000000,966500000000&
    body=bodyTest&
    scheduledDatetime=2020-09-30T14:26

if the request submitted successfully header status of 201 will be return as follows:

{
    "statusCode": 201,
    "messageId": 5452899970,
    "cost": 0.026,
    "currency": "SAR",
    "totalCount": 1,
    "msgLength": 1,
    "accepted": "[966500000000,]",
    "rejected": "[]"
}

if the request return header 401 , you are using wrong bearer Tokens
make sure to follow the steps in above to setup your bearer Token Setup Bearer token

{
    "statusCode": 401,
    "message": "invalid credentials information"
}

if the request return header 405 , you are using RESTFull API and have used unauthorized method for example
if the System resource allow only get , and you used post error 405 expected to return.

{
    "statusCode": 405,
    "message": "Method Not Allowed"
}

if the request return header 400 , its mean the request has not submitted successfully and the error code in the response will explain the issue
you can scroll down to the error list to understand what type of error you have.




Schedule (DELETE)


This resource used to delete a message from messages scheduled queue.
Authorization is required .


DELETE ​/v1/messages/delete

You can make sure the message has been deleted successfuly by access to our portal https://api.taqnyat.sa/ from Manage SMS section and select Scheduled SMS , and make sure the message you've schedualed not exsist.

Parameter Description Required
deleteId Message id you want to delete Yes

Here are some examples of HTTP API:

https://api.taqnyat.sa/v1/messages/delete?
    bearerTokens=xxxxxxxxxxxxxxxxxxxxxxxxxx&
    deleteId=100

if the request submitted successfully header status of 201 will be return as follows:

{
    "statusCode":201,
    "message":"Deleted successfully"
}

if the request return header 401 , you are using wrong bearer Tokens
make sure to follow the steps in above to setup your bearer Token Setup Bearer token

{
    "statusCode": 401,
    "message": "invalid credentials information"
}

if the request return header 422 , you have submitted wrong deleteId
make sure to pass the correct deleteId with your request.

{
    "statusCode":422,
    "message":"Invalid deleteKey"
}

if the request return header 405 , you are using RESTFull API and have used unauthorized method for example
if the System resource allow only get , and you used post error 405 expected to return.

{
    "statusCode": 405,
    "message": "Method Not Allowed"
}



Senders

This resource used to manage sender names from your account.

Authorization is required .


GET /v1/messages/senders

To define new sender

  • Request the New sender Form , from your account manager.
  • Fill the sender information on the sender form using your company letter head.
  • Provide your company valid certification.
  • send both form and certification to your account manager.
  • you will be notified once your sender is approved by the operators .



Here are some examples of HTTP API:

https://api.taqnyat.sa/v1/messages/senders?
    bearerTokens=xxxxxxxxxxxxxxxxxxxxxxxxxx

if the request submitted successfully header status of 201 will be return as follows:

{
    "statusCode": 201,
    "senders": [
        {
            "senderName": "sender name 1",
            "status": "active",
            "destination": "KSA"
        },
        {
            "senderName": "sender name 2",
            "status": "active",
            "destination": "international"
        }
    ]
}

if the request return header 401 , you are using wrong bearer Tokens
make sure to follow the steps in above to setup your bearer Token Setup Bearer token

{
    "statusCode": 401,
    "message": "invalid credentials information"
}

if the request return header 405 , you are using RESTFull API and have used unauthorized method for example
if the System resource allow only get , and you used post error 405 expected to return.

{
    "statusCode": 405,
    "message": "Method Not Allowed"
}




Error Code

Below on the table list for code in the response , if the header returned 400 .
lookup the code of the response with code on the table for better understanding the error cause.

Error Code Error Description
2 Your balance is 0 Your balance has been consumed and you need to top up your account to restore the ability to send messages again.
3 Your balance is not enough Your account has a low balance and does not cover all messages you are about to send.
6 SMS-API not responding , please try again Error connecting to the server, due to scheduled maintenance, better try again later on.
13 Sender Name is not accepted Sender name used is not correct, make sure to include the sender name as it is shown at your account (case sensitive)
14 Sender Name not active Sender name used is not among your active sender name, you may check the active senders using Check Sender
15 Mobile(s) number(s) is not specified or incorrect All destination mobile numbers must be submitted with international format without 00 or symbol (+)
16 Sender Name is not specified Sender name is required for sending messages, make sure the parameter "sender" is provided with your request
17 Message text is not specified Message content is required for sending messages, make sure the parameter "body" is provided with your request
18 Sending SMS stopped from support Your account has a problem, you need to contact support@taqnyat.sa
21 no data for this msg The request has return no data, you may contact support@taqnayt.sa to get more details about the request results.
22 The number of recipients is greater than 1000 The max allowed recipients per request are 1000 destination
24 Sender Name is expired Your Sender Name is expierd, you need to contact support@taqnayt.sa
101 sending by API is disabled You need to go to Developers on the left side of the screen, then click on Security Settings, and make sure that "Disable send SMS using API" is enabled.
102 this ip Not authorized to using the API You need to go to Developers on the left side of the screen, then click on Security Settings, and make sure that the IP is authorized to send.
103 this country Not authorized to using the API to send to this country, you need to contact support@taqnayt.sa
104 you can't use proxy to send Your account has a problem, you need to contact support@taqnayt.sa
130 Error while checking the template خطأ أثناء التحقق من القالب
فشل استعلام قاعدة البيانات أثناء البحث عن القالب.
131 Template name does not exist or is not active اسم القالب غير موجود أو غير فعال
اسم القالب غير موجود للمستخدم والمرسل.
132 Invalid template variable configuration تعريف المتغيرات في القالب غير صحيح
عدد أو أسماء المتغيرات في إعدادات القالب لا تطابق تعريف القالب.
132 Undefined type for variable: {variableName} نوع المتغير {variableName} غير معرف
نوع المتغير المحفوظ في القالب غير معرف.
133 Invalid variables format صيغة المتغيرات غير صحيحة
صيغة بيانات المتغيرات ليست مصفوفة أو JSON صحيحًا.
134 Variables count does not match template. Expected: {count} عدد المتغيرات لا يطابق القالب. المطلوب: {count}
عدد المتغيرات المرسلة لا يساوي العدد المطلوب.
135 Missing variable: {variableName} المتغير {variableName} غير موجود
أحد أسماء المتغيرات المطلوبة غير موجود في الطلب.
136 Invalid value for variable: {variableName} قيمة المتغير {variableName} غير صحيحة
قيمة المتغير ليست نصًا أو رقمًا.
136 Invalid characters or spaces in variable: {variableName} المتغير {variableName} يحتوي على أحرف أو مسافات غير صحيحة
قيمة فارغة، أو تحتوي على مسافات أو أحرف غير مسموحة، أو UTF-8 غير صالح.
137 Variable {variableName} exceeds maximum length: {maxLength} المتغير {variableName} يتجاوز الحد المسموح: {maxLength}
طول المتغير يتجاوز الحد المسموح، أو الحد غير صالح.
138 Invalid type for variable {variableName}. Expected: {type} قيمة المتغير {variableName} غير مطابقة للنوع المطلوب: {type}
قيمة المتغير لا تطابق نوعه المسجل.
139 Company name is missing for awareness template اسم الشركة غير معرف للقالب التوعوي
لا يوجد اسم شركة للقالب التوعوي.



Callback


DELETE ​CallBack

Callback URL or "webhook" used to feed your system with messages status once it's updated, you can enable this feature by providing a URL using the below setps.

Callback required to send us a safe phrase to confirm callback receiving , other wise our server will keep sending the same callback considering the previous attempts failed , this loop will continue up to three attempts and we will discontinue calling back after that.


To configure your callback URL or "webhook" simply flow those steps:

  1. Login to your account at portal.taqnyat.sa.
  2. Select Developer tools from Developer section.
  3. Fill your Webhook URL at Webhook URL.
  4. Enter your pass Phrase , that will be used for confirming callback receiving.
  5. Hit save to confirm modifications.