Skip to content

REST

This is our new API which is available for GatewayAPI.com and based predominately on HTTP POST calls and JSON.

To use this API you must be a customer on the GatewayAPI.com platform, and run on “modern” SSL/TLS software (support SHA-2, ie. OpenSSL 0.9.8+, NSS 3.11+, Win2k8/Vista+, Java 7+).

Sending SMSes

Also known as MT SMS, short for Mobile Terminated SMS, is when you want to deliver a SMS to a users mobile device.

Warning

Note that messages are subject to message filtering, based on the content, sender, destination specific limitations.

Basic Use

Also see Advanced usage for a complete example of all features.

POST /rest/mtsms

The root element can be either a dict with a single SMS or a list of SMSes. You can send data in JSON format, or even as http form data or query args.

Request JSON Object:

  • class (string) - Default “standard”. The message class to use for this request. If specified it must be the same for all messages in the request.
  • message (string) - The content of the SMS. Always specified in UTF-8 encoding, which we transcode depending on the “encoding” field. The default is the usual GSM 03.38 encoding. Required.
  • sender (string) Up to 11 alphanumeric characters, or 15 digits, that will be shown as the sender of the SMS. See SMS Sender.
  • user_ref (string) - A opaque string reference, you may set to keep track of the message in your own systems. Returned to you when you receive Delivery Statuses.
  • callback_url (string) - If specified send status notifications to this URL, else use the default webhook if set.
  • recipients (array) - Array of recipients, described below. The number of recipients in a single message is limited to 10 000. Required

Request JSON Array of Objects:

Response JSON Object:

  • ids (array) - If successful you receive a object containing a list of ids.
  • usage (object) - If successful you receive a object containing usage infomation for your request.

Status Codes:

Content-Types

The two examples below do the exact same thing, but with different styles of input.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
POST /rest/mtsms HTTP/1.1
Host: gatewayapi.com
Authorization: Basic R28tQ3JlYXRlLWFuLUFQSS10b2tlbjoK
Accept: application/json, text/javascript
Content-Type: application/json

{
    "message": "Hello World",
    "recipients": [
        {"msisdn": 4512345678},
        {"msisdn": 4587654321}
    ]
}
1
2
3
4
5
POST /rest/mtsms?token=Go-Create-an-API-token HTTP/1.1
Host: gatewayapi.com
Content-Type: application/x-www-form-urlencoded

message=Hello World&recipients.0.msisdn=4512345678&recipients.1.msisdn=4587654321

You can even send it all using just a query string on a GET request.

GET /rest/mtsms

1
2
GET /rest/mtsms?token=Go-Create-an-API-token&message=Hello+World&recipients.0.msisdn=4512345678&recipients.1.msisdn=4587654321 HTTP/1.1
Host: gatewayapi.com

Connection Limit

Our API has a limit of 40 open connections per IP address, if you have more than 40 open connections our web server will reject your requests. If you need to send lots of SMSes consider bulking your requests with multiple recipients, you can use tags and tagvalues to add unique data per recipient, bulking your requests will also increase your delivery speed compared to making a single request per recipient.

Code Examples

Since sending SMSes is a central part of most customers use cases we host and maintain a few code examples in the dashboard.

Advanced Usage

POST /rest/mtsms

The root element can be either a dict with a single SMS or a list of SMSes.

