Introduction

With our amazing REST, easy, and smart “Verify” APIs, integration of OTP SMS into your app is a breeze! Just two simple steps and you'll be up and running in seconds! Generate the code, verify it, and you're ready to go!




APIs Features:

Connecting to taqnyat.sa API is a breeze! Simply use HTML forms to send data as POST, or send data to the API URL directly using Query String and send the data as "GET". For larger amounts of data, we recommend using POST, as GET does not support sending large amounts of data. Additionally, you can send data in JSON - a full description of the JSON Data method can be found in this document. taqnyat.sa also returns data in the most common format, JSON. When connecting to taqnyat.sa API through HTTP/HTTPS protocols, the SMS data must be in a certain format. For example, Sender Name must be encoded using URL-Encoding and the message text must be in UTF-8 encoding.




Before you go

• We recommended the one who is going to use this documentation or APIs to have programming skills. • The testing cost is nothing because we offer a free startup balance of 1 SAR for any trial account. • Cost calculation for messaging depends on how many messages you will send and how many destinations it will be receiving the messages. • 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. • When you send SMS through API, mobile numbers that will receive the SMS must be in international format without 00 or symbol (+) • 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/verify.php`]


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 within the header Authorization.




Setup Bearer token

With Taqnyat you can set up your bearer token in seconds using the below steps: • Login to your account at Taqnyat. • Select Application from Developer section. • Press the add button on the top right corner. • Choose a suitable name for your application. • Select the services you want this app to include, in our case SMS. • Hit the confirm button to submit your application. • Copy the Bearer Tokens.




Generate new OTP Verification

This resource used to generate the OTP.

POST https://api.taqnyat.sa/verify.php
Parameter Description Required
apiKey The Bearer Token from Taqnyat portal Yes
numbers Array of strings, of numbers started with international 966 Yes
sender message sender No
method specifies how to send the verification code, for now we only support SMS No
lang specifies the language of SMS message, “en” or “ar”, “ar “is the default No
requestId you can specify a unique ID for each verification process through this variable. If this variable is passed to the verify API, it must be used during the check verification code process No
note text to be appended to message No
returnJson when send this variable with value 1 the result will be return in JSON format No

Sample

[
    {
        "apiKey": "*************************",
        "numbers": [
            "966000000000"
        ],
        "method": "sms",
        "lang": "ar",
        "requestId": "1",
        "note": "some note"
    }
]



Check OTP Verification

This resource used to generate the OTP.

POST https://api.taqnyat.sa/verify.php
Parameter Description Required
apiKey The Bearer Token from Taqnyat portal Yes
numbers Array of strings, of numbers started with international 966 Yes
sender message sender No
method specifies how to send the verification code, for now we only support SMS No
lang specifies the language of SMS message, “en” or “ar”, “ar “is the default No
requestId you can specify a unique ID for each verification process through this variable. If this variable is passed to the verify API, it must be used during the check verification code process No
note text to be appended to message No
returnJson when send this variable with value 1 the result will be return in JSON format No
activeKey The code received on the number Yes

Sample

[
    {
        "apiKey": "*************************",
        "numbers": [
            "966000000000"
        ],
        "method": "sms",
        "lang": "ar",
        "requestId": "1",
        "note": "some note",
        "activeKey": "6240"
    }
]



Results values

code Description
0 Connection failed to Taqnyat server
1 invalid apiKey
3 Mobile number is not specified or incorrect.
4 Your balance is not enough.
5 Activation code sent successfully.
6 Unknown error Please contact technical support, this case holds more than one error such as: Sender name is not authorized or Your balance is 0.
7 The activation code has already been sent, you can re-send it in second, Get JSON result form more details
8 You have exceeded the allowed number of attempts, change requestId to verify mobile number.
10 Activation process completed successfully.
11 Activation code is incorrect.
12 Attempts to enter activation code have been exhausted.
13 This number is activated
×