Introduction - senast uppdaterad: 2016-03-29 08:53:43

This is our modern RESTful API, easily accessible by any system that can make proper HTTP requests using json formatting. It gives you access to most of our services directly in your own applications with minimal work.

Basic use-cases include contact management, SMS message reminders, notifications and communication.

Our premium services such as AnalysSMS are also available through API, with an added cost. With this you can have your application automatically send surveys and collect answers when needed.


Authentication - senast uppdaterad: 2016-03-29 09:08:12

All API calls require authentication with your account credentials. We use HTTP Basic Authentication using your account ID and API key. These can be found by logging in to our application.

Navigate to https://app.ip1sms.com/settings/#api and click on send API-key. Your API-key should now be sent to you in an SMS message.

To get your Basic Authentication string, take your account ID (i. e. ip1-12345) and your API-key (i. e. cCnbXFfyTM5BTKh7uNV) and run them through a Base64 encoder in the following way:

ip1-12345:CnbXFfyTM5BTKh7uNV

You should get at string that looks something like this:

aXAxLTEyMzQ1OkNuYlhGZnlUTTVCVEtoN3VOVg==

This is your HTTP Basic Authentication string and should be given as an HTTP header in the following way:

Authorization: Basic aXAxLTEyMzQ1OkNuYlhGZnlUTTVCVEtoN3VOVg==

Request structure - senast uppdaterad: 2016-03-29 09:58:38

The base URL for all API calls is api.ip1sms.com, and can be used with either HTTP or HTTPS as follows:

http://api.ip1sms.com/
or
https://api.ip1sms.com/

The rest of the URL is different for different calls, and that part is called the calls’ URI. Most URIs points to an entity or a collection of entities that is the target of the call (i. e. api/contacts points to the collection of contacts). The HTTP verb distinguishes the operation to perform on the target (i. e. GET reads and POST creates).

The body of all requests and responses that passes data is json formatted with utf-8 encoding for highest compatibility with different clients. Only entity IDs are passed via the URI.


Example: Send an SMS message - senast uppdaterad: 2018-08-24 14:01:55

Base URL: http://api.ip1sms.com/

Target URI: api/sms/send

Complete URL (Base URL + Target URI): http://api.ip1sms.com/api/sms/send

There are a few HTTP headers that are required. Firstly, authentication needs to be in place (see previous article). Secondly, Content-Type and Content-Length needs to be set to application/json; utf8 and the size of the body respectively. This makes sure the API understands that you send json formatted and utf8 encoded data in your request body.

The request body is json formatted and includes the following parameters:

Name

Description

Type

Additional information

From

Sending name or number: 3 - 11 digits (A - Z, 0 -9)

string

Required

Numbers

Recipient phone numbers

Collection of string

 

Contacts

Recipient contacts

Collection of integer

 

Groups

Recipient groups

Collection of integer

 

Message

Message contents

string

Required

Email

Whether to send SMS copies by email (for contacts with email addresses)

boolean

 

Prio

Message priority level, normal (1) or high (2)

integer

Range: inclusive between 1 and 2

For simplicity this example will only use the required parameters and a single phone number as recipient. This makes the effective parameters as follows:

Name

Value

From

iP1sms

Numbers

46123456789

Message

Hello world!

Let’s json encode these parameters and they become this:

{
   "From": "iP1sms",
   "Numbers": [
       "46123456789"
    ],
   "Message": "Hello world!"
}

We recommend you to send a maximum of 1000 recipients per http request

Now to make the request we need to use HTTP POST method as sending an SMS message is a creating operation. The complete URL, the authentication and formatting headers, and the json formatted body are POSTed. More on HTTP verbs in the next section.

The response contains information about each created message including sender, recipient, contents and status. This response is also json formatted for easy processing. The included information is as follows:

Name

Description

Type

ID

Message ID

integer

BundleID

Message bundle ID, if any

integer

Status

Message status code

integer

StatusDescription

Message status description

string

Prio

Message priority level, normal (1) or high (2)

integer

From

Sending name or phone number

string

To

Destination phone number

string

Message

Message contents

string

The json formatted version of this may look like this:

[
    {
       "ID": 65416,
       "BundleID": null,
       "Status": 0,
       "StatusDescription": "Delivered to gateway",
       "Prio": 1,
       "From": "iP1sms",
       "To": "46123456789",
       "Message": "Hello world!"
    }
]

A successful request will give an HTTP 200 status code and the response body as above. A failed request will give an HTTP error status code with an error message in header or body depending on the type of error. More on error codes and messages in the next section.


Technical API descriptions - senast uppdaterad: 2016-03-29 13:30:11

For further reading about specific API calls we refer to our Technical API descriptions at http://api.ip1sms.com/Help.