Request JSON Object:

  • class (string) - Default “standard”. The message class, “standard”, “premium” or “secret” to use for this request. If specified it must be the same for all messages in the request. The secret class can be used to blur the message content you send, used for very sensitive data. It is priced as premium and uses the same routes, which ensures end to end encryption of your messages. Access to the secret class is very strictly controlled.
  • message (string) - The content of the SMS, always specified in UTF-8 encoding, which we will transcode depending on the “encoding” field. The default is the usual GSM 03.38 encoding. Required unless payload is specified.
  • sender (string) - Up to 11 alphanumeric characters, or 15 digits, that will be shown as the sender of the SMS. See SMS Sender.
  • sendtime (integer) - Unix timestamp (seconds since epoch) to schedule message sending at certain time.
  • tags (array) - A list of string tags, which will be replaced with the tag values for each recipient.
  • userref (string) - A opaque string reference, you may set to keep track of the message in your own systems. Returned to you when you receive a Delivery Status Notification.
  • priority (string) - Default NORMAL. One of BULK, NORMAL, URGENT and VERY_URGENT. Urgent and Very Urgent normally require the use of premium message class.
  • validity_period (integer) - Specified in seconds. If message is not delivered within this timespan, it will expire and you will get a notification. The minimum value is 60. Every value under 60 will be set to 60.
  • encoding (string) - Encoding to use when sending the message. Defaults to UTF8, which means we will use GSM 03.38. Use UCS2 to send a unicode message.
  • destaddr (string) - One of DISPLAY, MOBILE, SIMCARD, EXTUNIT. Use DISPLAY to do “flash SMS”, a message displayed on screen immediately but not saved in the normal message inbox on the mobile device. Default value is MOBILE for normal SMS.
  • payload (string) - If you are sending a binary SMS, ie. a SMS you have encoded yourself or with speciel content for feature phones (non-smartphones). You may specify a payload, encoded as Base64. If specified, message must not be set and tags are unavailable.
  • udh (string) - UDH to enable additional functionality for binary SMS, encoded as Base64.
  • callback_url (string) - If specified send status notifications to this URL, else use the default webhook.
  • label (string) - A label added to each sent message, can be used to uniquely identify a customer or company that you sent the message on behalf of, to help with invoicing your customers. If specied it must be the same for all messages in the request. See statistics for how to make use of this feature.
  • max_parts (int) - A number between 1 and 255 used to limit the number of SMSes a single message will send. Can be used if you send SMSes from systems that generates messages that you cannot control, this way you can ensure that you do not send very long SMSes. You will not be charged for more than the amount specified here. Cannot be used with Tags or BINARY SMSes.
  • extra_details (string) - To get more details about the number of parts sent to each recipient set this to “recipients_usage”. See example response below.
  • recipients (array) - Array of recipients, described below. The number of recipients in a single message is limited to 10.000. required

Request JSON Array of Objects:

  • msisdn (string) - MSISDN aka the full mobile phone number of the recipient. Duplicates are not allowed in the same message. required
  • charge (object) - Charge data. See Overcharged SMSes.
  • tagvalues (array) - A list of string values corresponding to the tags in message. The order and amount of tag values must exactly match the tags.

Response JSON Object:

  • ids (array) - If successful you receive a object containing a list of message ids.

Status Codes:

Fully fledged request

This is a bit of contrived example since, but it shows most of the possible fields in the API like multiple recipients to the same message using tags and various extra options.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
POST /rest/mtsms HTTP/1.1
Host: gatewayapi.com
Authorization: Basic R28tQ3JlYXRlLWFuLUFQSS10b2tlbjoK
Accept: application/json, text/javascript
Content-Type: application/json

{
    "class": "premium",
    "message": "Hello World, regards %Firstname%, %Lastname%",
    "label": "Deathstar",
    "recipients": [
        {
            "msisdn": 1514654321,
            "tagvalues": [
                "Vader",
                "Darth"
            ]
        },
        {
            "msisdn": 1514654322,
            "tagvalues": [
                "Maul",
                "Darth"
            ]
        }
    ],
    "sender": "Empire",
    "sendtime": 915148800,
    "tags": [
        "%Lastname%",
        "%Firstname%"
    ],
    "userref": "1234",
    "priority": "VERY_URGENT",
    "validity_period": 86400,
    "encoding": "UTF8",
    "destaddr": "MOBILE",
    "callback_url": "https://example.com/cb?foo=bar"
}

Example response

If the request succeed, the internal message identifier are returned to the caller like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
HTTP/1.1 200 OK
Content-Type: application/json

{
    "ids": [
        421332671
    ],
    "usage": {
        "countries": {
            "DK": 2
        },
        "currency": "DKK",
        "total_cost": 0.30
    }
}

Please note that this response is subject to change and will continually, be updated to contain more useful data.

If the request fails, the response will look like the example below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
HTTP/1.1 403 FORBIDDEN
Content-Type: application/json

{
  "code": "0x0213",
  "incident_uuid": "d8127429-fa0c-4316-b1f2-e610c3958f43",
  "message": "Unauthorized IP-address: %1",
  "variables": [
    "1.2.3.4"
  ]
}

code and variables are left out of the response if they are empty. For a complete list of the various codes see API Errors.

If the extra_details option is set to recipients_usage the response will look like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
HTTP/1.1 200 OK
Content-Type: application/json

