Swedish site
SMS Gateway

Developer site

RESTful SMS 2.0

Introduction

iP.1's API allows you to connect your websites and applications to mobile operators across the world.


Create Account

To use iP.1's API you need to register in our Web App in order to get your account setup.

After creating an account, log in to our User Portal to access your authentication credentials as explained below.


Authentication

All endpoints are protected by authentication using HTTP Bearer tokens provided by us. Any account may have several API tokens with different restrictions on allowed IP-addresses etc. These can be accessed, created and edited in our User portal.


Pagination

All endpoints which return a collection of documents (batches, messages etc.) have pagination turned on. We use the database style of pagination with start, limit and order as it's parameter names or offset, limit and order< by as they are called in MariaDB. By default the start, limit and order are set to 0, 50 and ASC respectively but you may change them to your liking by adding them as query parameters when making your HTTP request like this: ?start=0&limit=200&order=DESC

You'll also receive a Link header which includes pagination information.

        Link: <https://api.ip1sms.com/v2/batches?start=201&limit=100&order=ASC> rel="next",
        <https://api.ip1sms.com/v2/batches?start=4901&limit=100&order=ASC> rel="last"
                                

This example includes a line break for readability.

Possible rel values are:

Name Description
self The link relation for the requested page of results
first The link relation for the first page of results.
prev The link relation for the immediate previous page of results.
next The link relation for the immediate next page of results.
last The link relation for the last page of results.

Registering Senders

Before sending messages using our APIs you need to register the sender that you are going to use. You can have as many senders registered as you want and you can unregister the ones that you do not use anymore.

Reading registered senders

Endpoint: GET me/senders

This endpoint will provide you with the documents of all registered senders in your account like the response data type below. Ordered alphabetically by sender.

Register a sender

Endpoint: PUT me/senders/{sender}

This endpoint allows you to register a new sender.

Unregister a sender

Endpoint: DELETE me/senders/{sender}

This endpoint allows you to unregister a previously registered sender.

Response data type
        {
            "sender": "TestNOS",
            "created": "2018-10-23T17:43:19Z"
        }
                                

You are also able to register or remove senders in our web application Capacity SMS.


Code samples
                                              
        using (var client = new HttpClient())
        {
            client.BaseAddress = new Uri("https://api.ip1sms.com/v2/");
            client.DefaultRequestHeaders.Accept.Clear();
            client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "API Key");
        
            var sms = new OutgoingSMS()
            {
                "sender": "string",
                "recipients": {"46712345678"},
                "body": "string",
                "type": sms,
                "datacoding": gsm,
                "priority": 1,
                "reference": "Test",
                "tags": [
                    "Test SMS"
                    ]
            };
        
            HttpResponseMessage response = await client.PostAsJsonAsync("batches", sms);
        
            if (response.IsSuccessStatusCode)
                {
                    Console.WriteLine("Sent");
                }
            else
                {
                    Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
                }
        }
                                            
                                        

