Swedish site
SMS Gateway

SMS

English docs Swedish docs

Introduction RESTful

Getting started

Our SMS API allows you to connect your web services and applications to mobile operators around the world and is designed to handle high volumes of SMS traffic. This API is optimal for larger group sendings such as marketing, but also single sendings for automated SMS alarms etc.

Create account

To get started you will need an account, which you ca create here.

Once you have created your account, log in to our user portal to access your credentials, which are described in more detail in the step below.

API Endpoint

The base URL for all our endpints in our RESTful API is the following: https://api.ip1sms.com

All requests must be made using HTTPS.

Autentisering

All endpoints are protected by authentication using HTTP Bearer okens 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.

Sign into the User Portal with your iP.1 User that was created when you registered your account. Watch the instruciton video below in order to create your API key.

Pagination

All endpoints in /v2/, 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. start, limit och order are set to 0, 50 och 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

?start=0&limit=200&order=DESC

Register Sender

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.

Notice! If you are developing with a trial account you need to use the sender iP1 or iP1sms, which you also need to register to your account.

Reading Registered Senders

Endpoint: GET /v2/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 New Sender

Endpoint: PUT /v2/me/senders/{sender}

This endpoint allows you to register a new sender, returning its document if successful.

Unregister a Sender

Endpoint: DELETE /v2/me/senders/{sender}

This endpoint allows you to unregister a previously registered sender. The output is the same as when Reading a single registered sender above, when successful.

Responsdata-typ

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

You can also register and delete senders via the User Portal.


Code Examples

Below you will find code examples with authentication and functionality to register a sender.

Register Sender C#
                          
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 sender = "iP1";

    HttpResponseMessage response = await client.PutAsync($"me/senders/{sender}", null);

    if (response.IsSuccessStatusCode)
    {
        Console.WriteLine("Sender registered");
    }
    else
    {
        Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }
}
                        
                    
Register Sender PHP
                         
$conf = array(
    'password' => 'API Key',
    'apiUrl' => 'api.ip1sms.com/v2/',
    'method' => 'PUT',
    'endpoint' => 'me/senders/',
);

$sender = "iP1";

// Set up request options
$options = array(
    'http' => array(
        'header'  => array(
            'Authorization: Bearer '.$conf['password']
        ),
        'method'  => $conf['method']
    )
);

$url = "https://" . $conf['apiUrl'] . $conf['endpoint'] . $sender;
$context  = stream_context_create($options);
// Send the request
$response = file_get_contents($url, false, $context);
// Print the response
echo $response;
                        
                    

Sending SMS

Send one or multiple SMS

Endpoint

Endpoint: POST /v2/batches

Anropsdata-typ

At it's core the sending SMS endpoint needs the following values:

                            
{
    "sender": "iP1",
    "recipients":[
        "456189040623",
        "175368927054",
        "392094880589",
        "568798567631"
    ],
    "body": "A very nice message",
}
                            
                        

This will send a text message to each of the recipients containing the message "A very nice message". The sender ID for the message will be "iP1".

sender

The request will be rejected if the sender:

  • Is longer than 15 characters
  • does not match the regex [0-9A-Za-z]{1,11} or follow the E164 standard
  • is not registered to your account (See the section "Register Sender")

A message may not reach the recipient if:

  • The operator carrying the recipient does not support the sender
recipients

A request will be rejected if a recipients:

  • is longer than 15 characters
  • contains non digit characters

Each phone number will then be parsed and validated where the result will appear as a status for the message. If this step fails the message will not be sent.

body

A request will be rejected if the body:

    is null, empty or only whitespace
  • is longer than 2000 characters
Extended

Some may require additional features such as templating, scheduled sending, delivery reports and setting your own reference.

                        
{
    "sender": "iP1",
    "recipients":{
        "456189040623": {
            "sign": "sent by Bob"
        },
        "175368927054": {},
        "392094880589": {},
        "568798567631": {},
        "default":{
            "sign": " sent by iP.1"
        }
    },
    "body": "A very nice message{sign}",
    "type": "sms",
    "datacoding": "gsm",
    "priority": 1,
    "deliveryWindows": [
        {
            "opens": "ISO-8601 string",
            "closes": "ISO-8601 string"
        },
        {
            "opens": "ISO-8601 string",
            "closes": "ISO-8601 string"
        }
    ],
    "deliveryReportUrl": "https://api.example.com/sms/deliveryreport",
    "reference": "A client reference",
    "tags": ["marketing", "ux", "design"]
}
                        
                    
recipients - templating

In order to utilize our templating system you must convert your previous recipients array to a dictionary of dictionaries. The top level key is the recipient MSISDN (phone number). The second level key is then searched for in the text and then replaced by the second level value.

type

There are two types that an SMS may have, sms and flash. sms is a regular SMS while flash is shown once and then deleted from the handset. Default is sms.

datacoding

There are two types that are available:

  • gsm is a 7 bit character set which allows an SMS to be 160 characters long but with a limited range of characters to choose from.
  • ucs is a 2 byte character set which allows all characters(such as emoji, kanji etc) but lowers the character amount to 70 characters per SMS.

Om gsm is set any message that requires the extended character set of ucs will be denied from being sent. Default is ucs.

priority

In case it it very important for you that your messages to arrive quickly and not be hindered by by our other customers you may set a higher priority. However setting the priority to a higher value will increase the price by 0.01 EUR. Priority 1 is the default and is the lowest priority that is available, and Priority 2 is the highest priority available. If provided then 1 and 2 are the only valid values.

deliveryWindows

In case there is a need to schedule a sending in the future there's the possibility to do so with our delivery time windows.

You may have as many windows as you choose. This allows you to send messages at specific times over multiple days eg. every day between 10:00 and 10:05 on business days.

Parsing
  • null on the opens field will be replaced with the current date and time.
  • if closes is null the field will be set to 7 days (168 hours) after the opens field.

Request will be rejected if windows overlap.

If no windows are given we will create a window which will apply the parsing rule above.

deliveryReportUrl

If supplied, reports of status updates will be sent to this URL by POST. These reports are separate for each message recipient, and each status update. For further reading on these reports see Receiving Delivery Reports.

reference

This is a property which allows the user of this API to have their own ID or reference in case storing iP.1's generated IDs are not favored.

Restrictions
  • May be a maximum of 40 characters
  • Can not be empty string or whitespace.
tags

An array of tags used to categorize/sort the batch among your other batches. When listing batches you can filter by these.

Respons

If the request is accepted, the API will return a summary for the batch, which can be found later at the location specified by the location header. For more information about the response data type go to the section "Read Batches".

We return our response before we've gotten confirmed that your accounts financials has been confirmed so the price summary may not be set.


Code Examples

Below you will find a simple code example with authentication and functionality for sending an SMS.

Sending SMS C#
                          
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 = "iP1",
        Recipients = new List() { "46712345678" },
        Body = "Test message rest v2",
        Type = "sms",
        Datacoding = "gsm",
        Priority = 1,
        Reference = "Test",
        Tags = new List() { "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());
    }
}
    
