aql Home Contact Us

APIs

Messaging APIs

Sign up to start using our APIs

Inbound SMS

List SMS relay actions

get
GET v2/sms-relay/geo/actions

Returns a list of all actions available for use on your account

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Response Fields (Success 200)

Field Type Description
Field: name Type: String Description:

The name of the action
Field: description Type: String Description:

Action description

curl [[DOMAIN]]v2/sms-relay/geo/actions
-X GET
-H "Content-type: application/json"
-H "X-Auth-Token: {{YOUR_API_TOKEN}}"

Send a Sample Request

GET

Header

Code Examples

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com/v2/sms-relay/geo/actions");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
$response = curl_exec($curl);
curl_close($curl);
import requests

url = "https://api.aql.com/v2/sms-relay/geo/actions"

headers = {
    'x-auth-token': "{{YOUR_API_TOKEN}}",
    'content-type': "application/json"
    }

response = requests.get(url, headers=headers)

print(response.text)
var client = new RestClient("https://api.aql.com/v2/sms-relay/geo/actions");
var request = new RestRequest(Method.GET);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");

IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $endpoint = '/v2/sms-relay/geo/actions';

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->GET($endpoint);
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 200 OK
{
  "data": [
    {
      "name": "black_hole",
      "description": "Do nothing"
    },
    {
      "name": "http_post",
      "description": "HTTP POST"
    },
    {
      "name": "http_get",
      "description": "HTTP GET"
    },
    {
      "name": "email",
      "description": "Email"
    }
  ]
  "meta": {
    "pagination": {
      "total": 4,
      "count": 4,
      "per_page": 15,
      "current_page": 1,
      "total_pages": 1,
      "links": []
    }
  }
}

List SMS relays

get
GET v2/sms-relay/geo

Returns a list of all available SMS relay numbers on the account

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Parameter

Parameter Type Required Description
Parameter: prefix Type: String Required: No Description:

An optional filter to only show numbers matching the specified query. Can accept * as a wildcard.

Response Fields (Success 200)

Field Type Description
Field: id Type: String Description:

The ID of the relay object
Field: prefix Type: String Description:

The prefix being affected
Field: action Type: Object Description:

The relay action associated with the prefix
Field: action.name Type: String Description:

The relay action name. Possible values are: black_hole, http_get, http_post, email, mvno If the action type of a prefix is currently set to 'mvno', this means that the messages cannot be forwarded to any external destination
Field: action.description Type: String Description:

The relay action description
Field: action.parameters Type: Array Description:

The parameters associated with the action. The values will depend on the selected action type For example, a list of destination email addresses in case of 'email' action or a list of http endpoints for 'http_get' or 'http_post' actions
Field: updated_at Type: Datetime Description:

The time of the most recent update

Send a Sample Request

GET

Header

Parameter

Code Examples

curl https://api.aql.com/v2/sms-relay/geo \
-X GET \
-H "Content-type: application/json" \
-H "X-Auth-Token: {{YOUR_API_TOKEN}}"
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com/v2/sms-relay/geo");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
$response = curl_exec($curl);
curl_close($curl);
import requests

url = "https://api.aql.com/v2/sms-relay/geo"

headers = {
    'x-auth-token': "{{YOUR_API_TOKEN}}",
    'content-type': "application/json"
    }

response = requests.get(url, headers=headers)

print(response.text)
var client = new RestClient("https://api.aql.com/v2/sms-relay/geo");
var request = new RestRequest(Method.GET);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");

IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $endpoint = '/v2/sms-relay/geo';

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->GET($endpoint);
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": "2Axr6kl8opBk",
      "action": {
        "name": "black_hole",
        "prefix": "441131234",
         "description": "Do nothing",
         "parameters": []
      },
      "updated_at": {
        "date": "2011-08-23 08:39:19.000000",
        "timezone_type": 2,
        "timezone": "GMT"
      }
    },
    {
      "id": "7dpzWM18jBgr",
      "action": {
        "name": "email",
        "prefix": "441137654",
         "description": "Email",
         "parameters": [
           "[email protected]"
         ]
      },
      "updated_at": {
        "date": "2011-08-23 08:39:19.000000",
        "timezone_type": 2,
        "timezone": "GMT"
      }
    }
  ]
  "meta": {
    "pagination": {
      "total": 2,
      "count": 2,
      "per_page": 15,
      "current_page": 1,
      "total_pages": 1,
      "links": []
    }
  }
}

Show SMS relay

get
GET v2/sms-relay/geo/:relay

Returns a single SMS relay object

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Parameter

Parameter Type Required Description
Parameter: relay Type: String Required: Yes Description:

The alphanumeric ID of SMS relay object to show

Response Fields (Success 200)

Field Type Description
Field: id Type: String Description:

The ID of the relay object
Field: prefix Type: String Description:

The prefix being affected
Field: action Type: Object Description:

The relay action associated with the prefix
Field: action.name Type: String Description:

The relay action name. Possible values are: black_hole, http_get, http_post, email, mvno If the action type of a prefix is currently set to 'mvno', this means that the messages cannot be forwarded to any external destination
Field: action.description Type: String Description:

The relay action description
Field: action.parameters Type: Array Description:

The parameters associated with the action. The values will depend on the selected action type For example, a list of destination email addresses in case of 'email' action or a list of http endpoints for 'http_get' or 'http_post' actions
Field: updated_at Type: Datetime Description:

The time of the most recent update

Send a Sample Request

GET

Header

Parameter

Code Examples

curl https://api.aql.com/v2/sms-relay/geo/:relay \
-X GET \
-H "Content-type: application/json" \
-H "X-Auth-Token: {{YOUR_API_TOKEN}}"
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com/v2/sms-relay/geo/:relay");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
$response = curl_exec($curl);
curl_close($curl);
import requests

url = "https://api.aql.com/v2/sms-relay/geo/:relay"

headers = {
    'x-auth-token': "{{YOUR_API_TOKEN}}",
    'content-type': "application/json"
    }

response = requests.get(url, headers=headers)

print(response.text)
var client = new RestClient("https://api.aql.com/v2/sms-relay/geo/:relay");
var request = new RestRequest(Method.GET);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");

IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $endpoint = '/v2/sms-relay/geo/:relay';

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->GET($endpoint);
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 200 OK
{
  "data":
    {
      "id": "2Axr6kl8opBk",
      "action": {
        "name": "black_hole",
        "prefix": "441131234",
         "description": "Do nothing",
         "parameters": []
      },
      "updated_at": {
        "date": "2011-08-23 08:39:19.000000",
        "timezone_type": 2,
        "timezone": "GMT"
      }
    }
  }
}

Update SMS relay

patch
PATCH v2/sms-relay/geo/:relay

Update an SMS relay object

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Parameter