PHP >= 5.4.0 < 8.0.0
                                              
        $conf = array(
            'password' => 'API key',
            'apiUrl' => 'api.ip1sms.com/v2/',
            'method' => 'POST',
            'endpoint' => 'batches',
        );
        
        $message = array(
            "sender" => "ip1sms",
            "recipients" => ["46712345678"],
            "body" => "Test message rest v2",
            "type" => "sms",
            "datacoding" => "gsm",
            "priority" => 1,
            "reference" => "Test",
            "tags" => ["Test SMS"],
        );
        
        $jsonEncodedMessage = json_encode($message);
        // Set up request options
        $options = array(
            'http' => array(
                'header'  => array(
                    'Content-Type: application/json',
                    'Authorization: Bearer '.$conf['password'],
                    'Content-Length: ' . strlen($jsonEncodedMessage)
                ),
                'method'  => $conf['method'],
                'content' => $jsonEncodedMessage,
            )
        );
        
        $url = "https://" . $conf['apiUrl'] . $conf['endpoint'];
        $context  = stream_context_create($options);
        // Send the request
        $response = file_get_contents($url, false, $context);
        // Print the response
        echo $response;
                                            
                                        
                                              
        Dim account As String = "ip1-xxxxxx"
        Dim password As String = "API-Key"
        
        Dim client As New HttpClient()
        
        client.BaseAddress = New Uri("https://api.ip1sms.com/v2/")
        client.DefaultRequestHeaders.Accept.Clear()
        client.DefaultRequestHeaders.Accept.Add(New MediaTypeWithQualityHeaderValue("application/json"))
        
        client.DefaultRequestHeaders.Authorization = New AuthenticationHeaderValue("Bearer", "API Key")
        
        Dim sms As New With
        {
            Key .sender = "iP1sms",
            Key .recipients = New List(Of String)() From {"46712345678"},
            Key .body = "Test",
            key .type = "sms",
            key .datacoding = "gsm",
            key .priority = 1,
            key .reference = "Test",
            key .tags = "Test SMS"
        }
        
        Dim response As HttpResponseMessage = Await client.PostAsJsonAsync("batches", sms)
        
        
        End Sub`;
                                            
                                        

Status codes

Below you will find a list containing all available status codes for our RESTful SMS API 2.0. The codes are divided in three separate groups:

Info

Informative statuses that informs where along the pipeline the message is.

Success

If the message ended in a user defined way such as Expired or DeliveredToHandset.

Rejection

If there is something wrong with the message it self such as length, banned keywords, etc.

Error

If the message was undeliverable or other errors which is out of the control for the delivery service.


Status group Info
Name Code Group description
Accepted 101 Info The message(s) has been accepted for processing
Queued 102 Info The message has been put a queue for sending
Funded 103 Info The message has been paid for and can be sent
Refunded 104 Info The message has been refunded i.e. its price has been returned to the account balance
Sending 110 Info The message is being sent
DeliveredToGateway 111 Info The message has been delivered to the next upstream gateway
DeliveredToCarrier 112 Info The message has been delivered to the carrier on which the subscriber belongs to
DeliveredToGSM 113 Info The message has been put on the GSM network
QueuedAtGateway 114 Info The message has been queued at the upstream gateway
Statusgrupp Success
Name Code Group description
DeliveredToHandset 201 Success The message has been delivered to the recipient in question
Expired 202 Success The expiry date has been exceeded before the message could be delivered
Canceled 203 Success Message was canceled by user
Status group Rejection
Name Code Group description
InsufficientFunds 402 Rejection The account sending SMS doesn't have enough funds to send the SMS
SenderRejected 403 Rejection The sender was rejected, given when the sender is considered fraudulent or sender ownership hasn't been verified
ContentRejected 404 Rejection The message body contained content that is not allowed. Eg gambling, adult content, etc.
RecipientRejected 405 Rejection The recipient is illegal
GenericRejected 406 Rejection The message was rejected for a reason other than the options above
InvalidSender 407 Rejection The message sender is invalid. Eg. Sender is too long, contains illegal characters etc.
InvalidContent 408 Rejection Message content is invalid. Eg. illegal characters, is to long etc.
InvalidRecipient 409 Rejection Message recipient is invalid. Eg. Recipient was is not a valid MSISDN
MissingSmsSubscription 410 Rejection The recipient does not have an SMS subscription and can therefore not recieve SMS
Status group Error
Name Code Group description
InternalError 500 Error An unrecognized error occurred
UnknownSubscriber 501 Error The network subscriber doesn't exist
SubscriberUnreachable 502 Error The network subscriber was not online and could therefore not receive the message
SubscriberOffline 503 Error The subscriber is currently offline, delivery will be retried once the subscriber is back online
DeliveryToGatewayFailed 511 Error The message could not be handed over to the next upstream gateway
DeliveryToCarrierFailed 512 Error The message could not be handed over to the carrier
DeliveryToGSMFailed 513 Error The message could not be added to the GSM network
DeliveryToHandsetFailed 514 Error The message could not be handed over to the target handset
GenericDeliveryFailure 515 Error Generic Delivery Failure
GatewayError 516 Error An unrecognized error occured occured at the gateway
Unknown 599 Error Message was delivered upstream but no Delivery Receipt has been received or a Delivery Receipt that could not be interpreted was received

RESTful SMS 1.0

Introduction

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.


Authentication

HTTP Basic Read more about HTTP Basic Authentication here

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 user portal.

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==

HTTP Bearer Read more about HTTP Bearer Authentication here

You can also authenticate your API calls using HTTP Bearer tokens provided by us. Any account may have several API tokens with different restrictions on allowed IP-addresses etc. These can be accessed, created and edited in our User portal.


Request structure

For each request made, we recommend a maximum amount of 500 recipients / requests. For larger recipient lists, we recommend splitting the number of recipients into multiple requests with a maximum of 500 recipients in each.

The base for all URL is api.ip1sms.com and should be used with HTTPS as follows:

https://api.ip1sms.com

The rest of the URL is different for different calls, and that part is called the calls’ URI. Most URI 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.

Code samples
                                                  
        using (var client = new HttpClient())
        {
            client.BaseAddress = new Uri("https://api.ip1sms.com/api/");
            client.DefaultRequestHeaders.Accept.Clear();
            client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes(string.Format("{0}:{1}", "ip1-xxxxx", "API-Key"))));
        
            var sms = new OutgoingSMS()
            {
                From = "iP1",
                Numbers = new List() { "46123456789" },
                Contacts = new List(),
                Groups = new List(),
                Message = "test",
                Prio = 1,
                Email = false
            };
        
            HttpResponseMessage response = await client.PostAsJsonAsync("sms/send", sms);
        
            if (response.IsSuccessStatusCode)
            {
                Console.WriteLine("Sent");
            }
            else
            {
                Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
            }
        }
                                                
                                            

PHP >= 5.4.0 < 8.0.0
                                                  
        $conf = array(
            'account' => 'ip1-xxxxx',
            'password' => 'apiKey',
            'apiUrl' => 'api.ip1sms.com',
            'method' => 'POST',
            'endpoint' => '/api/sms/send',
        );
        
        $message = array(
            'Numbers' => ['4673055555'],
            'From' => 'iP1',
            'Message' => "Test message via iP.1's REST API",
        );
        
        $jsonEncodedMessage = json_encode($message);
        // Set up request options
        $options = array(
            'http' => array(
                'header'  => array(
                    'Content-Type: application/json',
                    'Authorization: Basic '. base64_encode($conf['account'].":".$conf['password']),
                    'Content-Length: ' . strlen($jsonEncodedMessage)
                ),
                'method'  => $conf['method'],
                'content' => $jsonEncodedMessage,
            )
        );
        
        $url = "https://" . $conf['apiUrl'] . $conf['endpoint'];
        $context  = stream_context_create($options);
        // Send the request
        $response = file_get_contents($url, false, $context);
        // Print the response
        echo $response;
                                                
                                            
                                                  
        Dim account As String = "ip1-xxxxxx"
        Dim password As String = "API-Key"
        
        Dim client As New HttpClient()
        
        client.BaseAddress = New Uri("https://api.ip1sms.com/api/")
        client.DefaultRequestHeaders.Accept.Clear()
        client.DefaultRequestHeaders.Accept.Add(New MediaTypeWithQualityHeaderValue("application/json"))
        
        Dim authString As String = Convert.ToBase64String(Encoding.ASCII.GetBytes($"{account}:{password}"))
        client.DefaultRequestHeaders.Authorization = New AuthenticationHeaderValue("Basic", authString)
        
        Dim sms As New With
            {
                Key .From = "iP1sms",
                Key .Numbers = New List(Of String)() From {"46123456789"},
                Key .Contacts = New List(Of Integer)(),
                Key .Groups = New List(Of Integer)(),
                Key .Message = "Test", Key .Email = False
            }
        
        Dim response As HttpResponseMessage = Await client.PostAsJsonAsync("sms/send", sms)
        
        
        End Sub`;
                                                
                                            