public class OutgoingSMS
{
    public string Sender { get; set; }
    public List Recipients { get; set; }
    public string Body { get; set; }
    public string Type { get; set; }
    public string Datacoding { get; set; }
    public int Priority { get; set; }
    public string Reference { get; set; }
    public List Tags { get; set; }
}
                        
                    
Sending SMS PHP
                         
$conf = array(
    'password' => 'API key',
    'apiUrl' => 'api.ip1sms.com/v2/',
    'method' => 'POST',
    'endpoint' => 'batches',
);

$message = array(
    "sender" => "iP1",
    "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;
                        
                    

Reading Batches

Reading batches

Endpoint: GET /v2/batches

This endpoint will provide you with a collection of batches for which you can see the batch document definition below. However messageSummary and priceSummary will not be provided as those are only available to the single batch endpoint. Ordered chronologically by creation date.

Pagination

By adding a query for pagination on the call, you set a limit on how many batches you fetch

                        
https://api.ip1sms.com/v2/batches?start=0&limit=200&order=DESC
                        
                    
The example shows a list of 0 - 200 fetched batches for pagination on the call, so you set a limit on how many batches you fetch

Reading a Single Batch

Endpoint: Get /v2/batches/{batchId}

This endpoint will provide you with a single batch which will provide you with the total price of a batch as well as a summary of the statuses for the batch' messages.

Response data type

                        
{
    "id": "5bc86b6e85c7209830f96936",
    "sender": "iP1",
    "body": "Hi my name is {name}",
    "owner": "ip1-XXXXX",
    "type": "flash",
    "datacoding": "ucs",
    "priority": 1,
    "templated": true,
    "priceSummary": {
        "total": 0.125,
        "currency": "eur",
        "average": 0.0416
    },
    "messageSummary": {
        "101": {
        "messages": 43,
        "sms": 86
        },
        "102": {
        "messages": 3,
        "sms": 6
        },
        "201": {
        "messages": 142,
        "sms": 284
        }
    },
    "deliveryWindows": [
        {
            "opens": "ISO-8601 string",
            "closes": "ISO-8601 string"
        },
        {
            "opens": "ISO-8601 string",
            "closes": "ISO-8601 string"
        }
    ],
    "deliveryReportUrl": "https://api.example.com/sms/deliveryreport",
    "reference": "A client reference",
    "tags": ["marketing", "auth", "etc"],
}
                        
                    
sender

The sender ID used in the messages.

body

The original body sent before templating has been applied as supplied in the original request.

owner

The account ID of the SMS account that owns the batch (e.g. you).

type

There are two types that an SMS may have: sms and flash. sms is a regular SMS while flash is shown once and then deleted from the handset. Default is sms.

datacoding

Specifies the largest datacoding set allowed in the batch.

priority

In case it it very important for you that your messages to arrive quickly and not be hindered by by our other customers you may set a higher priority.

Please note that if you set a higher priority, the price per SMS will increase by 10 öre if you use a Swedish account, or € 0.01 if you use an international account.

Priority 1 is the default value and also the lowest available value, while priority 2 is the highest available value. If priority is set, 1 and 2 are the only values ​​allowed.

templated

Whether templating was utilized or not.

priceSummary

priceSummary.total The total price for the batch. This value may change if messages are rejected by the next upstream carrier in which case the payment for that specific message will be canceled.

priceSummary.currency What currency total and average are given in.

priceSummary.average The average price for a single message in the bundle. Note that a message differs from SMS since one message may require multiple SMS.

messageSummary

This is a dictionary where the key is a status code and the value is the count of how many messages (and their corresponding SMS segments) has that status code as it's most recently added status. For more information regarding our status codes for messages please see the section about status codes.

deliveryWindows

In case there is a need to schedule a sending in the future there's the possibility to do so with our delivery time windows. These are the current delivery time windows for this batch.

deliveryReportUrl

If supplied, reports of status updates will be sent to this URL by POST. These reports are separate for each message recipient, and each status update. For further reading on these reports see Receiving Delivery Reports.

reference

This is a property which allows the user of this API to have their own ID or reference in case storing iP.1's generated IDs are not favored.

tags

An array of tags used to categorize/sort the batch among your other batches. When listing batches you can filter by these.


Reading Messages

When you're reading messages it's always in the context of a batch. A message can not exist without a batch and therefore messages are placed below batches hierarchically.

Reading Messages

Endpoint: Get /v2/batches/{batch}/messages

This endpoint will provide you with the documents of all messages in a batch with their latest delivery report like the response data type below. Ordered chronologically by creation date.

Pagination

By adding a query for pagination on the call, you set a limit on how many batches you fetch

                        
https://api.ip1sms.com/v2/batches/{batch}/messages?start=0&limit=200&order=DESC
                        
                    
The example shows a list of 0 - 200 fetched messages
Read a Single Message

Endpoint: Get /v2/batches/{batch}/messages/{messageId}

This endpoint will provide you with the document of a single message with a full history of delivery reports like the data type below.

Response data type

Apart from reading the batch as a whole you may also look at specific messages.

                        
{
    "id": "5bc86b6e85c7209830f96936",
    "batchId": "5bcf4324ee47dee41a9dbb13",
    "owner": "ip1-XXXXX",
    "sender": "TestNOS",
    "recipient": "175368927054",
    "body": "Hi my name is earl",
    "direction": "mt",
    "segments": 1,
    "type":"SMS",
    "datacoding": "ucs",
    "priority": 1,
    "price": 0.0416,
    "currency": "EUR",
    "statuses": [
        {
            "created": "2018-10-23T17:43:21Z",
            "code": 201,
            "duration": 0
        }
    ],
    "modified": "2018-10-23T17:43:19Z",
    "reference": "A client reference",
    "mcc": "431",
    "mnc": "20"
}
                        
                    
id

A unique ID for the specific message.

batchId

An ID for all the messages sent in the same request as this message.

owner

The account ID of the SMS account that owns the message (e.g. you).

direction

Determines whether the message was sent or received by our systems.

mt an acronym for mobile terminated (Outgoing). mo an acronym for mobile originated (Incoming).

segments

In case the message contains more characters than one sms can hold the message will be split into multiple sms also known as concatenated sms. This property indicates how many sms the message needs to be sent.

datacoding

Specifies the smallest datacoding scheme needed to send the message in question. If characters outside of the specified datacoding are present in the message body the message is not sent, which the latest status code should reflect. This may differ from the batch's datacoding.

priority

The priority in which the message was sent. Priority 1 is the default and is the lowest priority that is available. Priority 2 is the higher priority.

price

The price for the entire message. In case you want to get the price for a single sms you can divide the number of segments by the price.

currency

Which currency the given price uses.

status

An array of status updates.

  • status[].created
    • when the status was added
  • status[].code
    • The specific status code. More may be added in the future
  • status[].duration
    • Tells whether this is the last status update or if there may be more status updates to come.

In the case that you're requesting a collection messages only the most recent status will be provided. However when requesting one specific message the entire status history will be provided. For more information regarding our status codes for messages please see our section about status codes.

modified

When the SMS was last updated.

reference

This is a property which allows the user of this API to have their own ID or reference in case storing iP.1's generated IDs are not favored.

mcc

The country part of the leaf operator may be specified here if it's provided by the upstream carrier.

MCC is an acronym for Mobile Country Code

mnc

The network part of the leaf operator may be specified here if it's provided by the upstream carrier.

MCC is an acronym for Mobile Network Code


Conversations

Read messages or message summaries regarding specific participants. Like conversations between you and a specific customer for example.

Messages

Read messages to and/or from a given participant.

The data returned is a paginated list of the same type of SMS objects seen in Reading SMS. Ordered chronologically by creation date.

  • All messages: GET /v2/conversations/{participant}
  • Outgoing messages: GET /v2/conversations/{participant}/mt
  • Incoming messages: GET /v2/conversations/{participant}/mo
participant

The sender ID of the participant whose messages are listed.

Sammanfattning

Apart from reading messages to and from specific MSISDNs we also provide an endpoint which gives you an aggregated summary with mt and mt

Endpoint: GET /conversations/{participant}/summary

                        
{
    "participant": "46734487112",
    "totalMessageCount": 387,
    "totalSmsCount": 774,
    "mobileTerminatedMessages": {
        "101": {
            "messages": 43,
            "sms": 86
        },
        "102": {
            "messages": 3,
            "sms": 6
        },
        "201": {
            "messages": 142,
            "sms": 284
        }
    },
    "mobileOriginatedMessages": {
        "201": {
            "messages": 199,
            "sms": 398
        }
    }
}
                        
                    
participant

A participant is either an MSISDN or an alphanumeric sender. This field tells what participant the summary is about.

totalMessageCount

The total number of messages with the participant.

totalSmsCount

The total number of SMS segments with the participant.

mobileTerminatedMessages

Summary of messages sent to the participant. This is a dictionary where the key is a status code and the value is the count of how many messages (and their corresponding SMS segments) has that status code as it's most recently added status.

mobileOriginatedMessage

Summary of messages sent from the participant. This is a dictionary where the key is a status code and the value is the count of how many messages (and their corresponding SMS segments) has that status code as it's most recently added status.


Receive incoming SMS

If an incoming delivery URL is specified in account settings, incoming SMS messages will be sent to that URL whenever they are available. The contents of these SMS messages are described below.

Our system sends the report using POST and expects a 200 OK response if the report is delivered correctly. If any other status (ie an error status) is received, the report will be sent again at a later time.

You manage your callback url in the user portal https://portal.ip1.net/accounts/ → Settings for incoming SMS (See image below)

Enter your callback url here

Rapport payload

                        
{
    "id": "5c613848879973045cf39ac4",
    "batchId": "5c613848879973045cf39ac3",
    "owner": "ip1-XXXXX",
    "sender": "TestNOS",
    "recipient": "456189040623",
    "body": "Hi my name is earl",
    "direction": "mt",
    "segments": 1,
    "type":"SMS",
    "datacoding": "ucs",
    "priority": 1,
    "statuses": [
        {
            "created": "2018-10-23T17:43:21Z",
            "code": 201,
            "duration": 1
        }
    ],
    "modified": "2018-10-23T17:43:19Z",
    "mcc": "431",
    "mnc": "20"
}
                        
                    
id

A unique ID for the specific message.

batchId

An ID for all the messages received in the same request as this message. This is usually just the one.

owner

The account ID of the SMS account that owns the message (e.g. you).

sender

The sender ID of the message's originator.

recipient

The recipient of the message (e.g. your virtual number).

body

The message contents.

direction

Determines whether the message was sent or received by our systems. Should always be mo here.

mt, an acronym for mobile terminated. mo, an acronym for mobile originated.

segments

In case the message contains more characters than one sms can hold the message will be split into multiple sms also known as concatenated sms. This property indicates how many sms the message needs to be sent.

datacoding

Specifies the datacoding scheme used to send the message in question.

priority

The priority in which the message was sent. Priority 1 is the default and is the lowest priority that is available. Priority 2 is the higher priority.

statuses

An array of status updates.

  • statuses[].created
    • when the status was added
  • statuses[].code
    • The specific status code. More may be added in the future
  • statuses[].duration
    • Tells whether this is the last status update or if there may be more status updates to come

Incoming messages only have one provided status as it entered our systems from outside. For more information regarding our status codes for messages please see our section about status codes.

modified

When the SMS was last updated.

mcc

The country part of the leaf operator may be specified here if it's provided by the upstream carrier.

mcc an acronym for Mobile Country Code

mnc

The network part of the leaf operator may be specified here if it's provided by the upstream carrier.

mnc an acronym for Mobile Network Code


Receive delivery reports

If a delivery report URL is specified when creating a batch, reports of status updates will be sent to that URL whenever they are available. The contents of these reports are described below.

Our system sends the report using POST and expects a 200 OK response if the report is delivered correctly. If any other status (i. e. an error status) is received then the report will be sent again at a later time. These retries are repeated each 10 minutes until an 200 OK is received, or for a maximum of 10 tries after which the report is discarded.

Report Payload

                        
{
    "messageId": "5c613848879973045cf39ac4",
    "batchId": "5c613848879973045cf39ac3",
    "recipient": "456189040623",
    "code": "102",
    "duration": 0,
    "created": "ISO-8601 string",
    "segments": 2,
    "price": 0.082,
    "currency": "eur",
    "reference": "A client reference"
}
                        
                    
messageId

A unique ID for the specific message.

batchId

An ID for all the messages sent in the same request as this message.

recipient

The recipient of the message.

code

The new status code for the message. See Status codes for more information on each status.

duration

Whether the status is permanent/final. If it is, then this is the last report that will be sent about this message.

created

When the status update occured (i. e. when the report was generated).

segments

In case the message contains more characters than one sms can hold the message will be split into multiple sms also known as concatenated sms. This property indicates how many sms the message needs to be sent.

price

The price for the entire message. In case you want to get the price for a single sms you can divide the number of segments by the price.

currency

Which currency the given price uses.

reference

This is a property which allows the user of this API to have their own ID or reference in case storing iP.1's generated IDs are not favored.


Status codes


Summary

This is a summary of what each status code group means. The way our status blocks works is that, for example, if the code starts with 1 then the status belongs to the status group Info. This allows us to add new status codes while still allowing your software to handle these new status codes without being explicitly developed for them.

Info

Informative statues 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.

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
Success
Name Code Group description
DeliveredToHandset 201 Success The message has been delivered to the recipient in questio
Expired 202 Success The expiry date has been exceeded before the message could be delivered
Canceled 203 Success Message was canceled by user
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
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

Managing landing pages

Reading a collection of landing pages

Endpoint: GET /v2/landings

This endpoint provides you with a collection of your landing pages. See the data type definition below..

Paginering

By adding a query for pagination on the call, you set a limit on how many landing pages you download.

                        
https://api.ip1sms.com/v2/landings?start=0&limit=10&order=DESC
                        
                    
The example shows a list of 0 - 10 downloaded landing pages

Read an individual landing page

Endpoint: Get /v2/landings/{landingId}

This endpoint gives you a single specific landing page.

Update a landing page

Endpoint: PUT /v2/landings/{landingId}

This endpoint allows you to update a specific landing page, change the stored data. Everything except elements, views and links are replaced with the new data.

Create a landing page

Endpoint: POST /v2/landings

This endpoint allows you to create a new landing page.

Delete landing page

Endpoint: POST /v2/landings/{landingId}

This endpoint allows you to delete a specific landing page.

Data type

    
        {
            "id": "615d9900792a81c7e32841ee",
            "name": "Welcome Page",
            "views": {
                "2021": 6,
                "2021-10": 4,
                "2021-10-19": 2,
                "2021-10-19 09:00:00": 1,
                "2021-10-19 11:00:00": 1,
                "2021-10-22": 2,
                "2021-10-22 15:00:00": 2,
                "2021-11": 2,
                "2021-11-22": 2,
                "2021-11-22 05:00:00": 2
            },
            "link": "https://landing.ip1.net/615d9900792a81c7e32841ee",
            "shortLink": "https://url.ip1.net/sdkkas",
            "lastModified": "2021-10-06T12:56:30.854Z",
            "elements": [
              {
                "type": "Title",
                "id": "615d9a0b792a81c7e32841ef",
                "order": 0,
                "backgroundColor": "#f7f7f7",
                "foregroundColor": "#111",
                "padding": "2",
                "margin": "0",
                "textAlignment": "Center",
                "font": "Roboto",
                "content": "Welcome to the Landing",
                "level": 1,
                "bold": false,
                "italic": false,
                "underline": false
              }
            ]
        }
    
id

The ID of the landing page, used to reference it..

name

The name of the landing page.

views

The number of times the landing page has been viewed by end users. A dictionary with keys as parts of timestamps (year, month, day, hour), and values as number of times the landing page has been viewed by end users during that part of time. Example below:

    
        {
            "2021": 6,
            "2021-10": 4,
            "2021-10-19": 2,
            "2021-10-19 09:00:00": 1,
            "2021-10-19 11:00:00": 1,
            "2021-10-22": 2,
            "2021-10-22 15:00:00": 2,
            "2021-11": 2,
            "2021-11-22": 2,
            "2021-11-22 05:00:00": 2
        }
    
lastModified

Timestamp of last modification to the landing page.

elements

A collection of the content elements on the landing page. More on these in "Element types".


Managing page elements

Read a collection of elements

Endpoint: GET /v2/landings/{landingId}/elements

This endpoint gives you a collection of elements on a specific landing page. See the definition of data type below.

Read a specific element

Endpoint: Get /v2/landings/{landingId}/elements/{elementId}

This endpoint gives you a specific element on a landing page.

Update an element

Endpoint: PUT /v2/landings/{landingId}/elements/{elementId}

This endpoint allows you to update an element on a landing page and change stored data. Everything is replaced by new values.

Create a new element

Endpoint: POST /v2/landings/{landingId}/elements

This endpoint allows you to create a new element on a landing page.

Delete an element

Endpoint: DELETE /v2/landings/{landingId}/elements/{elementId}

This endpoint allows you to delete an element on a landing page.

Data type

    
        {
            "type": "Title",
            "id": "615d9a0b792a81c7e32841ef",
            "order": 0,
            "backgroundColor": "#f7f7f7",
            "foregroundColor": "#111",
            "padding": "2",
            "margin": "2,0,2,0",
            "textAlignment": "Center",
            "font": "Roboto",
            "content": "Welcome to the Landing",
            "level": 1,
            "bold": false,
            "italic": false,
            "underline": false
        }
    
type

Element type. The example shows a title element.

id

Element ID, used to refer to a specific element.

order

The order of the element on the page, the page is rendered in ascending order (the ID breaks the bands). Optionally, the default value is null .

backgroundColor

The color used as the background of the element (Specified in hexadecimal), if applicable. The default value is #f7f7f7.

foregroundColor

The color used as the foreground of the element (Specified in hexadecimal), if applicable. The default value is #111.

padding

The padding added around the element. Either one (1) number for all pages, or four (4) digits comma-separated in order (top, bottom, left, right). All numbers from 0 to 8. The default is 2.

margin

The margin around the element. Either one (1) number for all pages, or four (4) digits comma-separated in order (top, bottom, left, right). All numbers from 0 to 8. The default is 0.


Element types

Here you will find definitions and descriptions of the different element types that are available for a landing page. All properties not explained in Manage Page Elements are explained here..

Title element

                      
{
  "type": "Title",
  "id": "615d9a0b792a81c7e32841ef",
  "order": 0,
  "backgroundColor": "#f7f7f7",
  "foregroundColor": "#111",
  "padding": "2",
  "margin": "2,0,2,0",
  "textAlignment": "Center",
  "font": "Roboto",
  "content": "Welcome to the Landing",
  "level": 1,
  "bold": false,
  "italic": false,
  "underline": false
}
                      
                  
level

A title levels. Valid values ​​are 1 - 5, of which 1 is the largest header size, 5 the smallest.

bold

Whether or not to display the title text in bold. default value is false

italic

Whether the title text should be displayed in italics or not. default value is false

underline

Whether the title text should be underlined or not. default value is false

Text block element

                      
{
  "type": "TextBlock",
  "id": "615db88a0f5018f08437bff5",
  "order": 1,
  "backgroundColor": "#f7f7f7",
  "foregroundColor": "#111",
  "padding": "2",
  "margin": "2,0,2,0",
  "textAlignment": "Left",
  "font": "Roboto",
  "content": "One row\n\nAnd another section",
  "fontSize": 16
}
                      
                  
fontSize

Font size in pixels. Default value is 16(px)

Button element

                    
{
  "type": "Button",
  "id": "615db9a50f5018f08437bff6",
  "order": 2,
  "backgroundColor": "#f7f7f7",
  "foregroundColor": "#111",
  "padding": "2",
  "margin": "2,0,2,0",
  "textAlignment": "Left",
  "font": "Roboto",
  "content": "Click me",
  "link": "https://example.com",
  "buttonType": "Standalone",
  "size": null,
  "buttonColor": "#89b642"
}
                    
                
buttonType

Determines the rendered button type. Valid values ​​are Standalone and block . The default value is Standalone .

size

Resizes the button element, larger or smaller. Valid values ​​are sm , lg and null . The default value is null .

color

Button element color (Specified in hexadecimal). The default value is # 89b642

Image element

                  
{
  "type": "Image",
  "id": "615dba140f5018f08437bff7",
  "order": 3,
  "backgroundColor": "#f7f7f7",
  "foregroundColor": "#111",
  "padding": "2",
  "margin": "2,0,2,0",
  "link": "https://example.com/cool-pic.png",
  "responsive": true,
  "alignment": "Center",
  "height": null,
  "width": null,
  "alt": "Image not available"
}
                  
              

Video element

                  
{
"type": "Image",
"id": "615dba140f5018f08437bff7",
"order": 3,
"backgroundColor": "#f7f7f7",
"foregroundColor": "#111",
"padding": "2",
"margin": "2,0,2,0",
"link": "https://example.com/cool-pic.png",
"responsive": true,
"alignment": "Center",
"height": null,
"width": null,
"alt": "Image not available"
}
                  
              
showControls

Determines whether or not controls for video elements are displayed. The default value is false

autoplay

Decides whether the video should start automatically as soon as the page loads or not. The default value is false

loop

Decides whether to play the video in a loop or not. The default value is false

muted

Determines whether the sound should be muted when the page is loaded or not. The default value is false

Common properties

textAlignment

The adjustment of the text content of the element. Valid values ​​are Left , Center , Right and Justified . The default value is Left .

alignment

The adjustment of media content inside an element. Valid values ​​are Left , Center and Right . The default value is Center .

font

The font used for text content in an element. Accepts any standard web font.

content

The text content of the element. For text blocks, this is interpreted as Markdown when rendered.

responsive

Whether to scale the video or image responsively. The default value is true .

height

The height of the video or image (in pixels). Ignored if the media object is to be scaled responsively. Voluntary. The default value is null .

width

The width of the video or image (in pixels). Ignored if the media object is to be scaled responsively. Voluntary. The default value is null .

alt

The alternate text to be displayed if the video or image cannot be loaded or displayed. The default value is null .


Configure 2FA


Get current configuration

Endpoint: GET /api/authentications/settings

This endpoint allows you to retrieve the current configuration for 2FA.


Update configuration

Endpoint: PUT /api/authentications/settings

This endpoint allows you to update the configuration for 2FA.

Request data type

                      
{
  "ConcurrentLimit": 1,
  "From": "iP1",
  "MessageFormat": "Use the following code to authenticate: {0}",
  "Length": 6,
  "ExpirationTime": 3600,
  "NumericOnly": true
}
                      
                  

Response data type

                      
{
  "ConcurrentLimit": 1,
  "From": "iP1",
  "MessageFormat": "Use the following code to authenticate: {0}",
  "Length": 6,
  "ExpirationTime": 3600,
  "NumericOnly": true
}
                    
                
ConcurrentLimit

The number of simultaneous authentications that are possible for one and the same mobile number.

From

The sender used in the SMS that carries the authentication code.

MessageFormat

The message that carries the code, where {0} represents a unique code for each recipient.

Length

The length of the authentication code.

ExpirationTime

The time when the authentication code expires.

NumericOnly

Whether the authentication code should consist of numbers only or not.


Manage and send 2FA


Create and send authentication

Endpoint: POST /api/authentications

This endpoint allows you to create and send out a new authentication.

Request data type

                      
{
  "Phone": "46712345678",
  "From": "iP1",
  "MessageFormat": "Use the following code to authenticate: {0}",
  "Length": 6,
  "ExpirationTime": 3600,
  "NumericOnly": true
}
                      
                  
Phone

The mobile number to which the authentication is to be sent.

Typ: String

From

The sender used in the SMS that carries the authentication code.

MessageFormat

The message that carries the code, where {0} represents a unique code for each recipient.

Length

The length of the authentication code.

ExpirationTime

The time when the authentication code expires.

NumericOnly

Whether the authentication code should consist of numbers only or not


List your authentications

Endpoint: GET /api/authentications

This endpoint allows you to list all your authentications.

Read an individual authentication

Endpoint: POST /api/authentications/{authentication}

This endpoint allows you to read an individual authentication.

Delete/cancel an authentication

Endpoint: DELETE /api/authentications/{authentication}

This endpoint allows you to delete/cancel a specific authentication.

Response data type

                        
{
  "ID": 1,
  "Phone": "sample string 2",
  "Created": "2022-06-15T14:38:32.8668254+00:00",
  "HasExpired": true,
  "Expires": "2022-06-15T14:38:32.8668254+00:00",
  "IsUsed": true,
  "Used": "2022-06-15T14:38:32.8668254+00:00"
}
                      
                  
ID

A specific authentication identifier.

Phone

The mobile number to which the authentication was sent.

Created

A date stamp that shows when the authentication was created.

HasExpired

Shows whether the authentication has expired or not.

Expires

A date stamp that shows when the authentication is due.

IsUsed

Shows whether an authentication is used or not.

Used

A date stamp indicating when the authentication was used.


Validate 2FA


Validate authentication

Endpoint: POST /api/authentications/validate

This endpoint allows you to validate an authentication code.

Request data type

                      
{
  "Phone": "sample string 1",
  "Code": "sample string 2"
}
                      
                  

Response data type

                      
{
  "Valid": true,
  "Authentication": {
    "ID": 1,
    "Phone": "sample string 2",
    "Created": "2022-06-15T14:21:25.3577027+00:00",
    "HasExpired": true,
    "Expires": "2022-06-15T14:21:25.3577027+00:00",
    "IsUsed": true,
    "Used": "2022-06-15T14:21:25.3577027+00:00"
  },
  "Phone": "sample string 2",
  "Code": "sample string 3"
}
                    
                
Valid

A value of true or false if the code is valid or invalid.

Valid

A list of information regarding a specific authentication.

ID

En specifik autentiserings identifierare.

Phone

A specific authentication identifier.

Created

A date stamp that shows when the authentication was created.

HasExpired

Shows whether the authentication has expired or not.

Expires

A date stamp that shows when the authentication is due.

IsUsed

Shows whether an authentication is used or not.

Used

A date stamp indicating when the authentication was used.

Phone

The mobile number that has been authenticated.

Code

The authentication code used in the authentication.


Summary contacts

Get contact data

Endpoint: GET /v2/contacts/meta

This endpoint provides a summary of the contact data stored in the contact system.

Response data type

                        
        {
            "totalCount": 10,
            "labels": [
                {
                    "labelName": "all",
                    "usageCount": 10
                },
                {
                    "labelName": "Customer",
                    "usageCount": 7
                },
                {
                    "labelName": "Coworker",
                    "usageCount": 3
                }
            ],
            "properties": [
                {
                    "propertyName": "email",
                    "usageCount": 9,
                    "averageLength": 20,
                    "maxLength": 26,
                    "minLength": 16
                },
                {
                    "propertyName": "firstName",
                    "usageCount": 10,
                    "averageLength": 5,
                    "maxLength": 6,
                    "minLength": 3
                },
                {
                    "propertyName": "lastName",
                    "usageCount": 10,
                    "averageLength": 7,
                    "maxLength": 12,
                    "minLength": 5
                },
                {
                    "propertyName": "department",
                    "usageCount": 10,
                    "averageLength": 4,
                    "maxLength": 8,
                    "minLength": 3
                },
                {
                    "propertyName": "phoneNumber",
                    "usageCount": 10,
                    "averageLength": 12,
                    "maxLength": 12,
                    "minLength": 12
                }
            ]
        }
                        
                    
totalCount

The total number of contacts stored.

labels

One entry for each label used.

labels.labelName

An individual Labels name

labels.usageCount

The number of stored contacts assigned to the label.


properties

One record for each property used.

properties.propertyName

The name/key of the property.

properties.usageCount

The number of contacts that have a value for the property.

properties.averageLength

The average length of the property among stored contacts.

properties.maxLength

The longest value for the property among the stored contact.

properties.minLength

The shortest value of the property among the stored contact.


Managing contacts

Read a collection of contacts

Endpoint: GET /v2/contacts

This endpoint gives you a collection of contacts for which you can see the definition of the contact document below. This collection can be filtered by properties, metadata and / or labels using query parameters. Metadata is only available if meta is added as a query parameter.

Examples of filters: https://ip1-api-gateway-dev.azure-api.net/v2/contacts?labels=Coworker&properties%5BphoneNumber%5D=%2B46123456789&metadata%5BphoneNumber.isBlocked%5D=false

Pagination

By adding a query for pagination on the call, you set a limit on how many contacts you retrieve

                        
https://api.ip1sms.com/v2/contacts?start=0&limit=200&order=DESC
                        
                    
The example shows a list of 0 - 200 retrieved contacts

Read an individual contact

Endpoint: Get /v2/contacts/{contactId}

This endpoint gives you a single specific contact. Metadata is only available if "meta" is added as a query parameter.

Update a contact

Endpoint: PATCH /v2/contacts/{contactId}

Endpoint: PUT /v2/contacts/{contactId}

With these endpoints you can update a contact and change stored data. The first endpoint makes a partial update, indicates any values ​​that exist and removes all clear null values ​​if any. The other replaces everything with new data regardless of previous values.

Add/import contacts

Endpoint: POST /v2/contacts

This endpoint allows you to add/import new contacts. It takes a collection of contact documents. By default, the contacts are accepted and then imported into the background, but this can be done directly by adding sync as a query parameter. Direct import is recommended only for small collections of contacts (less than 1000).

Delete contact

Endpoint: POST /v2/contacts/{contactId}

This endpoint allows you to delete a contact. There is also an endpoint for deleting more than one contact, see the section for Mass Operations.

Response data type

    
        {
            "id": "606312a5d233ab8484e18404",
            "ownerId": "ip1-XXXXX",
            "properties": {
                "phoneNumber": "+46123456789",
                "email": "icarus@example.com",
                "firstName": "Icarus",
                "lastName": "Sol",
                "department": "Sales"
            },
            "metadata": {
                "phoneNumber": {
                    "isPossiblePhoneNumber": "true",
                    "isValidPhoneNumber": "true",
                    "phoneNumberType": "MOBILE",
                    "parsedMSISDN": "46123456789",
                    "isBlocked": "false"
                }
            },
            "labels": [
              "Coworker",
              "all"
            ]
          }
    
id

Contact ID, used to refer to a specific contact.

ownerId

The account that owns the contact.

properties

A dictionary of contact properties, such as telephone numbers, names, company information, etc.

metadata

Metadata about certain properties. A dictionary with metadata properties for each metadata property. Things like validation results and blocked status

labels

A collection of labels for the connector. Most often used to categorize or group contacts.


Code example

Below you will find a simple code example including authentication for adding a contact.

Add a contact C#
                          
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 contact = new Contact()
    {
        properties = new Dictionary() {
            { "phoneNumber", "46712345678"},
            {"email" , icarus@example.com},
            {"firstName" , "Icarus"},
            {"lastName" , "Sol"},
            {"department" , "Sales"}
        },
        labels = new List() 
        { 
            "Coworker",
            "Sales"
        }
    };

    HttpResponseMessage response = await client.PostAsJsonAsync("contacts", contact);

    if (response.IsSuccessStatusCode)
    {
        Console.WriteLine("Sent");
    }
    else
    {
        Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }
}
    