Parameter Type Required Description
Parameter: relay Type: String Required: Yes Description:

The alphanumeric ID of SMS relay object to update
Parameter: action Type: String Required: Yes Description:

The name of the action to be assigned. Accepted values are: black_hole, http_get, http_post, email If you modify the action type from 'mvno' to some other method of delivery, this will mean that MT messages will no longer be delivered to the MVNO sim this prefix is associated with. It is important to note that you will not be able to set the action type to 'mvno' without having special permissions enabled on your account.
Parameter: parameters Type: Array Required: Yes Description:

The array of parameters for the selected action. The values will depend on the selected action type. This can be either a list of destination email addresses for the 'email' action or a list of HTTP endpoints for 'http_get' or 'http_post' actions. This is a required parameter unless the selected action type is 'black_hole' or 'mvno'.

When using either 'http_get' or 'http_post' as the relay action, you can pass in variable placeholders into the return URL. They will be replaced by corresponding values at runtime. The following placeholders are available:

%m: Message

%o: Originator

%d: Destination

%t: Timestamp in 'yyyy-mm-dd hh:mm:ss'

%x: Timestamp in Unix time

%u: UDH

%i: Message ID

Response Fields (Success 200)

Field Type Description
Field: id Type: String Description:

The ID of the relay object
Field: prefix Type: String Description:

The prefix being affected
Field: action Type: Object Description:

The relay action associated with the prefix
Field: action.name Type: String Description:

The relay action name. Possible values are: black_hole, http_get, http_post, email, mvno If the action type of a prefix is currently set to 'mvno', this means that the messages cannot be forwarded to any external destination
Field: action.description Type: String Description:

The relay action description
Field: action.parameters Type: Array Description:

The parameters associated with the action. The values will depend on the selected action type This can be either a list of destination email addresses for the 'email' action or a list of HTTP endpoints for 'http_get' or 'http_post' actions
Field: updated_at Type: Datetime Description:

The time of the most recent update

Send a Sample Request

PATCH

Header

Parameter

Code Examples

curl https://api.aql.com/v2/sms-relay/geo/:relay \
-X PATCH \
-H "Content-type: application/json" \
-H "X-Auth-Token: {{YOUR_API_TOKEN}}" \
-d '{
    "action": "http_post",
    "parameters": ["example.com/endpoint"],
}'
$curl = curl_init();
$data = [
    "action" => "http_post",
    "parameters" => ["example.com/endpoint"],
];
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com/v2/sms-relay/geo/:relay");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($curl);
curl_close($curl);
import requests

url = "https://api.aql.com/v2/sms-relay/geo/:relay"

payload = '{
    "action": "http_post",
    "parameters": ["example.com/endpoint"],
}'
headers = {
    'x-auth-token': "{{YOUR_API_TOKEN}}",
    'content-type': "application/json"
}

response = requests.patch(url, data=payload, headers=headers)

print(response.text)
var client = new RestClient("https://api.aql.com/v2/sms-relay/geo/:relay");
var request = new RestRequest(Method.PATCH);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");
request.AddParameter("application/json", '{
    "action": "http_post",
    "parameters": ["example.com/endpoint"],
}', ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $endpoint = '/v2/sms-relay/geo/:relay';
my $data = {
    "action": "http_post",
    "parameters": ["example.com/endpoint"],
};

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->PATCH(
    $endpoint,
    encode_json($data)
);
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 200 OK
{
  "data":
    {
      "id": "2Axr6kl8opBk",
      "action": {
        "name": "black_hole",
        "prefix": "441131234",
         "description": "Do nothing",
         "parameters": []
      },
      "updated_at": {
        "date": "2011-08-23 08:39:19.000000",
        "timezone_type": 2,
        "timezone": "GMT"
      }
    }
  }
}

Network lookup

Lookup query

get
GET v2/network-lookup/:number

Perform HLR lookup on a number to get information about it's home network - Cost 1 SMS credit per lookup

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Parameter

Parameter Type Required Description
Parameter: number Type: String Required: Yes Description:

The MSISDN (mobile number) to perform the lookup on. The number should not contain any special characters and begin with a country code without leading zeros or '+' sign.

Response Fields (Success 200)

Field Type Description
Field: number Type: String Description:

The lookup subject number
Field: status Type: Object Description:

Lookup status. It can contain different status codes depending on response from mobile provider
Field: mcc Type: String Description:

Mobile Country Code
Field: mnc Type: String Description:

Mobile Network Code
Field: network Type: Object Description:

Network info. It contains the name, country and contact details (if available) of the number's home network
Field: imsi Type: String Description:

International Mobile Subscriber Identity. The IMSI is a unique number identifying a GSM subscriber
Field: ported Type: Boolean Description:

Is it a ported number
Field: roaming Type: Boolean Description:

Is the number roaming

Send a Sample Request

GET

Header

Parameter

Code Examples

curl https://api.aql.com/v2/network-lookup/:number \
-H "Content-type: application/json" \
-H "X-Auth-Token: {{YOUR_API_TOKEN}}"
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com/v2/network-lookup/:number");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
$response = curl_exec($curl);
curl_close($curl);
import urllib2
token='{{YOUR_API_TOKEN}}'
url='https://api.aql.com/v2/network-lookup/:number'
req = urllib2.Request(url)
req.add_header("Content-type", "application/json")
req.add_header('X-Auth-Token', token)
res = urllib2.urlopen(req)
var client = new RestClient("https://api.aql.com/v2/network-lookup/:number");
var request = new RestRequest(Method.GET);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");
IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->GET('/v2/network-lookup/:number');
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 200 OK
{
  "data": {
    "number": "447999781578",
    "status": {
        "code": 0,
        "description": "OK"
    },
    "mcc": "234",
    "mnc": "10",
    "network": {
        "name": "O2 (Telefonica UK Ltd)",
        "country": "United Kingdom",
        "contact": null
    },
    "imsi": null,
    "ported": false,
    "roaming": false
  }
}

Outbound SMS

Check available credit

get
GET v2/sms/credit

Check the available credit amount on your account

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Send a Sample Request

GET

Header

Code Examples

curl https://api.aql.com/v2/sms/credit \
-H "Content-type: application/json" \
-H "X-Auth-Token: {{YOUR_API_TOKEN}}"
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com/v2/sms/credit");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
$response = curl_exec($curl);
curl_close($curl);
import urllib2
token='{{YOUR_API_TOKEN}}'
url='https://api.aql.com/v2/sms/credit'
req = urllib2.Request(url)
req.add_header("Content-type", "application/json")
req.add_header('X-Auth-Token', token)
res = urllib2.urlopen(req)
var client = new RestClient("https://api.aql.com/v2/sms/credit");
var request = new RestRequest(Method.GET);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");
IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->GET('/v2/sms/credit');
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 200 OK
{
    "data": {
        "credit": 1000
    }
}

