SMS

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.

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;
                        
                    

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.

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

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
                        
                    

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

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
                        
                    

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

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.

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

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.

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
                        
                    

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
        }
    

link

The link to where the page can be viewed..

shortLink

A shorter link that redirects to link. This one is used in SMS campaigns.

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".

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.

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"
}
                  
              

previewLink

A URL to a preview image to be displayed when the video is not playing. Optionally, the default value is null .

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.

link

A URL to the linked content of the element. For videos and images, this is the video or image, and for buttons, it is the destination you reach when you click

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 .

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.

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

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.

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
                        
                    

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.

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

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.

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.

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.

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:

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.