{
    "ids": [
        421332671, 4421332672
    ],
    "usage": {
        "countries": {
            "DK": 3
        },
        "currency": "DKK",
        "total_cost": 0.36
    },
    "details": {
        "messages": [
            {
                "id": 421332671,
                "recipients": [
                    {
                        "country": "DK",
                        "msisdn": 1514654321,
                        "parts": 1
                    },
                    {
                        "country": "DK",
                        "msisdn": 1514654322,
                        "parts": 1
                    }
                ]
            },
            {
                "id": 421332672,
                "recipients": [
                    {
                        "country": "DK",
                        "msisdn": 4512345678,
                        "parts": 1
                    }
                ]
            }
        ]
    }
}

Overcharged SMSes

Overcharged SMSes are only possible in Denmark for the moment. Contact our support if you are interested in using this feature.

An overcharged SMS is sent like a normal SMS, with a few extra parameters and restrictions.

Only one recipient per message is allowed. Messageclass charge must be used. Sendername is limited to 1204 or your own shortcode.

The charge object in recipient takes the following. See Advanced usage for full list of parameters.

POST /rest/mtsms

Request JSON Object:

  • amount (float) - The amount to be charged including VAT. required
  • currency (string) - Currency used in ISO 4217. required
  • code (string) - Product code. P01-P10. required
  • description (string) - Description of the charge to appear on the phonebill for the MSISDN owner. required
  • category (string) - Service category category. SC00-SC34. required

Full example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
POST /rest/mtsms HTTP/1.1
Host: gatewayapi.com
Authorization: Basic R28tQ3JlYXRlLWFuLUFQSS10b2tlbjoK
Accept: application/json, text/javascript
Content-Type: application/json

[
    {
        "message": "Thank you for your purchase",
        "class": "charge",
        "sender": 1204,
        "recipients": [
            {
                "msisdn": 4512345678,
                "charge": {
                    "amount": 50.75,
                    "currency": "DKK",
                    "code": "P01",
                    "category": "SC29",
                    "description": "Nokia tune",
                }
            }
        ]
    }
]

See Charge status for info about status reports and Refund charged SMS for info about refunding a charged sms.

Refund charged SMS

Charged SMSes that have successfully been captured are eligible for refunds. Sending charged SMSes requires special setup and permissions. You will not immediately know if the refund is successful, this info will be send to your callback url, or will be visible through the SMS log on your backend when updated.

POST /rest/refund

Only charged SMSes with charge status capture, can be refunded.

Request JSON Object:

  • mtsms_id (integer) - The id of the charged SMS to refund.
  • msisdn (integer) - The msisdn the charged messages was sent to.
  • callback_url (string) - Optional url for getting status of the refund.

Status Codes:

Get SMS and SMS status

You can use HTTP GET requests to retrieve a message based on its id, this will give you back the original message that you send, including delivery status and error codes if something went wrong. You get the ID when you send your message, so remember to keep track of the id, if you need to retrieve a message. This is only possible after the message has been sent, since only then is it transferred to long term storage.

Let us notify you

Please note we strongly recommend using Webhooks to get the status pushed to you when it changes, rather than poll for changes. We do not provide the same guarantees for this particular API endpoint as the others, since it runs on the reporting infrastructure.

GET /rest/mtsms/{message_id:int}

Parameters:

  • id (integer) - A SMS ID, as returned when sending the SMS

Status Codes:

Example request

1
2
3
4
5
POST /rest/mtsms/1 HTTP/1.1
Host: gatewayapi.com
Authorization: Basic R28tQ3JlYXRlLWFuLUFQSS10b2tlbjoK
Accept: application/json, text/javascript
Content-Type: application/json

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
HTTP/1.1 200 OK
Content-Length: 729
Content-Type: application/json

[
    {
        "class": "standard",
        "message": "Hello World, regards %Firstname, --Lastname--",
        "payload": null,
        "id": 1,
        "label": "Deathstar inc.",
        "recipients": [
            {
                "country": "DK",
                "csms": 1,
                "dsnerror": null,
                "dsnerrorcode": null,
                "dsnstatus": "DELIVERED",
                "dsntime": 1498040129.0,
                "mcc": 302,
                "mnc": 720,
                "msisdn": 1514654321,
                "senttime": 1498040069.0,
                "tagvalues": [
                    "Vader",
                    "Darth"
                ]
            },
            {
               "country": "DK",
               "csms": 1,
               "dsnerror": null,
               "dsnerrorcode": null,
               "dsnstatus": "DELIVERED",
               "dsntime": 1498040129.0,
               "mcc": 238,
               "mnc": 1,
               "msisdn": 4512345678,
               "senttime": 1498040069.0,
               "tagvalues": null
            }
        ],
        "sender": "Test Sender",
        "sendtime": 915148800,
        "tags": [
            "--Lastname--",
            "%Firstname"
        ],
        "userref": "1234",
        "priority": "NORMAL",
        "validity_period": 86400,
        "encoding": "UTF8",
        "destaddr": "MOBILE",
        "udh": null,
        "callback_url": "https://example.com/cb?foo=bar"
    }
]