Delete pending SMS

delete
DELETE v2/sms/:message

Allows for deleting pending SMS messages. It is only possible to delete one message at a time.

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Parameter

Parameter Type Required Description
Parameter: message Type: Integer Required: Yes Description:

The message ID

Error Fields (Error 4xx)

Field Type Description
Field: message Type: String Description:

Error message

Send a Sample Request

DELETE

Header

Parameter

Code Examples

curl https://api.aql.com/v2/sms/:message \
-X DELETE \
-H "Content-type: application/json" \
-H "X-Auth-Token: {{YOUR_API_TOKEN}}"
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com/v2/sms/:message");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "DELETE");
$response = curl_exec($curl);
curl_close($curl);
import requests
url='https://api.aql.com/v2/sms/:message'
headers = {'x-auth-token': '{{YOUR_API_TOKEN}}'}
response = requests.get(url, headers=headers)
var client = new RestClient("https://api.aql.com/v2/sms/:message");
var request = new RestRequest(Method.DELETE);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");
IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->DELETE('/v2/sms/:message');
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 204 NO CONTENT

Get pending SMS

get
GET v2/sms/pending

Get a list of pending SMS messages which have not yet been sent. Multipart messages will be displayed separately.

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Response Fields (Success 200)

Field Type Description
Field: id Type: Integer Description:

The ID of the pending message
Field: source Type: String Description:

The name or number of the sender
Field: destination Type: String Description:

The destination number (MSISDN)
Field: received Type: Datetime Description:

The time when the message was registered by our system
Field: scheduled_delivery Type: Datetime Description:

The scheduled delivery time
Field: original_scheduled_delivery Type: Datetime Description:

The original scheduled delivery time It will be the same as scheduled_delivery unless the initial message delivery fails and is rescheduled in the system
Field: data Type: String Description:

The message body

Error Fields (Error 4xx)

Field Type Description
Field: message Type: String Description:

Error message

Send a Sample Request

GET

Header

Code Examples

curl https://api.aql.com/v2/sms/pending \
-H "Content-type: application/json" \
-H "X-Auth-Token: {{YOUR_API_TOKEN}}" \
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com/v2/sms/pending");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
$response = curl_exec($curl);
curl_close($curl);
import requests
url='https://api.aql.com/v2/sms/pending'
headers = {'x-auth-token': '{{YOUR_API_TOKEN}}'}
response = requests.get(url, headers=headers)
print(response.text)
var client = new RestClient("https://api.aql.com/v2/sms/pending");
var request = new RestRequest(Method.GET);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");
IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->GET('/v2/sms/pending');
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 123,
            "source": "Company Name",
            "destination": "441234567890",
            "received": "2017-02-15 15:57:38",
            "scheduled_delivery": "2017-02-15 16:56:18",
            "original_scheduled_delivery": "2017-02-15 16:56:18",
            "data": "Message text"
        },
    ],
    "meta": {
        "pagination": {
        "total": 1,
        "count": 1,
        "per_page": 15,
        "current_page": 1,
        "total_pages": 1,
        "links": []
        }
    }
}

Preview SMS

post
POST v2/sms/preview

"Fake" sending an SMS message to view how it will be handled by the service, how it will be split and how much credit will be used.

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Parameter

Parameter Type Required Description
Parameter: destinations Type: Array Required: Yes Description:

An array containing destination numbers to which the message will be sent. The destination numbers must be digits only without any special characters or spaces, and must begin with a country code (E.164 compliant) without leading zeros
Parameter: message Type: String Required: Yes Description:

Message body
Parameter: originator Type: String Required: No Description:

The message sender name to be shown.
Parameter: send_time Type: String Required: No Description:

Specific date and time on which the message should be sent. If not specified it will be sent instantaneously.
Parameter: dlr_url Type: String Required: No Description:

A [GET] URL on your server where the delivery report should be sent.
Parameter: max_parts Type: Integer Required: No Description:

Maximum number of concatenated parts the message can be split into. If the message is too long to fit within the chosen limit, only part of it will be delivered.
Parameter: replace Type: Boolean Required: No Description:

Replaceable Messages are messages which are allowed to be updated by newer versions of themselves. Both the original and replacement messages must be sent as Replaceable Messages with the same originator.
Parameter: flash Type: Boolean Required: No Description:

Flash SMS is an SMS which is displayed on the phone screen immediately upon arrival. If several flash messages are sent to one phone, only the latter message will be displayed.

Response Fields (Success 200)

Field Type Description
Field: message_parts Type: Integer Description:

The number of parts the message will be split into
Field: credit_cost Type: Integer Description:

Number of credits required for sending the message
Field: available_credit Type: Integer Description:

Amount of credits currently available on the account
Field: message_meta Type: Object Description:

Additional information about the message

Error Fields (Error 4xx)

Field Type Description
Field: message Type: String Description:

Error message
Field: errors Type: String Description:

List of request parameters that failed validation

Send a Sample Request

POST

Header

Parameter

Code Examples

curl https://api.aql.com/v2/sms/preview \
-X POST \
-H "Content-type: application/json" \
-H "X-Auth-Token: {{YOUR_API_TOKEN}}" \
-d '{"destinations" : ["441234567890"], "message": "Hello, I am a message"}'
$curl = curl_init();
$data = ["destinations" => ["441234567890"], "message" => "Hello, I am a message."];
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com/v2/sms/preview");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($curl);
curl_close($curl);
import requests

url = "https://api.aql.com/v2/sms/preview"

payload = "{\"destinations\" : [\"441234567890\"], \"message\": \"Hello, I am a message\"}"
headers = {
    'x-auth-token': "{{YOUR_API_TOKEN}}",
    'content-type': "application/json"
    }

response = requests.post(url, data=payload, headers=headers)

