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 platform, and support at least TLS 1.2.

If you are using our EU platform (gatewayapi.eu), you have to replace the hostname in the examples below with host: gatewayapi.eu

Sending SMS Messages

When you want to deliver an SMS to a user’s mobile device, it is 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 use 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-7 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.
  • 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 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

We do not have a set rate limit towards our APIs, but we reserve the right to implement countermeasures against traffic that resembles a DoS attack. This means that you should not open an obscene amount of HTTP connections at the same time. In general, our API has a limit of 40 open connections, per IP address. If you have more than 40 open connections our web server may 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.

Do note that the actual delivery speed is defined by the operators, so sending 1000 messages in a few seconds will not make the delivery of the messages go much faster. 1 API call with 1000 messages will be delivered at the same speed as 10 API calls with 100 messages. In addition, if you receive callbacks for your messages, your web server should also be able to handle the same amount of traffic in a short timespan.

Code Examples

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

Advanced Use

POST /rest/mtsms

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

Multi SMS limits

Large SMS batches are limited to only allow up to 10 000 recipients and 1 000 SMS messages in a single request.

Note that we do not recommend sending multiple SMS messags with multiple recipients in a single API request - as it will impact the response time of the API in a negative way.

Request JSON Object:

  • class (string) - Default “standard”. The message class can be set to either “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-7 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) - One of BULK, NORMAL, URGENT and VERY_URGENT. Check the Limitations for details.
  • validity_period (integer) - Specified in seconds. If the 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. The default expiration - and maximum - for all messages is 5 days. Some messages might expire before that.
  • encoding (string) - Encoding to use when sending the message. Defaults to UTF8, which means we will use GSM-7. 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, i.e. an SMS you have encoded yourself or with special content for feature phones (non-smartphones). You may specify a payload, encoded as Base64. If specified, the “message” field 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 (integer | string) - MSISDN is 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 of a 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 succeeds, the internal message identifier is 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 this:

 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 currently only possible in Denmark. Contact our support if you are interested in using this feature.

An overcharged SMS is sent like a normal SMS, but 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 special parameters. See Advanced use 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. 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, but this info will be sent 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 CAPTURED can be refunded.

Request JSON Object:

  • mtsms_id (integer) - The ID of the charged SMS to refund.
  • msisdn (integer) - The MSISDN the charged messages were 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 returns the 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
GET /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) - An 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 end user 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 IPs 35.241.147.191 and 35.233.1.105. In the future we may add IPs.

If you are using our EU setup, the IPs are 49.12.113.232 and 78.47.225.149.

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.

Your webhook will be called whenever the message changes state, either by our systems or our providers.

If we cannot reach your server, or you reply with a HTTP status code >= 400, or the request times out after 5 seconds, then we will re-attempt delivery of the status report or incoming message after a short delay. This will continue with an exponential backoff until no further attempts can be made after about 24 hours.

SSL certificates will be verified, and you will not receive callbacks if you have an invalid certificate. Use our webhook tester in the dashboard to verify your webhook.

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

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, i.e. 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
  • mcc (string) - Optional MCC for the msisdn. Only present to certain accounts
  • mnc (string) - Optional MNC for the msisdn. Only present to certain accounts

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
16
17
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,
    "mcc": "238",
    "mnc": "01",
}

The charge_status is only present for overcharged SMS messages.

The MCC and MNC is only present if that feature is enabled on your account. Contact sales if you need such information in your callbacks.

Notice that you should not rely on the order of the JSON fields.

Receiving SMS Messages

Webhooks are also used to receive SMS messages, which is often referred to as MO SMS.

Prerequisites

In order to receive an SMS, you will need a short code and/or keyword to which the user sends the SMS. This short code and/or 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 i.e. “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

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

POST /example/callback

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 which will show you how to verify the token.

In order 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

Below you can see 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 tho this, 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 customers. If you want to use this API, then contact us on the support chat and we will advise you from there. Requested numbers can be in any of these formats +4512345678, 004512345678, 4512345678.

POST /rest/hlr

Request JSON Object:

  • msisdns (array) - List of numbers to look up.

Status Codes:

Example request

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

{
  "msisdns": [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
}