public class Contact
{
    public Dictionary properties { get; set; }
    public List labels { get; set; }
}                            
                        
                    

Managing labels

These endpoints update all contacts in perspective from a label and return a summary of the label in question.

Add a label for multiple contacts

Endpoint: POST /v2/labels/{labelName}/contacts

This endpoint allows you to add a label to many contacts at once. It takes a collection of contact IDs

Example:
    
        [
            "5d8b19f972c0b7514c5b0f"
            "5d8b19f972c0b7515c5b0f"
            "5d8b19f972c0b7516c5b0f"
        ]
    

Delete a label

Endpoint: DELETE /v2/labels/{labelName}

This endpoint allows you to delete a label and can remove it from any contacts that have it. The contacts are otherwise intact.

Responsdata-typ

    
        {
            "labelName": "Coworker",
            "usageCount": 3
        }
    
labelName

Label name.

usageCount

The number of contacts that use the label.


Mass operations

These endpoints perform so-called mass operations and can sometimes be destructive or "dangerous" as data can disappear if not used properly.

Delete contacts by filtering

Endpoint: DELETE /v2/contacts

This endpoint allows you to delete all contacts that match the filters used. These are the same filters as for listing contacts (see Managing Contacts). This is destructive and should be used with caution. It returns a collection of the deleted contacts much like listing them.