print(response.text)
var client = new RestClient("https://api.aql.com/v2/sms/preview");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");
request.AddParameter("application/json", "{\"destinations\" : [\"441234567890\"],
\"message\": \"Hello, I am a message\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $endpoint = '/v2/sms/preview';
my $data = {destinations => ["441234567890"], message => "Hello, I am a message"};

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->POST(
    $endpoint,
    encode_json($data)
);
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 200 OK
{
    "data": {
        "message_parts": 1,
        "credit_cost": 1,
        "available_credit": 1000,
        "message_meta": {
            "forced_route": null,
            "originator": "Company Name",
            "dlr_type": "off",
            "dlr_data": "",
            "ip": "127.0.0.1",
            "flash": false,
            "replace_sms": false,
            "account_id": 1234,
            "delete_body": false,
            "send_time": null
        }
    }
}

Send SMS

post
POST v2/sms/send

Send a message to one or more specified destination numbers. In the case of multipart messages, the credit cost is calculated by multiplying the number of parts by the number of recipients.

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Parameter

Parameter Type Required Description
Parameter: destinations Type: Array Required: Yes Description:

An array containing destination numbers to which the message will be sent. The destination numbers must be digits only without any special characters or spaces, and must begin with a country code (E.164 compliant) without leading zeros. Please note, we only perform basic validation on the destination numbers and we suggest performing additional validation before submitting the request. Using Network Lookup is recommended to ensure the destination number exists and is reachable.
Parameter: message Type: String Required: Yes Description:

Message body
Parameter: originator Type: String Required: No Description:

The message sender name to be shown.
Parameter: send_time Type: String Required: No Description:

Specific date and time on which the message should be sent. If not specified it will be sent instantaneously.
Parameter: dlr_url Type: String Required: No Description:

A [GET] URL on your server where the delivery report should be sent.

eg: https://www.site.com/dlr.php?reportcode=%code&destinationnumber=%dest&msgid=%msgid&dlr=%dlr&ts=%timestamp

%msgid - message id
%dest - destination number
%code - delivery report code

The values are:

1 = Delivered to Handset
2 = Rejected from Handset
4 = Buffered in transit (phone probably off / out of reception)
8 = Accepted by SMSC
16 = Rejected by SMSC

%dlr - delivery report body

Example DLR body:
id:12345678 sub:001 dlvrd:001 submit date:1904090857 done date:1904090857 stat:DELIVRD err:000 text:This is some text

%timestamp - message delivery time as the number of seconds since January 1st 1970 00:00:00 GMT
Parameter: max_parts Type: Integer Required: No Description:

Maximum number of concatenated parts the message can be split into. If the message is too long to fit within the chosen limit, only part of it will be delivered.
Parameter: replace Type: Boolean Required: No Description:

Replaceable Messages are messages which are allowed to be updated by newer versions of themselves. Both the original and replacement messages must be sent as Replaceable Messages with the same originator.
Parameter: flash Type: Boolean Required: No Description:

Flash SMS is an SMS which is displayed on the phone screen immediately upon arrival. If several flash messages are sent to one phone, only the latter message will be displayed.

Response Fields (Success 200)

Field Type Description
Field: id Type: Integer Description:

The ID of the pending message
Field: source Type: String Description:

The sender name or number
Field: destination Type: String Description:

The destination number (MSISDN)
Field: received Type: Datetime Description:

The time of the message being registered by our system
Field: scheduled_delivery Type: Datetime Description:

The scheduled delivery time
Field: original_scheduled_delivery Type: Datetime Description:

The original scheduled delivery time It will be the same as scheduled_delivery unless the initial message delivery fails and is rescheduled in the system
Field: data Type: String Description:

The message body

Error Fields (Error 4xx)

Field Type Description
Field: message Type: String Description:

Error message
Field: errors Type: String Description:

List of request parameters that failed validation

Send a Sample Request

POST

Header

Parameter

Code Examples

curl https://api.aql.com/v2/sms/send \
-X POST \
-H "Content-type: application/json" \
-H "X-Auth-Token: {{YOUR_API_TOKEN}}" \
-d '{"destinations" : ["441234567890"], "message": "Hello, I am a message"}'
$curl = curl_init();
$data = ["destinations" => ["441234567890"], "message" => "Hello, I am a message."];
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com/v2/sms/send");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($curl);
curl_close($curl);
import requests

url = "https://api.aql.com/v2/sms/send"

payload = "{\"destinations\" : ["441234567890"], \"message\": \"Hello, I am a message\"}"
headers = {
    'x-auth-token': "{{YOUR_API_TOKEN}}",
    'content-type': "application/json"
    }

response = requests.post(url, data=payload, headers=headers)

print(response.text)
var client = new RestClient("https://api.aql.com/v2/sms/send");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");
request.AddParameter("application/json", "{\"destinations\" : [\"441234567890\"], \"message\":
\"Hello, I am a message\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $endpoint = '/v2/sms/send';
my $data = {destinations => ["441234567890"], message => "Hello, I am a message"};

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->POST(
    $endpoint,
    encode_json($data)
);
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 123,
            "source": "Company Name",
            "destination": "441234567890",
            "received": "2017-02-15 15:57:38",
            "scheduled_delivery": "2017-02-15 16:56:18",
            "original_scheduled_delivery": "2017-02-15 16:56:18",
            "data": "Message text"
        },
    ],
    "meta": {
        "pagination": {
        "total": 1,
        "count": 1,
        "per_page": 15,
        "current_page": 1,
        "total_pages": 1,
        "links": []
        }
    }
}

Error Response Example

Error-Response:

HTTP/1.1 402 Payment Required
{
    "message": "Insufficient credit."
}

Error-Response:

HTTP/1.1 422 Unprocessable Entity
{
    "message": "Request validation failed.",
    "errors": "The destinations.0 format is invalid."
}

Send vCard

post
POST v2/sms/send-vcard

Send contact details as a vCard via SMS.

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Parameter

Parameter Type Required Description
Parameter: destinations Type: Array Required: Yes Description:

An array containing destination numbers to which the vCard will be sent. The destination numbers must be digits only without any special characters or spaces, and must begin with a country code (E.164 compliant) without leading zeros
Parameter: first_name Type: String Required: Yes Description:

The contact's first name
Parameter: last_name Type: String Required: Yes Description:

The contact's last name
Parameter: phone Type: Array Required: No Description:

An array containing contact's phone numbers
Parameter: phone.mobile Type: String Required: No Description:

Mobile phone number
Parameter: phone.home Type: String Required: No Description:

Home phone number
Parameter: phone.work Type: String Required: No Description:

Work phone number
Parameter: phone.fax Type: String Required: No Description:

Fax number
Parameter: email Type: String Required: No Description:

The contact's email
Parameter: birth_date Type: String Required: No Description:

The contact's birth date
Parameter: note Type: String Required: No Description:

Additional note
Parameter: originator Type: String Required: No Description:

The vCard sender name to be shown.
Parameter: send_time Type: String Required: No Description:

Specific date and time on which the vCard should be sent. If not specified it will be sent instantaneously.
Parameter: dlr_url Type: String Required: No Description:

A [GET] URL on your server where the delivery report should be sent.

eg: https://www.site.com/dlr.php?reportcode=%code&destinationnumber=%dest&msgid=%msgid

%msgid - message id
%dest - destination number
%code - delivery report code

The values are:

1 = Delivered to Handset
2 = Rejected from Handset
4 = Buffered in transit (phone probably off / out of reception)
8 = Accepted by SMSC
16 = Rejected by SMSC
Parameter: version Type: String Required: No Description:

The Vcard protocol version to use (2.1 | 3.0 | 4.0). If not specified, 3.0 is used.