Delete scheduled SMS

If you send SMSes using the sendtime parameter to schedule the sms for a specific time. You can send us DELETE requests for the id of the schudeled message and remove it from, the queue.

DELETE /rest/mtsms/{id:int}

You can only delete SMSes that have been added to the queue using the sendtime parameter.

Parameters:

  • id (integer) - A SMS ID, as returned when sending the SMS

Status Codes:

Webhooks

Although the REST API supports polling for the message status, we strongly encourage to use our simple webhooks for getting Delivery Status Notifications, aka DSNs.

In addition webhooks can be used to react to enduser initiated events, such as MO SMS (Mobile Originated SMS, or Incoming SMS).

If you filter IPs, note that we will call your webhook from the IP range 35.241.147.191/32 and 35.233.1.105/32. In the future we may add IPs but for now this is the range.

You can receive webhook callback by either setting up one of your webhooks as the default for the status notifications or by adding the callback_url field with the URL of your server that will receive the webhook event.

Whenever the message change state, either by our systems or our providers closer to the recipient.

If we cannot reach your server, or you reply with a http status code >= 400, then we will re-attempt delivery of the DSN after a 60 second delay, then 120 seconds, 360 seconds, 24 minutes, 2 hours and lastly after 12 hours. We expect you to reply with a 2XX status code within 15 seconds, or we consider it a failed attempt.

HTTP Callback

If you specify a callback url when sending your message, or have a webhook configured as your default webhook for status notification, we will perform a http request to your webhook with the following data.

POST /example/callback

Example of how our request to you could look like.

Request JSON Object:

  • id (integer) - The ID of the SMS/MMS this notification concerns
  • msisdn (integer) - The MSISDN of the mobile recipient.
  • time (integer) - The UNIX Timestamp for the delivery status event
  • status (string) - One of the states, in all-caps, ie. DELIVERED
  • error (string) - Optional error decription, if available.
  • code (string) - Optional numeric code, in hex, see SMS Errors, if available.
  • userref (string) - If you specified a reference when sending the message, it is returned to you
  • country_code (string) - Optional country code of the msisdn.
  • country_prefix (integer) - Optional country prefix of the msisdn.

Status Codes:

  • 200 OK - If you reply with a 2xx code, we will consider the DSN delivered successfully.
  • 500 Internal Server Error - If we get a code >= 300, we will re-attempt delivery at a later time.

