Skip to content

REST

This is our newest API which is available for GatewayAPI.com and based predominantly 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 SMS Messages

When you want to deliver an SMS to a user’s mobile device, also known as MT SMS, short for Mobile Terminated SMS.

Warning

Note that messages are subject to message filtering, based on the content, sender, and 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 an object with a single SMS or a list of SMS message objects. You can send data in JSON format, or even as http form data or query string parameters.

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. Otherwise 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 an object containing a list of IDs.
  • usage (object) - If successful you receive an object containing usage information 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 send large amounts of SMS messages, 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 SMS messages is a central part of most customer’s use cases, we host and maintain a few code examples in the dashboard.

Advanced Usage

POST /rest/mtsms

The root element can be either an object with a single SMS or a list of SMS message objects.

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 Class and uses the same routes, which anonymizes all sensitive data in your message once it has been sent. 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 a certain time.
  • tags (array) - A list of string tags, which will be replaced with the tag values for each recipient.
  • userref (string) - An 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 send a “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 special 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, otherwise use the default webhook.
  • label (string) - A label added to each sent message, which can be used to uniquely identify a customer or company that you have sent the message on behalf of. Can e.g. be used when invoicing your customers. If specified it must be the same for all messages in the request. See the statistics page to learn how to use this feature.
  • max_parts (int) - A number between 1 and 255 used to limit the number of SMS messages a single message will send. Can be used if you send SMS messages from systems that generate messages that you cannot control. This way you can ensure that you do not send very long SMS messages. You will not be charged for more than the amount specified here. Cannot be used with Tags or BINARY SMS messages.
  • 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 also known as the full mobile phone number of the recipient. Duplicates are not allowed in the same message. Required
  • charge (object) - Charge data. See Overcharged SMS messages.
  • tagvalues (array) - A list of string values corresponding to the tags in the message. The order and amount of tag values must exactly match the tags.

Response JSON Object:

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

Status Codes:

Fully fledged request

This is a bit a of contrived example, but it shows most of the possible fields in the API, such as 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 SMS Messages

Overcharged SMS messages 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 SMS messages that have successfully been captured are eligible for refunds. Sending charged SMS messages requires special account 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 SMS messages 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, which return original message that you sent, including delivery status and error codes if something went wrong. You receive the ID when you send your message, so remember to keep track of the ID, if you need to retrieve a message afterwards. This is only possible after the message has been sent, where it is transferred to long term storage.

Let us notify you

Please note that 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.

GET /rest/mtsms/{message_id:int}

Parameters:

  • id (integer) - An SMS ID, as returned from the API when the SMS was sent.

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 SMS messages using the sendtime parameter to schedule the sms for a specific time. You can send us DELETE requests for the ID of the scheduled message and remove it from the queue.

DELETE /rest/mtsms/{id:int}

You can only delete SMS messages 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 you to use our simple webhooks for getting SMS status reports.

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 callbacks 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 changes 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 the 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 description, 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 SMS messages.

Receiving SMS Messages

Webhooks are also used to receive SMS messages, which is often referred to as MO 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 SMS messages.
  • Click the tab “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.

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 the 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) - Country code of the msisdn. Optional
  • country_prefix (integer) - Country prefix of the msisdn. Optional

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 the 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 more or less 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 retrieved 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 working 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 for selected customer. If you want to use this API contact us on the support chat and we will figure something out. Requested numbers can be in any of these formats +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 request is successful, the response will contain information for each valid number sent in the request. Such as the example 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
}