Managing blacklist


Read blacklist

Endpoint: GET /v2/blacklist

This endpoint allows you to read your entire blacklist.

Add an entry

Endpoint: POST /v2/blacklist

This endpoint adds an entry to your blacklist.

Read a single entry

Endpoint: GET /v2/blacklist/{msisdn}

This endpoint allows you to read a specific entry in your blacklist.

Add or update an entry

Endpoint: PUT /v2/blacklist/{msisdn}

Denna endpoint låter dig uppdatera eller lägga till en post i din blacklist.

Delete an entry

Endpoint: DELETE /v2/blacklist/{msisdn}

This endpoint allows you to delete an entry from your blacklist.

Data type

    
        {
            "msisdn": "46703541190",
            "created": "2019-11-01T16:32:18.253"
        }
    
msidsn

Det tillagda mobilnumret.

created

Datumet då posten lades till i blacklisten.



Overview Account


Overview main account

Endpoint

Endpoint: GET /api/me

This endpoint will give you an overview of your main account

Response data type

                        
{
    "Account": "string",
    "Organization": "string",
    "Type": "string",
    "Balance": 0.0,
    "Currency": "string"
}
                        
                    
Account

The unique ID of an individual account consisting of the prefix ip1- followed by a number of digits.

Organization

The company/organization name that owns the account.