Callback example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
POST /example/callback HTTP/1.1
Host: example.com
Accept: */*
Content-Type: application/json

{
    "id": 1000001,
    "msisdn": 4587654321,
    "time": 1450000000,
    "status": "DELIVERED",
    "userref": "foobar",
    "charge_status": "CAPTURED",
    "country_code": "DK",
    "country_prefix": 45
}

The charge_status is only present for overcharged SMSes.

MO SMS (Receiving SMSes)

Web hooks are also used to receive SMSes. We call this MO SMS (Mobile Originated SMS).

Prerequisites

In order to receive a SMS, you will need a short code and/or keyword to which the user sends the SMS. This short code and keyword is leased to you, so when we receive a SMS on the specific short code, with the specific keyword, we know where to deliver the SMS.

You can either lease a keyword on a shared short code, such as +45 1204, or you can lease an entire short code, such as +45 60575797. Contact us via the live chat if you need a new short code and/or keyword.

If you lease the keyword “foo” on the short code 45 1204, a Danish (+45) user would send ie. “foo hello world” to “1204”, and you will receive the SMS.

Once you have a keyword lease, you will need to assign the keyword to a webhook. You can do this from the dashboard.

  • If you do not have a webhook, add one.
  • Click the webhook you want to receive SMSes.
  • Click the tab pane “Keywords”
  • Make sure the checkbox next to “Assign” is checked for the keywords you want to assign to this webhook.

If you have any questions, please contact us using the live chat found ie. in the lower right when reading the documentation online.

HTTP Callback

POST /example/callback

Example of how our request to you could look like. The many optional fields are rarely used.

Request JSON Object:

  • id (integer) - The ID of the MO SMS
  • msisdn (integer) - The MSISDN of the mobile device who sent the SMS.
  • receiver (integer) - The short code on which the SMS was received.
  • message (string) - The body of the SMS, incl. keyword.
  • senttime (integer) - The UNIX Timestamp when the SMS was sent.
  • webhook_label (string) - Label of the webhook who matched the SMS.
  • sender (string) - If SMS was sent with a text based sender, then this field is set. Optional.
  • mcc (integer) - MCC, mobile country code. Optional.
  • mnc (integer) - MNC, mobile network code. Optional.
  • validity_period (integer) - How long the SMS is valid. Optional.
  • encoding (string) - Encoding of the received SMS. Optional.
  • udh (string) - User data header of the received SMS. Optional.
  • payload (string) - Binary payload of the received SMS. Optional.
  • country_code (string) - Optional country code of the msisdn.
  • country_prefix (integer) - Optional country prefix of the msisdn.

Status Codes:

  • 200 OK - If you reply with a 2xx code, we will consider the DSN delivered successfully.
  • 500 Internal Server Error - If we get a code >= 300, we will re-attempt delivery at a later time.

Callback example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
POST /example/callback HTTP/1.1
Host: example.com
Accept: */*
Content-Type: application/json

{
    "id": 1000001,
    "msisdn": 4587654321,
    "receiver": 451204,
    "message": "foo Hello World",
    "senttime": 1450000000,
    "webhook_label": "test",
    "country_code": "DK",
    "country_prefix": 45
}

Authentication token

When setting up your webhook you have an option to add an authentication token if you add text to this field we will use it to make a JWT token, which we will send back to your server in the X-Gwapi-Signature header.

JWT is widely supported and you can find libraries for mostly any programming language on jwt.io, that will show you how to verify the token.

To verify you need the token we send in the X-Gwapi-Signature header and the authentication token that you chose when setting up your webhook.

Code Examples

How to verify JWT tokens in different languages. More examples can be found on jwt.io.

In the following examples the secret shared between you and GatewayAPI are written directly in the code, in production environments, the shared secret should be part of your configuration, so it is better protected.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<?php
require_once 'vendor/autoload.php';
use \Firebase\JWT\JWT;
/*
  Token is extracted from the X-Gwapi-Signature header in the post request
  received on your webserver.
*/
$token = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6MjM4MTcwMywibXNpc2RuIjo0NTQyNjA5MDQ1LCJ0aW1lIjoxNTIyNzY0MDYyLCJzdGF0dXMiOiJERUxJVkVSRUQiLCJlcnJvciI6bnVsbCwiY29kZSI6bnVsbCwidXNlcnJlZiI6bnVsbCwiY2FsbGJhY2tfdXJsIjoiaHR0cDovL2JiYWY3MTQyLm5ncm9rLmlvIiwiYXBpIjo0fQ.KdfDH65bnQtgxEkFnpAQodOciAJedZFB13r9wEo8t3Y';
// secret is the secret token you have chosen when setting up your webhook.
$secret = "secret";
// Verify.
$decoded = JWT::decode($token, $secret, array('HS256'));
print_r($decoded);
?>
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# The token variable contains the jwt token
# extracted from X-Gwapi-Signature header from the post request received.
# on your webserver
token = (
  'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6MjM4MTcwMywibXNpc2RuIjo'
  '0NTQyNjA5MDQ1LCJ0aW1lIjoxNTIyNzY0MDYyLCJzdGF0dXMiOiJERUxJVkVSRUQiLCJlcnJ'
  'vciI6bnVsbCwiY29kZSI6bnVsbCwidXNlcnJlZiI6bnVsbCwiY2FsbGJhY2tfdXJsIjoiaHR'
  '0cDovL2JiYWY3MTQyLm5ncm9rLmlvIiwiYXBpIjo0fQ.KdfDH65bnQtgxEkFnpAQodOciAJ'
  'edZFB13r9wEo8t3Y')