Response Fields (Success 200)

Field Type Description
Field: id Type: Integer Description:

The ID of the pending message
Field: source Type: String Description:

The sender name or number
Field: destination Type: String Description:

The destination number (MSISDN)
Field: received Type: Datetime Description:

The time of the message being registered by our system
Field: scheduled_delivery Type: Datetime Description:

The scheduled delivery time
Field: original_scheduled_delivery Type: Datetime Description:

The original scheduled delivery time It will be the same as scheduled_delivery unless the initial message delivery fails and is rescheduled in the system
Field: data Type: String Description:

The message body

Send a Sample Request

POST

Header

Parameter

Code Examples

curl https://api.aql.com/v2/sms/send-vcard \
-X POST \
-H "Content-type: application/json" \
-H "X-Auth-Token: {{YOUR_API_TOKEN}}" \
-d '{"destinations" : ["441234567890"], "first_name" : "John", "last_name" : "Doe",
"phone" : ["mobile" : "447654321876"]}'
$curl = curl_init();
$data = ["destinations" => ["441234567890"], "first_name" => "John", "last_name" => "Doe",
"phone" => ["mobile" => "447654321876"]];
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com/v2/sms/send-vcard");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($curl);
curl_close($curl);
import requests

url = "https://api.aql.com/v2/sms/send-vcard"

payload = "{\"destinations\" : [\"441234567890\"], \"first_name\" : \"John\", \"last_name\" : \"Doe\",
\"phone\" : [\"mobile\" : \"447654321876\"]}"
headers = {
    'x-auth-token': "{{YOUR_API_TOKEN}}",
    'content-type': "application/json"
    }

response = requests.post(url, data=payload, headers=headers)

print(response.text)
var client = new RestClient("https://api.aql.com/v2/sms/send-vcard");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");
request.AddParameter("application/json", "{\"destinations\" : [\"441234567890\"],
\"first_name\" : \"John\", \"last_name\" : \"Doe\",
\"phone\" : [\"mobile\" : \"447654321876\"]}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $endpoint = '/v2/sms/send-vcard';
my $data = {destinations => ["441234567890"], "first_name" => "John", "last_name" => "Doe",
"phone" => ["mobile" => "447654321876"]};

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->POST(
    $endpoint,
    encode_json($data)
);
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 123,
            "source": "Company Name",
            "destination": "441234567890",
            "received": "2017-02-15 15:57:38",
            "scheduled_delivery": "2017-02-15 16:56:18",
            "original_scheduled_delivery": "2017-02-15 16:56:18",
            "data": "Message text"
        },
    ],
    "meta": {
        "pagination": {
        "total": 1,
        "count": 1,
        "per_page": 15,
        "current_page": 1,
        "total_pages": 1,
        "links": []
        }
    }
}

SIP

Download CDR archive

get
GET v2/sip/cdr/:handle/download

Download zip file containing prepared CDR data in CSV format.

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Parameter

Parameter Type Required Description
Parameter: handle Type: String Required: Yes Description:

The request identifier received from 'v2/cdr/request' call.

Send a Sample Request

GET

Header

Parameter

Code Examples

curl https://api.aql.com/v2/sip/cdr/:handle/download \
-H "Content-type: application/json" \
-H "X-Auth-Token: {{YOUR_API_TOKEN}}" \
-o cdr.zip
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com/v2/sip/cdr/:handle/download");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
$response = curl_exec($curl);
curl_close($curl);
import urllib2
token='{{YOUR_API_TOKEN}}'
url='https://api.aql.com/v2/sip/cdr/:handle/download'
req = urllib2.Request(url)
req.add_header("Content-type", "application/json")
req.add_header('X-Auth-Token', token)
res = urllib2.urlopen(req)
var client = new RestClient("https://api.aql.com/v2/sip/cdr/:handle/download");
var request = new RestRequest(Method.GET);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");
IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->GET('/v2/sip/cdr/:handle/download');
my $response = from_json($client->responseContent());
print Dumper($response);

Request CDR download

post
POST v2/sip/cdr/request

Request Call Detail Records for specific time period as downloadable archive containing CSV files. This will create a request for the data to be prepared for download. Requests will expire after 2 hours from being submitted. If the data is not downloaded by that time, a new request will need to be submitted. Please note, all dates (submitted and returned) are in UTC.

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Parameter

Parameter Type Required Description
Parameter: from_date Type: String Required: Yes Description:

Start date for CDR lookup (required)
Parameter: to_date Type: String Required: Yes Description:

End date for CDR lookup (required)
Parameter: email Type: String Required: No Description:

Email address to which a confirmation will be sent when the requested data is ready.
Parameter: format Type: String Required: No Description:

Please note: the UKv3a format is now the current default CDR layout as of 30/09/2021 23:59. The UKv3 format is no longer supported.
Parameter: single_file Type: Boolean Required: No Description:

When set to true, all of the data will be put into single CSV file instead of being split by days.

Send a Sample Request

POST

Header

Parameter

Code Examples

curl https://api.aql.com/v2/sip/cdr/request \
-X POST \
-H "Content-type: application/json" \
-H "X-Auth-Token: {{YOUR_API_TOKEN}}" \
-d '{"from_date" : "2017-01-01 00:00:00", "to_date": "2017-01-31 23:59:59"}'
$curl = curl_init();
$data = ["from_date" => "2017-01-01 00:00:00", "to_date" => "2017-01-31 23:59:59"];
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com/v2/sip/cdr/request");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($curl);
curl_close($curl);
import requests

url = "https://api.aql.com/v2/cdr/request"

payload = "{\"from_date\" : \"2017-01-01 00:00:00\", \"to_date\": \"2017-01-31 23:59:59\"}"
headers = {
    'x-auth-token': "{{YOUR_API_TOKEN}}",
    'content-type': "application/json"
    }

response = requests.post(url, data=payload, headers=headers)

print(response.text)
var client = new RestClient("https://api.aql.com/v2/sip/cdr/request");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");
request.AddParameter("application/json", "{\"from_date\" : \"2017-01-01 00:00:00\", \"to_date\": \"2017-01-31
    23:59:59\"}", ParameterType.RequestBody); IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $client = REST::Client->new();
my $data = "{\"from_date\" : \"2017-01-01 00:00:00\", \"to_date\": \"2017-01-31 23:59:59\"}";
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->POST('/v2/sip/cdr/request', $data);
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 200 OK
{
    "data": {
        "handle": 21458b41485d1405
        "from_date": "2017-01-01 00:00:00",
        "to_date": "2017-01-31 23:59:59",
        "status": {
            "name": "pending",
            "description": "Request submitted"
        },
        "created_at": "2017-02-01 13:30:00",
        "updated_at": "2017-02-01 14:25:00",
        "parts_count": "31",
        "single_file": false
    }
    "meta": {
       "check_status": "[[DOMAIN]]v2/sip/cdr/21458b41485d1405"
    }
}

