iP.1's API allows you to connect your websites and applications to mobile operators across the world.
To use iP.1's API you need to register in our Web App in order to get your account setup.
After creating an account, log in to our User Portal to access your authentication credentials as explained below.
All endpoints are protected by authentication using HTTP Bearer tokens provided by us. Any account may have several API tokens with different restrictions on allowed IP-addresses etc. These can be accessed, created and edited in our User portal.
All endpoints which return a collection of documents (batches, messages etc.) have pagination turned on. We use the database style of pagination with start, limit and order as it's parameter names or offset, limit and order< by as they are called in MariaDB. By default the start, limit and order are set to 0, 50 and ASC respectively but you may change them to your liking by adding them as query parameters when making your HTTP request like this: ?start=0&limit=200&order=DESC
You'll also receive a Link header which includes pagination information.
Link: <https://api.ip1sms.com/v2/batches?start=201&limit=100&order=ASC> rel="next", <https://api.ip1sms.com/v2/batches?start=4901&limit=100&order=ASC> rel="last"
This example includes a line break for readability.
Possible rel values are:
Name | Description |
---|---|
self | The link relation for the requested page of results |
first | The link relation for the first page of results. |
prev | The link relation for the immediate previous page of results. |
next | The link relation for the immediate next page of results. |
last | The link relation for the last page of results. |
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.
Endpoint: GET me/senders
This endpoint will provide you with the documents of all registered senders in your account like the response data type below. Ordered alphabetically by sender.
Endpoint: PUT me/senders/{sender}
This endpoint allows you to register a new sender.
Endpoint: DELETE me/senders/{sender}
This endpoint allows you to unregister a previously registered sender.
{ "sender": "TestNOS", "created": "2018-10-23T17:43:19Z" }
You are also able to register or remove senders in our web application Capacity SMS.
You generate and handle your API KEYS for RESTful SMS API 1.0 in our User Portal
using (var client = new HttpClient())
{
client.BaseAddress = new Uri("https://api.ip1sms.com/v2/");
client.DefaultRequestHeaders.Accept.Clear();
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "API Key");
var sms = new OutgoingSMS()
{
"sender": "string",
"recipients": {"46712345678"},
"body": "string",
"type": sms,
"datacoding": gsm,
"priority": 1,
"reference": "Test",
"tags": [
"Test SMS"
]
};
HttpResponseMessage response = await client.PostAsJsonAsync("batches", sms);
if (response.IsSuccessStatusCode)
{
Console.WriteLine("Sent");
}
else
{
Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
}
}
$conf = array(
'password' => 'API key',
'apiUrl' => 'api.ip1sms.com/v2/',
'method' => 'POST',
'endpoint' => 'batches',
);
$message = array(
"sender" => "ip1sms",
"recipients" => ["46712345678"],
"body" => "Test message rest v2",
"type" => "sms",
"datacoding" => "gsm",
"priority" => 1,
"reference" => "Test",
"tags" => ["Test SMS"],
);
$jsonEncodedMessage = json_encode($message);
// Set up request options
$options = array(
'http' => array(
'header' => array(
'Content-Type: application/json',
'Authorization: Bearer '.$conf['password'],
'Content-Length: ' . strlen($jsonEncodedMessage)
),
'method' => $conf['method'],
'content' => $jsonEncodedMessage,
)
);
$url = "https://" . $conf['apiUrl'] . $conf['endpoint'];
$context = stream_context_create($options);
// Send the request
$response = file_get_contents($url, false, $context);
// Print the response
echo $response;
Dim account As String = "ip1-xxxxxx"
Dim password As String = "API-Key"
Dim client As New HttpClient()
client.BaseAddress = New Uri("https://api.ip1sms.com/v2/")
client.DefaultRequestHeaders.Accept.Clear()
client.DefaultRequestHeaders.Accept.Add(New MediaTypeWithQualityHeaderValue("application/json"))
client.DefaultRequestHeaders.Authorization = New AuthenticationHeaderValue("Bearer", "API Key")
Dim sms As New With
{
Key .sender = "iP1sms",
Key .recipients = New List(Of String)() From {"46712345678"},
Key .body = "Test",
key .type = "sms",
key .datacoding = "gsm",
key .priority = 1,
key .reference = "Test",
key .tags = "Test SMS"
}
Dim response As HttpResponseMessage = Await client.PostAsJsonAsync("batches", sms)
End Sub`;
Below you will find a list containing all available status codes for our RESTful SMS API 2.0. The codes are divided in three separate groups:
Informative statuses that informs where along the pipeline the message is.
If the message ended in a user defined way such as Expired or DeliveredToHandset.
If there is something wrong with the message it self such as length, banned keywords, etc.
If the message was undeliverable or other errors which is out of the control for the delivery service.
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 |
Name | Code | Group | description |
---|---|---|---|
DeliveredToHandset | 201 | Success | The message has been delivered to the recipient in question |
Expired | 202 | Success | The expiry date has been exceeded before the message could be delivered |
Canceled | 203 | Success | Message was canceled by user |
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 |
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 |
This is our modern RESTful API, easily accessible by any system that can make proper HTTP requests using json formatting. It gives you access to most of our services directly in your own applications with minimal work.
Basic use-cases include contact management, SMS message reminders, notifications and communication.
HTTP Basic Read more about HTTP Basic Authentication here
All API calls require authentication with your account credentials. We use HTTP Basic Authentication using your account ID and API key. These can be found by logging in to our user portal.
To get your Basic Authentication string, take your account ID (i. e. ip1-12345) and your API-key (i. e. cCnbXFfyTM5BTKh7uNV) and run them through a Base64 encoder in the following way: ip1-12345:CnbXFfyTM5BTKh7uNV
You should get at string that looks something like this: aXAxLTEyMzQ1OkNuYlhGZnlUTTVCVEtoN3VOVg==
This is your HTTP Basic Authentication string and should be given as an HTTP header in the following way:
Authorization: Basic aXAxLTEyMzQ1OkNuYlhGZnlUTTVCVEtoN3VOVg==
HTTP Bearer Read more about HTTP Bearer Authentication here
You can also authenticate your API calls using HTTP Bearer tokens provided by us. Any account may have several API tokens with different restrictions on allowed IP-addresses etc. These can be accessed, created and edited in our User portal.
For each request made, we recommend a maximum amount of 500 recipients / requests. For larger recipient lists, we recommend splitting the number of recipients into multiple requests with a maximum of 500 recipients in each.
The base for all URL is api.ip1sms.com and should be used with HTTPS as follows:
https://api.ip1sms.com
The rest of the URL is different for different calls, and that part is called the calls’ URI. Most URI points to an entity or a collection of entities that is the target of the call (i. e. api/contacts points to the collection of contacts). The HTTP verb distinguishes the operation to perform on the target (i.e. GET reads and POST creates).
The body of all requests and responses that passes data is json formatted with utf-8 encoding for highest compatibility with different clients. Only entity IDs are passed via the URI.
You generate and handle your API KEYS for RESTful SMS API 1.0 in our User Portal
using (var client = new HttpClient())
{
client.BaseAddress = new Uri("https://api.ip1sms.com/api/");
client.DefaultRequestHeaders.Accept.Clear();
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes(string.Format("{0}:{1}", "ip1-xxxxx", "API-Key"))));
var sms = new OutgoingSMS()
{
From = "iP1",
Numbers = new List() { "46123456789" },
Contacts = new List(),
Groups = new List(),
Message = "test",
Prio = 1,
Email = false
};
HttpResponseMessage response = await client.PostAsJsonAsync("sms/send", sms);
if (response.IsSuccessStatusCode)
{
Console.WriteLine("Sent");
}
else
{
Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
}
}
$conf = array(
'account' => 'ip1-xxxxx',
'password' => 'apiKey',
'apiUrl' => 'api.ip1sms.com',
'method' => 'POST',
'endpoint' => '/api/sms/send',
);
$message = array(
'Numbers' => ['4673055555'],
'From' => 'iP1',
'Message' => "Test message via iP.1's REST API",
);
$jsonEncodedMessage = json_encode($message);
// Set up request options
$options = array(
'http' => array(
'header' => array(
'Content-Type: application/json',
'Authorization: Basic '. base64_encode($conf['account'].":".$conf['password']),
'Content-Length: ' . strlen($jsonEncodedMessage)
),
'method' => $conf['method'],
'content' => $jsonEncodedMessage,
)
);
$url = "https://" . $conf['apiUrl'] . $conf['endpoint'];
$context = stream_context_create($options);
// Send the request
$response = file_get_contents($url, false, $context);
// Print the response
echo $response;
Here you will find everything you need to connect our RESTful Survey API to your system or application. With the help of a Survey API, you can easily customize your own automated customer surveys.
By connecting to 2FA for example for registering new accounts, you can easily ensure that the person has entered the correct information by confirming the user's telephone number. The code is sent as a text message to the specified number in no time.
When you integrate two-factor authentication via SMS from iP.1, you automatically gain access to our global spam filter list that includes thousands of virtual numbers used in malicious bot registrations.
Below you will find a list of status code for both HTTP Calls and SMS Status codes.
Code | Name | Description |
---|---|---|
200 | OK | Default success code, used for everything but entity creation |
201 | Created | Only used for successful entity creation, the Location header is used for pointing out the newly created entity |
400 | Bad Request | Used when the user specified data contains faults, the body may contain information about which data is invalid and why |
401 | Unauthorized | Used when authentication information is missing or invalid, or if the authenticated user lacks access to the API call used |
403 | Forbidden | Used when correctly authenticated but trying to access an entity or collection of entities that the user has no access to, the status description may contain a reason |
404 | Not Found | Used when trying to access an entity or collection of entities that do not exist, or if the URI is invalid |
405 | Method Not Allowed | Used when trying to use an HTTP verb that cannot be used on the given entity or collection of entities |
415 | Unsupported Media Type | Used when trying to send non JSON data or if the Content-Type header is missing |
500 | Internal Server Error | General error when something went wrong, if no other error is more appropriate, the response body may contain further details |
Code | Description |
---|---|
0 | Delivered to gateway |
1 | Gateway login failed |
2 | Invalid message content |
3 | Invalid phone number format |
4 | Insufficient funds |
10 | Received by the gateway |
11 | Delayed delivery |
12 | Delayed delivery cancelled |
21 | Delivered to the GSM network |
22 | Delivered to the phone |
30 | Insufficient funds |
41 | Invalid message content |
42 | Internal error |
43 | Delivery failed |
44 | Delivery failed |
45 | Invalid phone number |
50 | General delivery error |
51 | Delivery to GSM network failed |
52 | Delivery to phone failed |
100 | Insufficient credits |
101 | Wrong account credentials |
110 | Parameter error |
$conf['apiurl'] = 'https://web.smscom.se/sendsms/sendsms.asmx?wsdl';
$conf['mmsapiurl'] = 'https://web.smscom.se/mms/mms.asmx?wsdl';
$conf['account'] = 'ip1-xxxxx';
$conf['password'] = 'API-Key';
$conf['to'] = '46712345678';
$conf['from'] = 'iP1';
$conf['prio'] = '1';
$conf['msg'] = 'Test message via iP.1 API (Web Service)';
$conf['msg_at'] = "Test send at message via iP.1 API (Web Service)";
$conf['msg_bundle'] = "Test bundle message via iP.1 API (Web Service)";
$client = new SoapClient($conf['apiurl']);
$mmsClient = new SoapClient($conf['mmsapiurl']);
$result = $client->balans(array('konto'=>$conf['account'], 'passwd' => $conf['password']));
echo 'Balnace: ' . $result->balansResult;
$smsresult = $client->sms(array('konto'=>$conf['account'], 'passwd' => $conf['password'], 'till' => $conf['to'], 'from' => $conf['from'], 'meddelande' =>$conf['msg'], 'prio' => $conf['prio']));
echo 'Result of SMS: ' . $smsresult->smsResult;
Deprecated This API is deprecated and will no longer be further developed. We recommend that you use one of our REST APIs
For each request made, we recommend a maximum amount of 500 recipients / requests. For larger recipient lists, we recommend splitting the number of recipients into multiple requests with a maximum of 500 recipients in each.
Complete documentation
$conf['account'] = 'ip1-xxxx';
$conf['password'] = 'api-key';
$conf['apiurl'] = 'https://web.smscom.se/sendsms.aspx';
$conf['to'] = '4673055555';
$conf['from'] = 'iP1';
$conf['msg'] = 'Test message via iP.1 HTTP Request';
$conf['prio'] = '1';
$data = http_build_query(array('acc'=>$conf['account'],'pass'=>$conf['password'],'msg'=> $conf['msg'],'from'=>$conf['from'],'to'=> $conf['to'],'prio'=>$conf['prio'], 'type' => ''));
$opts = array('http' =>
array(
'method' => 'GET',
'header' => 'Content-type: application/x-www-form-urlencoded',
'content' => $data
)
);
$context = stream_context_create($opts);
$result = file_get_contents($conf['apiurl'] . '?' . $data, false, $context);
echo 'Result/SMS ID: ' . $result;
Deprecated This API is deprecated and will no longer be further developed. We recommend that you use one of our REST APIs
For each request made, we recommend a maximum amount of 500 recipients / requests. For larger recipient lists, we recommend splitting the number of recipients into multiple requests with a maximum of 500 recipients in each.
Complete documentation