Type

An individual accounts account type, swedish or international. Accounts of type swedish is is only suitable for SMS traffic within Sweden. All traffic outside of Swedenb will be billed 1 SEK extra/SMS. Accounts of type international gives you a specific price/sms based on the country code.

Balance

An individual accounts balance level. The balance can be a negative number if post billing is used.

Currency

Gives you the currency of nn individual account. SEK or EUR.


Details account


Get details for an account

Endpoint

Endpoint: GET /api/me/account

This endpoint will give you the details of a specific account, according to the response data type below.

Response data type

                        
{
    "Key": "string",
    "Parent": "string",
    "Type": "string",
    "Balance": 0.0,
    "Currency": "string",
    "ID": "string",
    "Name": "string"
}
                        
                    
Key

A specific account's API Key..

Parent

A specific account's parent account.

Type

A specific account's account type.

Balance

A specific account's balance level. The balance can be a negative number if post billing is used.

Currency

Gives you the currency of the specific account. SEK or EUR.

ID

A specific account's unique ID consisting of the prefix ip1- followed by a number of digits.

Name

A specific account's label, use this as a reference to tell different accounts apart.


Create Sub Account


Create a new Sub Account

Endpoint

Endpoint: POST /api/me/children

This endpoint lets you create a new sub account with your main account as parent.