RESTful SMS Survey 1.0

Description

Here you will find everything you need to connect our RESTful Survey API to your system or application. With the help of a Survey API, you can easily customize your own automated customer surveys.


Code samples

                                                  
        using (var client = new HttpClient())
        {
            client.BaseAddress = new Uri("https://api.ip1sms.com/api/");
            client.DefaultRequestHeaders.Accept.Clear();
            client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes(string.Format("{0}:{1}", "ip1-xxxxx", "API-Key"))));
        
            var survey = new OutgoingSurvey()
            {
                From = "iP1",
                Numbers = new List() { "46123456789" },
                Contacts = new List(),
                Groups = new List(),
                Message = "test survey",
                Prio = 1,
                Email = false
            };
        
            HttpResponseMessage response = await client.PostAsJsonAsync("surveys/{survey}/send", survey);
        
            if (response.IsSuccessStatusCode)
            {
                Console.WriteLine("Survey Sent");
            }
            else
            {
                Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
            }
        }
                                                
                                            
                                                  
        $conf = array(
            'account' => 'ip1-xxxxx',
            'password' => 'apiKey',
            'apiUrl' => 'api.ip1sms.com',
            'method' => 'POST',
            'endpoint' => '/surveys/{survey}/send',
        );
        
        $message = array(
            'Numbers' => ['4673055555'],
            'From' => 'iP1',
            'Message' => "Test message via iP.1's REST API",
        );
        
        $jsonEncodedMessage = json_encode($message);
        // Set up request options
        $options = array(
            'http' => array(
                'header'  => array(
                    'Content-Type: application/json',
                    'Authorization: Basic '. base64_encode($conf['account'].":".$conf['password']),
                    'Content-Length: ' . strlen($jsonEncodedMessage)
                ),
                'method'  => $conf['method'],
                'content' => $jsonEncodedMessage,
            )
        );
        
        $url = "https://" . $conf['apiUrl'] . $conf['endpoint'];
        $context  = stream_context_create($options);
        // Send the request
        $response = file_get_contents($url, false, $context);
        // Print the response
        echo $response;
                                                
                                            
                                                  
        Dim account As String = "ip1-xxxxxx"
        Dim password As String = "API-Key"
        
        Dim client As New HttpClient()
        
        client.BaseAddress = New Uri("https://api.ip1sms.com/api/")
        client.DefaultRequestHeaders.Accept.Clear()
        client.DefaultRequestHeaders.Accept.Add(New MediaTypeWithQualityHeaderValue("application/json"))
        
        Dim authString As String = Convert.ToBase64String(Encoding.ASCII.GetBytes($"{account}:{password}"))
        client.DefaultRequestHeaders.Authorization = New AuthenticationHeaderValue("Basic", authString)
        
        Dim survey As New With
            {
                Key .From = "iP1sms",
                Key .Numbers = New List(Of String)() From {"46123456789"},
                Key .Contacts = New List(Of Integer)(),
                Key .Groups = New List(Of Integer)(),
                Key .Message = "Test", Key .Email = False
            }
        
        Dim response As HttpResponseMessage = Await client.PostAsJsonAsync("surveys/{survey}/send", survey)
        
        
        End Sub`;
                                                
                                            

RESTful 2FA

Description

By connecting to 2FA for example for registering new accounts, you can easily ensure that the person has entered the correct information by confirming the user's telephone number. The code is sent as a text message to the specified number in no time.

When you integrate two-factor authentication via SMS from iP.1, you automatically gain access to our global spam filter list that includes thousands of virtual numbers used in malicious bot registrations.

Code samples


Status codes

Below you will find a list of status code for both HTTP Calls and SMS Status codes.

Status Codes HTTP
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
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
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

SMS Gateway (Soap) Deprecated


Code samples
                                    
        $conf['apiurl'] = 'https://web.smscom.se/sendsms/sendsms.asmx?wsdl';
        $conf['mmsapiurl'] = 'https://web.smscom.se/mms/mms.asmx?wsdl';
        $conf['account'] = 'ip1-xxxxx';  
        $conf['password'] = 'API-Key'; 
        
        $conf['to'] = '46712345678'; 
        $conf['from'] = 'iP1';
        $conf['prio'] = '1';
        $conf['msg'] = 'Test message via iP.1 API (Web Service)';
        $conf['msg_at'] = "Test send at message via iP.1 API (Web Service)";
        $conf['msg_bundle'] = "Test bundle message via iP.1 API (Web Service)";
        
        $client = new SoapClient($conf['apiurl']);
        $mmsClient = new SoapClient($conf['mmsapiurl']);
        
        $result = $client->balans(array('konto'=>$conf['account'], 'passwd' => $conf['password']));
        echo 'Balnace: ' . $result->balansResult;
        
        $smsresult = $client->sms(array('konto'=>$conf['account'], 'passwd' => $conf['password'], 'till' => $conf['to'], 'from' => $conf['from'], 'meddelande' =>$conf['msg'], 'prio' => $conf['prio']));
        
        echo 'Result of SMS: ' . $smsresult->smsResult;
                                    
                                
Documentation SMS Gateway (Soap)

Deprecated This API is deprecated and will no longer be further developed. We recommend that you use one of our REST APIs


For each request made, we recommend a maximum amount of 500 recipients / requests. For larger recipient lists, we recommend splitting the number of recipients into multiple requests with a maximum of 500 recipients in each.

Complete documentation

SMS Gateway (http) Deprecated


Code samples

                                    
        $conf['account'] = 'ip1-xxxx';  
        $conf['password'] = 'api-key'; 
        $conf['apiurl'] = 'https://web.smscom.se/sendsms.aspx';
        
        $conf['to'] = '4673055555';     
        $conf['from'] = 'iP1';        
        $conf['msg'] = 'Test message via iP.1 HTTP Request';       
        $conf['prio'] = '1';
        
        $data = http_build_query(array('acc'=>$conf['account'],'pass'=>$conf['password'],'msg'=>  $conf['msg'],'from'=>$conf['from'],'to'=> $conf['to'],'prio'=>$conf['prio'], 'type' => ''));
                
        
        $opts = array('http' =>
            array(
                'method'  => 'GET',
                'header'  => 'Content-type: application/x-www-form-urlencoded',
                'content' => $data
            )
        );
        
        $context  = stream_context_create($opts);            
        $result = file_get_contents($conf['apiurl'] . '?' . $data, false, $context);
        
        echo 'Result/SMS ID: ' . $result;
                                    
                                
Documentation SMS Gateway (HTTP)

Deprecated This API is deprecated and will no longer be further developed. We recommend that you use one of our REST APIs


For each request made, we recommend a maximum amount of 500 recipients / requests. For larger recipient lists, we recommend splitting the number of recipients into multiple requests with a maximum of 500 recipients in each.

Complete documentation