Cancel CDR request

delete
DELETE v2/sip/cdr/:handle

Cancel a download request.

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Parameter

Parameter Type Required Description
Parameter: handle Type: String Required: Yes Description:

The request identifier received from 'v2/cdr/request' call.

Send a Sample Request

DELETE

Header

Parameter

Code Examples

curl https://api.aql.com//v2/sip/cdr/:handle \
-X DELETE \
-H "Content-type: application/json" \
-H "X-Auth-Token: {{YOUR_API_TOKEN}}" \
$curl = curl_init();
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com//v2/sip/cdr/:handle");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
$response = curl_exec($curl);
curl_close($curl);
import urllib2
token='{{YOUR_API_TOKEN}}'
url='https://api.aql.com//v2/sip/cdr/:handle'
req = urllib2.Request(url)
req.add_header("Content-type", "application/json")
req.add_header('X-Auth-Token', token)
res = urllib2.urlopen(req)
var client = new RestClient("https://api.aql.com//v2/sip/cdr/:handle");
var request = new RestRequest(Method.DELETE);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");
IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->DELETE('/v2/sip/cdr/:handle');
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 200 OK
{
    "data": {
        "handle": "21458b41485d1405",
        "from_date": "2017-01-01 00:00:00",
        "to_date": "2017-01-31 23:59:59",
        "status": {
            "name": "cancelled",
            "description": "Request cancelled"
        },
        "created_at": "2017-02-05 13:30:00",
        "updated_at": "2017-02-05 13:50:00",
        "parts_count": "31"
    }
}

Check CDR request

get
GET v2/sip/cdr/:handle

Check the status of previously submitted request. If it has been processed, the response meta element will contain a download link. This will create a request for the data to be prepared for download.

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Parameter

Parameter Type Required Description
Parameter: handle Type: String Required: Yes Description:

The request identifier received from 'v2/cdr/request' call.

Send a Sample Request

GET

Header

Parameter

Code Examples

curl https://api.aql.com/v2/sip/cdr/:handle \
-H "Content-type: application/json" \
-H "X-Auth-Token: {{YOUR_API_TOKEN}}" \
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com/v2/sip/cdr/:handle");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
$response = curl_exec($curl);
curl_close($curl);
import urllib2
token='{{YOUR_API_TOKEN}}'
url='https://api.aql.com/v2/sip/cdr/:handle'
req = urllib2.Request(url)
req.add_header("Content-type", "application/json")
req.add_header('X-Auth-Token', token)
res = urllib2.urlopen(req)
var client = new RestClient("https://api.aql.com/v2/sip/cdr/:handle");
var request = new RestRequest(Method.GET);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");
IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->GET('/v2/sip/cdr/:handle');
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 200 OK
{
    "data": {
        "handle": "21458b41485d1405",
        "from_date": "2017-01-01 00:00:00",
        "to_date": "2017-01-31 23:59:59",
        "status": {
            "name": "processed",
            "description": "Request processed"
        },
        "created_at": "2017-02-05 13:30:00",
        "updated_at": "2017-02-05 13:30:00",
        "parts_count": "31",
        "single_file": false
    }
    "meta": {
       "download_link": "[[DOMAIN]]v2/sip/cdr/21458b41485d1405/download"
    }

}

Refresh CDR request to extend the expiry time.

put
PUT v2/sip/cdr/:handle

Refresh a request. The request expiry timer will be reset.

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Parameter

Parameter Type Required Description
Parameter: handle Type: String Required: Yes Description:

The request identifier received from 'v2/cdr/request' call.

Send a Sample Request

PUT

Header

Parameter

Code Examples

curl https://api.aql.com//v2/sip/cdr/:handle \
-X PUT \
-H "Content-type: application/json" \
-H "X-Auth-Token: {{YOUR_API_TOKEN}}" \
$curl = curl_init();
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com//v2/sip/cdr/:handle");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
$response = curl_exec($curl);
curl_close($curl);
import urllib2
token='{{YOUR_API_TOKEN}}'
url='https://api.aql.com//v2/sip/cdr/:handle'
req = urllib2.Request(url)
req.add_header("Content-type", "application/json")
req.add_header('X-Auth-Token', token)
res = urllib2.urlopen(req)
var client = new RestClient("https://api.aql.com//v2/sip/cdr/:handle");
var request = new RestRequest(Method.PUT);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");
IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->PUT('/v2/sip/cdr/:handle');
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 200 OK
{
    "data": {
        "handle": "21458b41485d1405",
        "from_date": "2017-01-01 00:00:00",
        "to_date": "2017-01-31 23:59:59",
        "status": {
            "name": "processed",
            "description": "Request processed"
        },
        "created_at": "2017-02-01 13:30:00",
        "updated_at": "2017-02-01 14:25:00",
        "parts_count": "31",
        "single_file": false,
    }
    "meta": {
       "download_link": "[[DOMAIN]]/v2/sip/cdr/21458b41485d1405/download"
    }

}

Get SIP trunk info

get
GET v2/sip/info

Get SIP trunk related information for current account

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Response Fields (Success 200)

Field Type Description
Field: balance Type: Integer Description:

Current account balance
Field: channels Type: Integer Description:

Maximum number of channels
Field: tariff_name Type: String Description:

The name of tariff currently being used

Send a Sample Request

GET

Header

Code Examples

curl https://api.aql.com/v2/sip/info \
-H "Content-type: application/json" \
-H "X-Auth-Token: {{YOUR_API_TOKEN}}"
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com/v2/sip/info");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
$response = curl_exec($curl);
curl_close($curl);
import urllib2
token='{{YOUR_API_TOKEN}}'
url='https://api.aql.com/v2/sip/info'
req = urllib2.Request(url)
req.add_header("Content-type", "application/json")
req.add_header('X-Auth-Token', token)
res = urllib2.urlopen(req)
var client = new RestClient("https://api.aql.com/v2/sip/info");
var request = new RestRequest(Method.GET);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");
IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->GET('/v2/sip/info');
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 200 OK
{
  "data": [
    {
      "balance": 100,
      "channels": 10,
      "tariff_name": "Standard Wholesale"
    }
  ]
}

Get SIP trunk source IPs

get
GET v2/sip/trunk/source-ips

Get SIP trunk source IPs for current account

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Parameter

Parameter Type Required Description
Parameter: limit Type: Integer Required: No Description:

Maximum records to return (optional - default all)
Parameter: offset Type: Integer Required: No Description:

Skip this number of records from start (optional - default 0)

Response Fields (Success 200)

Field Type Description
Field: source_ips Type: Array Description:

All source IPs for current account

Send a Sample Request