# The secret chosen by you when setting up your webhook
secret = 'secret'
# Verify
decoded = jwt.decode(token, secret, algorithms=['HS256'])
print(decoded)
1
2
3
4
5
6
7
var jwt = require('jsonwebtoken');
// var secret is the secret that you chose and entered on gatewayapi.com
// when setting up your webhook.
var secret = 'secret'
var auth = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6MjM4MTcwMywibXNpc2RuIjo0NTQyNjA5MDQ1LCJ0aW1lIjoxNTIyNzY0MDYyLCJzdGF0dXMiOiJERUxJVkVSRUQiLCJlcnJvciI6bnVsbCwiY29kZSI6bnVsbCwidXNlcnJlZiI6bnVsbCwiY2FsbGJhY2tfdXJsIjoiaHR0cDovL2JiYWY3MTQyLm5ncm9rLmlvIiwiYXBpIjo0fQ.KdfDH65bnQtgxEkFnpAQodOciAJedZFB13r9wEo8t3Y'
var decoded = jwt.verify(auth, secret);
console.log(decoded);
1
2
3
4
5
require 'jwt'
token = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6MjM4MTcwMywibXNpc2RuIjo0NTQyNjA5MDQ1LCJ0aW1lIjoxNTIyNzY0MDYyLCJzdGF0dXMiOiJERUxJVkVSRUQiLCJlcnJvciI6bnVsbCwiY29kZSI6bnVsbCwidXNlcnJlZiI6bnVsbCwiY2FsbGJhY2tfdXJsIjoiaHR0cDovL2JiYWY3MTQyLm5ncm9rLmlvIiwiYXBpIjo0fQ.KdfDH65bnQtgxEkFnpAQodOciAJedZFB13r9wEo8t3Y'
secret = 'secret'
decoded = JWT.decode token, secret
puts decoded_token

Get MOSMS by API

A webhook is required to receive incoming messages, but in addition messages can also be retreived using a GET request.

GET /rest/mosms

Query Parameters:

  • from - The from date, in YYYY-MM-DD format required
  • to - The to date, in YYYY-MM-DD format required
  • page - Page number
  • per_page - Results per page (max 200)

Response JSON Array of Objects:

  • results (int) - Total results
  • pages (int) - Pages available
  • per_page (int) - Results per page
  • page (int) - Current page
  • messages (array) - Array of messages

Example request

1
2
GET /rest/mosms?from=2019-01-01&to=2019-01-14 HTTP/1.1
Host: gatewayapi.com

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
HTTP/1.1 200 OK
Content-Type: application/json

{
    "messages": [
        {
            "anonymized": null,
            "encoding": null,
            "message": "test",
            "mosms_id": 2398517,
            "msisdn": 4512345678,
            "receiver": 451204,
            "sender": null,
            "senttime": 1554465205.0,
            "webhook": "Rukikab"
        },
        {
            "anonymized": null,
            "encoding": null,
            "message": "test2",
            "mosms_id": 2398518,
            "msisdn": 4512345678,
            "receiver": 451204,
            "sender": null,
            "senttime": 1554465459.0,
            "webhook": "Fibotfus"
        }
    ],
    "page": 1,
    "pages": 1,
    "per_page": 50,
    "results": 2
}

HLR and Number lookup

We are at work on expanding our services with a HLR API, for now we are offering a number lookup API for Danish numbers only. This will only be available to selected customer. If you have use of this API talk to us on support and we will figure something out. Requested numbers can be of any of these forms +4512345678, 004512345678, 4512345678.

POST /rest/hlr

Request JSON Object:

  • msisdns (array) - List of numbers to lookup.

Status Codes:

Example request

1
2
3
4
5
6
7
GET /rest/hlr HTTP/1.1
Host: gatewayapi.com
Authorization: Basic R28tQ3JlYXRlLWFuLUFQSS10b2tlbjoK
Accept: application/json, text/javascript
Content-Type: application/json

[4512345678, 4587654321]

Example response

If the requests succeeds information for each valid number passed to the API, will be returned as below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
HTTP/1.1 200 OK
Content-Type: application/json

{
    "currency": "DKK",
    "hlr": {
        "4512345678": {
            "current_carrier": {
                "mcc": "238",
                "mnc": "20",
                "name": "Telia"
            },
            "network_operator": {
                "mcc": "238",
                "mnc": "20",
                "name": "Telia"
            },
            "original_carrier": {
                "mcc": "238",
                "mnc": "20",
                "name": "Telia"
            },
            "ported": false,
            "type": "GSM"
        }
   },
   "lookups": 1,
   "total_cost": 0.06
}