Request data type

                        
{
    "Name": "string"
}
                        
                    
Name

The sub account's label, use this as a reference to tell accounts apart.

Response data type

                        
                            
{
    "Key": "string",
    "Parent": "string",
    "Type": "string",
    "Balance": 0.0,
    "Currency": "string",
    "ID": "string",
    "Name": "string"
}
                        
                    
Key

A sub account's API Key

Parent

A sub account's parent account.

Type

A sub account's account type.

Balance

A sub account's balance level. The balance can be a negative number if post billing is used.

Currency

A sub account's currency.

ID

A sub account's ID, contains of the prefix ip1- followed by a number of digits.

Name

A sub account's label, use this as a reference to tell different accounts apart.


Lista underkonton


List all sub accounts

Endpoint

Endpoint: GET /api/me/children

This endpoint lets you request a list of all sub accounts connected to your parent account.

List individual sub-account

Endpoint

Endpoint: GET /api/me/children{child}

This endpoint lets you list a single sub account connected to your parent account.

Response data type

                        
{
    "Key": "string",
    "Parent": "string",
    "Type": "string",
    "Balance": 0.0,
    "Currency": "string",
    "ID": "string",
    "Name": "string"
}
                        
                    
Key

An individual sub-account API key.

Parent

A single sub-account parent account.