GET

Header

Parameter

Code Examples

curl https://api.aql.com/v2/sip/trunk/source-ips \
-H "Content-type: application/json" \
-H "X-Auth-Token: {{YOUR_API_TOKEN}}"
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com/v2/sip/trunk/source-ips");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
$response = curl_exec($curl);
curl_close($curl);
import urllib2
token='{{YOUR_API_TOKEN}}'
url='https://api.aql.com/v2/sip/trunk/source-ips'
req = urllib2.Request(url)
req.add_header("Content-type", "application/json")
req.add_header('X-Auth-Token', token)
res = urllib2.urlopen(req)
var client = new RestClient("https://api.aql.com/v2/sip/trunk/source-ips");
var request = new RestRequest(Method.GET);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");
IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->GET('/v2/sip/trunk/source-ips');
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 200 OK
{
  "data": [
    {
      "source_ips": [
         "0.0.0.0",
         "1.1.1.1"
      ]
    }
  ]
}

VMN Inbound SMS

List SMS relay actions

get
GET v2/sms-relay/vmn/actions

Returns a list of all actions available for use on your account

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Response Fields (Success 200)

Field Type Description
Field: name Type: String Description:

The name of the action
Field: description Type: String Description:

Action description

curl [[DOMAIN]]v2/sms-relay/vmn/actions
-X GET
-H "Content-type: application/json"
-H "X-Auth-Token: {{YOUR_API_TOKEN}}"

Send a Sample Request

GET

Header

Code Examples

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com/v2/sms-relay/vmn/actions");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
$response = curl_exec($curl);
curl_close($curl);
import requests

url = "https://api.aql.com/v2/sms-relay/vmn/actions"

headers = {
    'x-auth-token': "{{YOUR_API_TOKEN}}",
    'content-type': "application/json"
    }

response = requests.get(url, headers=headers)

print(response.text)
var client = new RestClient("https://api.aql.com/v2/sms-relay/vmn/actions");
var request = new RestRequest(Method.GET);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");

IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $endpoint = '/v2/sms-relay/vmn/actions';

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->GET($endpoint);
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 200 OK
{
  "data": [
    {
      "name": "inactive",
      "description": "No Action"
    },
    {
      "name": "http_post",
      "description": "HTTP POST"
    },
    {
      "name": "http_get",
      "description": "HTTP GET"
    },
    {
      "name": "email",
      "description": "Email"
    },
    {
      "name": "dialogue_post",
      "description": "Dialogue's HTTP POST"
    },
    {
      "name": "dialogue_get",
      "description": "Dialogue's HTTP GET"
    },
    {
      "name": "ms_outlook",
      "description": "Microsoft Outlook"
    },
    {
      "name": "desktopsms",
      "description": "DesktopSMS"
    },
    {
      "name": "inbound_gw",
      "description": "Inbound Gateway"
    }
  ]
  "meta": {
    "pagination": {
      "total": 10,
      "count": 10,
      "per_page": 15,
      "current_page": 1,
      "total_pages": 1,
      "links": []
    }
  }
}

List VMN SMS relays

get
GET v2/sms-relay/vmn

Returns a list of all available Virtual Mobile Numbers SMS relays on the account

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Parameter

Parameter Type Required Description
Parameter: number Type: String Required: No Description:

An optional filter to only show numbers matching the specified query. Can accept * as a wildcard.

Response Fields (Success 200)

Field Type Description
Field: id Type: String Description:

The ID of the relay object
Field: number Type: String Description:

The number being affected
Field: action Type: Object Description:

The relay action associated with the number
Field: action.name Type: String Description:

The relay action name. Possible values are: inactive, http_get, http_post, email, dialogue_post, dialogue_get, ms_outlook, desktopsms, inbound_gw
Field: action.description Type: String Description:

The relay action description
Field: action.parameters Type: Array Description:

The parameters associated with the action. The values will depend on the selected action type For example, a list of destination email addresses in case of 'email' action or a list of http endpoints for 'http_get' or 'http_post' actions
Field: updated_at Type: Datetime Description:

The time of the most recent update

Send a Sample Request

GET

Header

Parameter

Code Examples

curl https://api.aql.com/v2/sms-relay/vmn \
-X GET \
-H "Content-type: application/json" \
-H "X-Auth-Token: {{YOUR_API_TOKEN}}"
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com/v2/sms-relay/vmn");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
$response = curl_exec($curl);
curl_close($curl);
import requests

url = "https://api.aql.com/v2/sms-relay/vmn"

headers = {
    'x-auth-token': "{{YOUR_API_TOKEN}}",
    'content-type': "application/json"
    }

response = requests.get(url, headers=headers)

print(response.text)
var client = new RestClient("https://api.aql.com/v2/sms-relay/vmn");
var request = new RestRequest(Method.GET);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");

IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $endpoint = '/v2/sms-relay/vmn';

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->GET($endpoint);
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": "2Axr6kl8opBk",
      "action": {
        "name": "inactive",
        "number": "441131234",
         "description": "No Action",
         "parameters": []
      },
      "updated_at": {
        "date": "2011-08-23 08:39:19.000000",
        "timezone_type": 2,
        "timezone": "GMT"
      }
    },
    {
      "id": "7dpzWM18jBgr",
      "action": {
        "name": "email",
        "number": "441137654",
         "description": "Email",
         "parameters": [
           "[email protected]"
         ]
      },
      "updated_at": {
        "date": "2011-08-23 08:39:19.000000",
        "timezone_type": 2,
        "timezone": "GMT"
      }
    }
  ]
  "meta": {
    "pagination": {
      "total": 2,
      "count": 2,
      "per_page": 15,
      "current_page": 1,
      "total_pages": 1,
      "links": []
    }
  }
}

Show VMN SMS relay

get
GET v2/sms-relay/vmn/:relay

Returns a single Virtual Mobile Number SMS relay object

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Parameter

Parameter Type Required Description
Parameter: relay Type: String Required: Yes Description:

The alphanumeric ID of SMS relay object to show

Response Fields (Success 200)

Field Type Description
Field: id Type: String Description:

The ID of the relay object
Field: number Type: String Description:

The number being affected
Field: action Type: Object Description:

The relay action associated with the number
Field: action.name Type: String Description:

The relay action name. Possible values are: inactive, http_get, http_post, email, dialogue_post, dialogue_get, ms_outlook, desktopsms, inbound_gw
Field: action.description Type: String Description:

The relay action description
Field: action.parameters Type: Array Description:

The parameters associated with the action. The values will depend on the selected action type For example, a list of destination email addresses in case of 'email' action or a list of http endpoints for 'http_get' or 'http_post' actions
Field: updated_at Type: Datetime Description:

The time of the most recent update

Send a Sample Request

GET

Header

Parameter