HTTP Verbs - senast uppdaterad: 2016-03-29 14:44:31

As per proper RESTful practice we use several HTTP verbs for different types of operations. The ones we use and what they are used for are as follows:

HTTP verb/method

Use/meaning

GET

Used for reading an entity or list/browse a collection of entities

POST

Used for creating a new entity or perform processing operations

PUT

Used for updating an entity with new information, replaces all previous data

DELETE

Used for removing an entity completely, and remove it from its collection


HTTP Status codes - senast uppdaterad: 2016-03-29 14:49:44

As per proper RESTful practice we use several HTTP status codes to distinguish different successes and failures of API calls.

These are used for successful API calls:

Status code

Name

Description

200

OK

Default success code, used for everything but entity creation

201

Created

Only used for successful entity creation, the Location header is used for pointing out the newly created entity

These are used for unsuccessful API calls:

Status code

Name

Description

400

Bad Request

Used when the user specified data contains faults, the body may contain information about which data is invalid and why

401

Unauthorized

Used when authentication information is missing or invalid, or if the authenticated user lacks access to the API call used

403

Forbidden

Used when correctly authenticated but trying to access an entity or collection of entities that the user has no access to, the status description may contain a reason

404

Not Found

Used when trying to access an entity or collection of entities that do not exist, or if the URI is invalid

405

Method Not Allowed

Used when trying to use an HTTP verb that cannot be used on the given entity or collection of entities

415

Unsupported Media Type

Used when trying to send non-json data or if the Content-Type header is missing

500

Internal Server Error

General error when something went wrong, if no other error is more appropriate, the response body may contain further details


SMS Status codes - senast uppdaterad: 2016-03-29 16:21:47

When sending SMS messages through our API calls status information is returned for each message. The status information is a code with an associated description. Although that description is included with the code it may be convenient to know which status codes are possible. This is a complete list of all SMS message status codes and their descriptions:

 

Status code

Description

0

Delivered to gateway

1

Gateway login failed

2

Invalid message content

3

Invalid phone number format

4

Insufficient funds

10

Received by the gateway

11

Delayed delivery

12

Delayed delivery cancelled

21

Delivered to the GSM network

22

Delivered to the phone

30

Insufficient funds

41

Invalid message content

42

Internal error

43

Delivery failed

44

Delivery failed

45

Invalid phone number

50

General delivery error

51

Delivery to GSM network failed

52

Delivery to phone failed

100

Insufficient credits

101

Wrong account credentials

110

Parameter error


Receiving phone number - senast uppdaterad: 2016-04-06 16:30:26

To receive incoming SMS messages, you need to have ordered either an eleven-digit phone number or a five-digit phone number with a keyword.

Order the number by logging in to our application and navigate to https://app.ip1sms.com/shop/ and place an order for the kind of number you want or contact us directly.


Callback HTTP - senast uppdaterad: 2016-04-06 16:32:42

When you have a receiving phone number (described in the previous article) you can optionally set up a callback URL to take care of getting received SMS messages as they arrive. This can be set via our application on https://app.ip1sms.com/settings/#extra or by contacting us directly.

Whenever an SMS message is sent to your receiving phone number we will make an HTTP GET request to its callback URL with the following parameters.

 

Name

Description

Type

incsmsid

ID of the SMS message

string

sender

Phone number of the sender

string

text

Contents of the message

string

to

Phone number of the recipient (your receiving phone number)

string

Example: if your callback URL looks like this:

http://www.example.com/smscallback.php

Then the request will look something like this:

http://www.example.com/smscallback.php?incsmsid=123456789&sender=4673222222&text=test+message&to=4673XXXXXXXXXXX

On a successful callback we expect an HTTP 200 response with only an unformatted OK in its body, anything else will be interpreted as unsuccessful. If unsuccessful we will try again once each hour for a maximum of ten attempts.


Callback e-mail - senast uppdaterad: 2016-04-06 16:33:16

When you have a receiving phone number (described in a previous article) you can optionally set up a callback e-mail address to take care of getting received SMS messages as they arrive. This can be set via our application on https://app.ip1sms.com/settings/#extra or by contacting us directly.

Whenever an SMS message is sent to your receiving number a copy of that SMS message will be sent as an e-mail message to its callback e-mail address.


base64encode.org - senast uppdaterad: 2016-04-06 16:43:52

A site for easy base64 en-/decoding. Useful when creating authentication strings manually.

https://www.base64encode.org/


Fiddler - senast uppdaterad: 2016-04-06 16:46:33

A useful tool for web debugging and HTTP API testing.

http://www.telerik.com/fiddler


Code Beautify (json) - senast uppdaterad: 2016-04-06 16:48:37

A useful site with tools for beautifying and navigating json strings.

http://codebeautify.org/jsonviewer