Type

An individual sub-account account type.

Balance

Balance level of an individual sub-account. May consist of a negative number or a positive number depending on which payment model is linked to the account.

Currency

Currency of an individual sub-account.

ID

An individual sub-account ID, consists of the prefix ip1- followed by a number of digits.

Name

the labeling of an individual sub-account. For example, department or reference to the purpose of the account.


Update Sub Account


Update an individual sub account

Endpoint

Endpoint: put /api/me/children/{child}

This endpoint lets you update an individual sub account connected to a main account.

Request data type

                        
{
    "ID": "string",
    "Name": "string"
}
                        
                    
ID

A specific sub account's ID, contains of the prefix ip1- followed by a number of digits.

Name

A specific sub account's label, use this as a reference to tell different accounts apart.

Response data type

                        
{
    "Key": "string",
    "Parent": "string",
    "Type": "string",
    "Balance": 0.0,
    "Currency": "string",
    "ID": "string",
    "Name": "string"
}
                        
                    
Key

A specific sub account's API Key.

Parent

A specific sub account's parent account.

Type

A specific sub account's account type.

Balance

A specific sub account's balance level. The balance can be a negative number if post billing is used.

Currency

A specific sub account's currency.

ID

A specific sub account's ID, contains of the prefix ip1- followed by a number of digits.

Name

A specific sub account's label, use this as a reference to tell different accounts apart.


Inkommande SMS

För att ta emot inkommande SMS behöver du ett virtuellt nummer. I vår webshop kan du beställa ett virtuellt nummer med svensk landskod (11 siffror) samt ett prefix till vårt delade kortnummer (5 siffror) till ditt konto. Behöver du ett virtuelt nummer med annan landskod än svensk, kontakta oss för pris och leveranstid.

Kom ihåg att avsändaren inte får bestå av ett nummer längre än 15 tecken och att det bara är möjligt att ta emot meddelanden från vår server om detta krav är uppfyllt.

Callback

Det enklaste sättet att hantera inkommande SMS är att skapa en webb-applikation och sedan registrera en callback-URL för mottagarnumret hos oss.

När ett meddelandet tas emot av vår gateway så genomförs ett HTTP GET till callback-URL:en med följande parametrar:

Parameter Beskrivning Typ
text Meddelandets innehåll Sträng
to Mottagarens telefonnummer Sträng
sender Avsändare Sträng
incsmsid ID-nummer sträng

Exempel: Om din callback-URL är http://www.example.com/smscallback.php ser anropet ut så här:

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

Det är också möjligt att skapa ett anrop med query-strängar, till exempel: http://www.example.com/smscallback.php?someparam=somevalue

Som svar på ditt callback-anrop ska din applikation returnera ett oformaterat OK (två tecken, utan formatering). Om ditt anrop inte lyckas eller om du får ett annat svar från servern så kommer servern att försöka igen med en intervall på 30 minuter, maximalt tio försök.

Lägg till en Callback-URL

När du har en färdig Callback-url måste du registrera den på https://app.ip1sms.com/settings/#extra. Logga in med din iP.1 Användare. Klistra in din URL i text-fältet ”Callback URL och spara dina inställningar.

Kodexempel

Nedan hittar du ett enkelt kodexempel med autentisering och funktionalitet för att skicka ett enskilt SMS.

Kodexempel C#

                          
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
    {
        sender = "iP1",
        recipients = new string[] { "46712345678" },
        body = "Test Message",
        type = "sms",
        datacoding = "ucs",
        priority = 1,
        reference = "Test"
    };

    StringContent content = new StringContent(JsonConvert.SerializeObject(sms), Encoding.UTF8, "application/json");
    HttpResponseMessage response = await client.PostAsync("batches", content);

    if (response.IsSuccessStatusCode)
    {
        Console.WriteLine("Sent");
    }
    else
    {
        Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }
}
                        
                    

Kodexemempel PHP

                          
$conf = array(
    'password' => 'API key',
    'apiUrl' => 'api.ip1sms.com/v2/',
    'method' => 'POST',
    'endpoint' => 'batches',
);