Code Examples

curl https://api.aql.com/v2/sms-relay/vmn/:relay \
-X GET \
-H "Content-type: application/json" \
-H "X-Auth-Token: {{YOUR_API_TOKEN}}"
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com/v2/sms-relay/vmn/:relay");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
$response = curl_exec($curl);
curl_close($curl);
import requests

url = "https://api.aql.com/v2/sms-relay/vmn/:relay"

headers = {
    'x-auth-token': "{{YOUR_API_TOKEN}}",
    'content-type': "application/json"
    }

response = requests.get(url, headers=headers)

print(response.text)
var client = new RestClient("https://api.aql.com/v2/sms-relay/vmn/:relay");
var request = new RestRequest(Method.GET);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");

IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $endpoint = '/v2/sms-relay/vmn/:relay';

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->GET($endpoint);
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 200 OK
{
  "data":
    {
      "id": "2Axr6kl8opBk",
      "action": {
        "name": "inactive",
        "number": "441131234",
         "description": "No Action",
         "parameters": []
      },
      "updated_at": {
        "date": "2011-08-23 08:39:19.000000",
        "timezone_type": 2,
        "timezone": "GMT"
      }
    }
  }
}

Update VMN SMS relay

patch
PATCH v2/sms-relay/vmn/:relay

Update a Virtual Mobile Number SMS relay object

Header

Header Type Required Description
Header: X-Auth-Token Type: String Required: Yes Description:

Your API token.
Header: Content-Type Type: String Required: Yes Description:

Request content type.

Parameter

Parameter Type Required Description
Parameter: relay Type: String Required: Yes Description:

The alphanumeric ID of SMS relay object to update
Parameter: action Type: String Required: Yes Description:

The name of the action to be assigned. Accepted values are: inactive, http_get, http_post, email, dialogue_post, dialogue_get, ms_outlook, desktopsms, inbound_gw
Parameter: parameters Type: Array Required: Yes Description:

The array of parameters for the selected action. The values will depend on the selected action type. This can be either a list of destination email addresses for the 'email' action or a list of HTTP endpoints for 'http_get' or 'http_post' actions. This is a required parameter unless the selected action type is 'inactive'.

When using either 'http_get' or 'http_post' as the relay action, you can pass in variable placeholders into the return URL. They will be replaced by corresponding values at runtime.

The following placeholders are available:

%id: A unique identifier for the message

%stat: Message Status: 0 (Normal Message), 1 (Concatenated message), 2 - (Indecipherable UDH - possibly corrupt message)

%orig: The sender's number

%dest: The destination number

%msg: The message body

%time: Time the message was received (UK time). Format: YYYY-MM-DD HH:MM:SS

%timeZone: An integer, indicating time zone (eg: if timeZone is 1 then it means smsTime is GMT + 1)

%smsTime: Time when the sms was sent. Format: YYYY-MM-DD HH:MM:SS

%netw: Name of the originating network. Will be replaced with an SMSC reference number if the network is not recognised.

%code: Message coding - 7 (GSM), 8 (binary) or 16 (Unicode)

%udh: The User Data Header of the message

Response Fields (Success 200)

Field Type Description
Field: id Type: String Description:

The ID of the relay object
Field: number Type: String Description:

The number being affected
Field: action Type: Object Description:

The relay action associated with the number
Field: action.name Type: String Description:

The relay action name. Possible values are: inactive, http_get, http_post, email, dialogue_post, dialogue_get, ms_outlook, desktopsms, inbound_gw
Field: action.description Type: String Description:

The relay action description
Field: action.parameters Type: Array Description:

The parameters associated with the action. The values will depend on the selected action type This can be either a list of destination email addresses for the 'email' action or a list of HTTP endpoints for 'http_get' or 'http_post' actions
Field: updated_at Type: Datetime Description:

The time of the most recent update

Send a Sample Request

PATCH

Header

Parameter

Code Examples

curl https://api.aql.com/v2/sms-relay/vmn/:relay \
-X PATCH \
-H "Content-type: application/json" \
-H "X-Auth-Token: {{YOUR_API_TOKEN}}" \
-d '{
    "action": "http_post",
    "parameters": ["http://www.example.com/callback.php?id=%id&originator=%orig&destination=%dest&message=%msg"],
}'
$curl = curl_init();
$data = [
    "action" => "http_post",
    "parameters" => ["http://www.example.com/callback.php?id=%id&originator=%orig&destination=%dest&message=%msg"],
];
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($curl, CURLOPT_URL, "https://api.aql.com/v2/sms-relay/vmn/:relay");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-Auth-Token: {{YOUR_API_TOKEN}}", "Content-type: application/json"]);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($curl);
curl_close($curl);
import requests

url = "https://api.aql.com/v2/sms-relay/vmn/:relay"

payload = '{
    "action": "http_post",
    "parameters": ["http://www.example.com/callback.php?id=%id&originator=%orig&destination=%dest&message=%msg"],
}'
headers = {
    'x-auth-token': "{{YOUR_API_TOKEN}}",
    'content-type': "application/json"
}

response = requests.patch(url, data=payload, headers=headers)

print(response.text)
var client = new RestClient("https://api.aql.com/v2/sms-relay/vmn/:relay");
var request = new RestRequest(Method.PATCH);
request.AddHeader("content-type", "application/json");
request.AddHeader("x-auth-token", "{{YOUR_API_TOKEN}}");
request.AddParameter("application/json", '{
    "action": "http_post",
    "parameters": ["http://www.example.com/callback.php?id=%id&originator=%orig&destination=%dest&message=%msg"],
}', ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
use REST::Client;
use JSON;
use Data::Dumper;

my $endpoint = '/v2/sms-relay/vmn/:relay';
my $data = {
    "action": "http_post",
    "parameters": ["http://www.example.com/callback.php?id=%id&originator=%orig&destination=%dest&message=%msg"],
};

my $client = REST::Client->new();
$client->addHeader('Content-Type' => 'application/json');
$client->addHeader('X-Auth-Token' => '{{YOUR_API_TOKEN}}');
$client->setHost('https://api.aql.com/');
$client->PATCH(
    $endpoint,
    encode_json($data)
);
my $response = from_json($client->responseContent());
print Dumper($response);

Success Response Example

HTTP/1.1 200 OK
{
  "data":
    {
      "id": "2Axr6kl8opBk",
      "action": {
        "name": "inactive",
        "number": "441131234",
         "description": "No Action",
         "parameters": []
      },
      "updated_at": {
        "date": "2011-08-23 08:39:19.000000",
        "timezone_type": 2,
        "timezone": "GMT"
      }
    }
  }
}
AutoJemma®

How can I help you today?

Can't find what you're looking for, ask a question below!

Additional Details

AutoJemma® can make mistakes, please verify any critical information.