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

Link Header

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:

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

• C#
• PHP
• Visual Basic

                                              
        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());
                }
        }
                                            
                                        

                                              
        $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

Statusgrupp Success

Status group Rejection

Status group Error

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

• C#
• PHP
• VB

                                                  
        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());
            }
        }
                                                
                                            

                                                  
        $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

• C#
• PHP
• VB

                                                  
        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

                                                        
        $conf = array(
            'account' => 'ip1-XXXXX',
            'password' => 'APIKey',
            'apiUrl' => 'api.ip1sms.com',
            'endpoint' => '/api/authentications',
            'method' => 'POST'
            );
            
        $message = array(
            'Phone' => '46712345678',
            'From' => 'iP1sms',
            'MessageFormat' => 'Använd denna kod för att verifiera: {0}',
            'Length' => '6',
            'ExpirationTime' => '1200'
        );
        
        $jsonEncodedMessage = json_encode($message);
        
        
        $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);
        
        $response = file_get_contents($SendUrl, false, $context);
        
        echo $response;
                                                        
                                                    

                                                        
        $submittedCode = $_POST["code"]; // e. g. 453342
        
        $conf = array(
            'account' => 'ip1-XXXXX',
            'password' => 'APIKey',
            'apiUrl' => 'api.ip1sms.com',
            'endpoint' => '/api/authentications/validate',
            'method' => 'POST'
            );
        
        $validate = array(
            'Phone' => '46712345678',
            'Code' => $submittedCode
        );
        
        $jsonEncodedValidation = json_encode($validate);
        
        $options = array(
            'http' => array(
                'header'  => array(
                    'Content-Type: application/json',
                    'Authorization: Basic '. base64_encode($conf['account'].":".$conf['password']),
                    'Content-Length: ' . strlen($jsonEncodedValidation)
                ),
                'method'  => $conf['method'],
                'content' => $jsonEncodedValidation,
            )
        );
        
        $ValidationUrl = "https://" . $conf['apiUrl'] . $conf['endpoint'];
        $context  = stream_context_create($options);
        
        $response = file_get_contents($ValidationUrl, false, $context);
        
        echo $response;
                                                        
                                                    

                                                        
        using (var client = new HttpClient())
        {
            client.BaseAddress = new Uri("http://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 authentication = new AuthenticationDTO()
            {
                Phone = "46712345678",
                From = "iP1sms",
                MessageFormat = "Use {0} to verify yourself",
                Length = "6"
                ExpirationTime = "1200"
            };
        
            HttpResponseMessage response = await client.PostAsJsonAsync("authentications", authentication);
        
            if (response.IsSuccessStatusCode)
            {
                Console.WriteLine("Sent");
            }
            else
            {
                Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
            }
        }
                                                        
                                                    

                                                        
        string submittedCode = Console.ReadLine(); // e. g. 453342
        
        using (var client = new HttpClient())
        {
            client.BaseAddress = new Uri("http://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 validation = new AuthenticationValidationRequest()
            {
                Phone = "46712345678",
                Code = submittedCode,
            };
        
            HttpResponseMessage response = await client.PostAsJsonAsync("authentications/validate", validation);
        
            if (response.IsSuccessStatusCode)
            {
                Console.Log("Validated");
            }
            else
            {
                Console.Log("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
            }
        }
                                                        
                                                    

Status codes

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

Status Codes HTTP

SMS Status codes

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;
                                    
                                

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;