$message = array(
    "sender" => "iP1",
    "recipients" => ["46712345678"],
    "body" => "Test message rest v2",
    "type" => "sms",
    "datacoding" => "ucs",
    "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;
                        
                    

Kodexempel VB Script

                          
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", "Insert API Key Here")

Dim sms As New With
{
    Key .sender = "iP1sms",
    Key .recipients = New List(Of String)() From {"46712345678"},
    Key .body = "Test",
    Key .type = "sms",
    Key .datacoding = "ucs",
    Key .priority = 1
}

Dim content = New StringContent(JsonConvert.SerializeObject(sms), Encoding.UTF8, "application/json")
Dim response As HttpResponseMessage = Await client.PostAsync("batches", content)
                        
                    

Helpfull tools

iP.1 Utils

A nuget package with various tools. Contains, among other things, tools for formatting your mobile numbers and for calculating the number of SMS in a message.

iP.1 Utils
Is-Disposable Phone numbers

An NPM package with blacklist for disposable phonenumbers. Contains a blacklist with, among other things, one-time virtual numbers used in account registration.

Is-Disposable-Phonenumber

Introduktion SMPP

Protokoll
Kom igång

Vårt SMS API låter dig koppla upp dina webbtjänster och applikationer mot mobiloperatörer världen över och är designat för att hantera höga volymer av SMS-trafik och lämpar sig perfekt för bland annat större grupputskick vid exempelvis marknadsföring, men även singelutskick för automatiserade SMS-larm etc.

Skapa konto

För att komma igång behöver du först och främst ett konto, vilket du kan skapa här.

När du skapat ditt konto loggar du in i vår användarportal för att få tillgång till dina autentiseringsuppgifter, som beskrivs närmare i steget nedan.

API Endpoint

Bas-url:en för endpoints enligt API-referens i SMPP API:et är: https://api.ip1sms.com/v2/

Alla requester måste göras genom HTTPS.

Autentisering

Systemet är skyddat av autentisering med ditt kontonummer som System ID samt API-nyckel som lösenord. Varje konto du skapar kan ha flera nycklar med restriktion på IP-adress. Använd en nyckel som minst tillåter 10.0.0.0/8 för anslutning till SMPP systemet. API-nycklarna skapar och hanterar du i vår Användarportal.

1. Logga in i användarportalen med din iP.1-användare som skapades i samband med kontoregistrering.

2. gå till Konton (se bild)

3. tryck på överblick och gå till filken API-nycklar (se bild)

4. Klicka på Lägg till ny nyckel, ge nyckeln ett namn och sätt eventuell nätverksintervall om du vill begränsa nyckeln till ett specifikt IP-adress-spann. Slutför genom att trycka på skapa nyckel.

Paginering

Alla endpoints som returnerar en samling av dokument (Batcher, meddelanden etc.) har paginering aktiverat. Vi använder oss av databas-stilen av paginering med start, limit och order som parameternamn. start, limit och order är sätt till 0, 50 och ASC i respektive ordning, men du kan ändra dem genom att ange dem som query-parametrar när du gör ett HTTP-anrop på detta vis: ?start=0&limit=200&order=DESC

Du kommer också ta emot ett länk-huvud som innehåller paginerings-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"
                        
                    

Detta exempel innehåller radbryt för läsbarhetens skull.

Möjliga värden för rel är följande:

Namn Beskrivning
self Länkrelationen för den begärda resultatsidan.
first Länkrelationen för den första resultatsidan.
prev Länkrelationen för den omedelbart föregående resultatsidan.
next Länkrelationen för den omedelbart nästa resultatsidan.
last Länkrelationen för den sista resultatsidan.

Statuskoder


Sammanfattning

Nedan hittar du samtliga statuskoder för SMPP. Statuskoderna är uppdelade i 4 olika grupper:

Info

Informativa statusar som talar of vart SMS:et befinner sig innan det når mottagarens telefon.

Success

Talar om SMS:ets slutgiltiga status.

Rejection

Talar om ifall något i själva meddelandet är fel, exempelvis längden, spärrade nyckelord etc.

Error

Talar om ifall meddelandet är olevererbart eller andra tekniska fel.

Info
Name Code Group description
Accepted 101 Info Meddelandet har accepterats för behandling
Queued 102 Info Meddelandet har satts i kö för att skickas ut
Funded 103 Info Meddelandets kostnad har dragits från saldot och kan skickas ut.
Refunded 104 Info Meddelandets kostnad har återbetalats och lagts till på ditt saldo
Sending 110 Info Meddelandet skickas
DeliveredToGateway 111 Info Meddelandet har levererats till gateway
DeliveredToCarrier 112 Info Meddelandet har levererats till operatören där numret är registrerat
DeliveredToGSM 113 Info Meddelandet har skickats ut till GSM-nätverket
QueuedAtGateway 114 Info Meddelandet har lagts i kö i gateway
Success
Name Code Group description
DeliveredToHandset 201 Success Meddelandet har skickats till den aktuella mottagaren
Expired 202 Success Meddelandets utgångsdatum har paserat före meddelandet hann levereras
Canceled 203 Success Meddelandet avbröts av användaren
Rejection
Name Code Group description
InsufficientFunds 402 Rejection Kontot som försöker skicka har inte tillräckligt med saldo för att skicka SMS:et
SenderRejected 403 Rejection Avsändaren har blivit nekad, ges när avsändaren anses vara bedrägeri-klassad eller att ägarskapet av avsändaren inte har verifierats ordentligt
ContentRejected 404 Rejection Meddelandets innehåll är inte tillåtet hos den specifika operatören och/eller landet, exempelvis hassardspel, vuxet innehåll etc.
RecipientRejected 405 Rejection Mottagaren är ogiltig
GenericRejected 406 Rejection Meddelandet har avvisats av någon annan anledning än ovan nämnda.
InvalidSender 407 Rejection Meddelandets avsändare är ogiltig, exempelvis för lång, innehåller ogiltiga tecken etc.
InvalidContent 408 Rejection Meddelandets innehåll är ogiltigt, exempelvis ogiltiga tecken, för långt etc.
InvalidRecipient 409 Rejection Meddelandets mottagare är ogiltig, exempelvis att mottagaren inte är ett giltigt MSISDN
MissingSmsSubscription 410 Rejection Mottagaren har inte stöd för SMS och kan därför inte ta emot meddelandet.
Error
Name Code Group description
InternalError 500 Error Ett okänt fel inträffade
UnknownSubscriber 501 Error Nätverksabonnenten existerar inte
SubscriberUnreachable 502 Error Nätverksabonnenten var inte tillgänglig och kan därför inte ta emot meddelandet
SubscriberOffline 503 Error Abonnenten är tillfälligt offline, leverans kommer att försökas på nytt så fort abonnenten är tillgänglig
DeliveryToGatewayFailed 511 Error Meddelandet kunte inte lämnas över till nästkommande gateway
DeliveryToCarrierFailed 512 Error Meddelandet kunde inte lämnas över till operatören
DeliveryToGSMFailed 513 Error Meddelandet kunde inte läggas till på GSM-nätverket
DeliveryToHandsetFailed 514 Error Meddelandet kunde inte lämnas över till mottagarens telefon
GenericDeliveryFailure 515 Error Allmänt leveransfel
GatewayError 516 Error Ett okännt fel inträffade vid gateway
Unknown 599 Error Meddelandet levererades uppströms men inget leveranskvitto har mottagits eller ett leveranskvitto som inte kunde tolkas mottogs