IDM API Documentation

Introduction

API Root URL

https://api.i-digital-m.com/v2/

This is a documentation for the REST API of interactive digital media GmbH. To use this API you first have to register an account.

The IDM Rest API allows you to send SMS, monitor the state of already sent SMS and get certain information about your account such as your current balance.

Below you can see the resources that our API offers and example requests and responses.

Since the API follows the HATEOAS principle your can also just call the root URL and follow links to the different resources.

Getting Started

Basic Request Example

$ curl https://api.i-digital-m.com/v2/ \
    -H "Authorization: Basic dHN0dXNyOnRzdHB3"

Every API request requires atleast the Authorization HTTP header or the username/password query parameter.

Some functions of this API require certain HTTP headers set and different HTTP methods. Should your system not be able to set HTTP headers or make requests with different HTTP methods your can use special GET query parameters as replacement. The sections below will explain the details.

The request body is assumed to be UTF-8 in every request. Query parameters are expected to be URL encoded.

Authorization

Authorization Via Header

$ curl https://api.i-digital-m.com/v2/ \
    -H "Authorization: Basic dHN0dXNyOnRzdHB3" \
    -H "Accept: application/json"

Authorization Via Query

$ curl https://api.i-digital-m.com/v2/?username=tstusr&password=tstpw

HTTP basic auth is used as authorization method. You can get authorization for an API request via 2 ways, the Authorization HTTP header or the username/password query parameter. Whatever method of authorization you use, you have to send it with every request.

HTTP Methods

The API uses appropriate HTTP verbs for every action.

Method Description
GET Retrieve resources
POST Create new resources/Perform an action
PUT Update resources
DELETE Delete resources

For the majority of actions you do not have to call a new URL, you just have to use a different method. Should your system not be able to set different HTTP methods you have use the method query parameter instead, for example: method=POST.

Response

Request Example

$ curl https://api.i-digital-m.com/v2/ \
    -H "Authorization: Basic dHN0dXNyOnRzdHB3" \
    -H "Accept: application/json"
    

Response Structure Example

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "errors": [
        {
            "code": 404,
            "message": "Resource could not be found"
        }
    ],
    "status": 0,
    "links": {
        "documentation": {
            "href": "https://api.i-digital-m.com/v2/documentation",
            "method": "GET"
        },
        "sendSms": {
            "href": "https://api.i-digital-m.com/v2/sms",
            "method": "POST"
        },
        "account": {
            "href": "https://api.i-digital-m.com/v2/account",
            "method": "GET"
        }
    }
}

The response always has a basic structure additionally to the data of the actual response.

Default Response Fields

status
integer
0 = OK/1 = An error occurred. Use this field to easily check if the
action was successful independent of HTTP response status
errors
array
An array of objects describing all errors that occured during the request
code
integer
Error code. See Error Codes
message
string
Description of the error
links
object
Object containing links related to the current resource
href
string
The URL to the resource
method
string
Method that has to be used to request the resource

Format

The API can respond in multiple formats. You can specify the format you want in either the Accept HTTP header or in the accept query parameter. Below you can find a list of available formats. Both the query parameter and the HTTP header accept the short name and MIME version. The default format is json.

Short Name MIME
json application/json
xml application/xml
plain text/plain
html text/html

Date

The date format in responses is always YYYY-mm-dd HH:ii:ss in UTC.
For example: 2010-05-12 10:15:00.

Error Codes

Error Code Description
100 The requested API version does not exist
105 SMS message parameter is missing
106 SMS sender parameter is missing
107 SMS recipient parameter is missing
108 SMS recipient parameter too short
109 Message ID for sent SMS could not be retrieved
110 Invalid value for esmClass
111 Message invalid hex
113 Account has insufficient balance to execute the request
114 Your account is inactive
116 2FA recipient parameter missing
117 2FA message parameter too long
118 Generic SMS sending failed
119 2FA code parameter missing
120 Lookup MSISDN invalid
121 Lookup generic error
123 SMS recipient parameter invalid
125 Invalid lookup type
126 ProtocolId invalid
127 Invalid encoding
400 Bad request
401 Unauthorized
403 Given credentials are invalid
404 Requested resource not found
405 Used HTTP method is now allowed
406 Requested response format is invalid
429 Too many requests
440 Ip whitlist validation failed
500 Internal server error. Try again later
503 Service currently unavailable. Try again later

Rate Limit

Some resources have a limit on how often you can request them. Which resources are affected can be seen in their according sections of the documentation.

Resources that have a request limit always send 3 headers with every response: X-RateLimit-Reset, X-RateLimit-Remaining, X-RateLimit-Limit.

Field Description
X-RateLimit-Reset Unix timestamp (UTC) when the request count gets reset
X-RateLimit-Remaining Amount of requests remaining in current timeframe
X-RateLimit-Limit Max amount of requests that can be made in current timeframe

SMS

The IDM API allows you to send SMS and check on their status.

Send SMS

POST /sms

Send SMS Example

$ curl https://api.i-digital-m.com/v2/sms \
    -X POST \
    -H "Authorization: Basic dHN0dXNyOnRzdHB3" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
        "sender": "4915123456789",
        "recipient": "4915987654321",
        "message": "API Test Message",
        "dlr": 1
    }' 

Send Hex SMS Example

$ curl https://api.i-digital-m.com/v2/sms \
    -X POST \
    -H "Authorization: Basic dHN0dXNyOnRzdHB3" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
        "sender": "4915123456789",
        "recipient": "4915987654321",
        "message": "4150492054657374204d657373616765",
        "dlr": 1,
        "hex": 1
    }' 

Send SMS Via Query

$ curl "https://api.i-digital-m.com/v2/sms\
?method=POST\
&accept=json\
&username=tstusr\
&password=tstpass\
&sender=4915123456789\
&recipient=4915987654321\
&message=API Test Message\
&dlr=1"

Response Example

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8

{
    "messageId": "43a95b49982df502",
    "errors": [],
    "status": 0,
    "links": {
        "smsStatus": {
            "href": "https://api.i-digital-m.com/v2/sms/43a95b49982df502",
            "method": "GET"
        } 
    }
}

Send a SMS.

Request Arguments

sender
stringrequired
Sender ID of the SMS
recipient
stringrequired
Recipient number of the SMS
message
stringrequired
Message of the SMS
hex
booleanoptional
Set to 1 if the content of the message is a hex string
dlr
booleanoptional
Set to 1 if you want to receive a DLR for this SMS
srcEnc
stringoptional
Source encoding of the message. Defaults to utf8. Please see encodings section for valid values and explanation
dstEnc
stringoptional
Destination encoding of the message. Defaults to auto. Please see encodings section for valid values and explanation
dcs
integeroptional
Data coding of the message. Only for expert users
flash
booleanoptional
Send as flash SMS
protocolId
integeroptional
Protocol Id, value 0 - 255

Response

messageId
string
ID that can be used to identify the SMS in other requests

Retrieve SMS status

GET /sms/{messageId}

Request Example

$ curl https://api.i-digital-m.com/v2/sms/43a95b49982df502 \
    -H "Authorization: Basic dHN0dXNyOnRzdHB3" \
    -H "Accept: application/json"  

Response Example

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF=8

{
    "sms": {
        "messageId": "43a95b49982df502",
        "addedDate": "2015-03-05 10:00:00",
        "sender": "4915123456789",
        "recipient": "4915987654321",
        "status": "DELIVRD" 
    },
    "status": 0,
    "errors": [],
    "links": []
}

Retrieve status details about a SMS.

Request Arguments

messageId
stringrequired
ID of the SMS

Response

sms
object
Object containing the attributes of the SMS
messageId
string
ID of the SMS
status
string
Current status of the SMS. See SMS Status
sender
string
Sender of the SMS
recipient
string
Recipient of the SMS
addedDate
string
Datetime the SMS has been added

SMS Status

See below the status an SMS can have.

Status Description
ENROUTE Message is enroute
DELIVRD Message was successfully delivered
EXPIRED SMSC was unable to deliver the message in time (in case of a turned off phone for example)
DELETED Message was deleted
UNDELIV Message could not be delivered (in case of non-existing number for example)
ACCEPTD Message accepted for sending
UNKNOWN Unknown error occured
REJECTD Message was rejected (because the provider blocked the phone numbers range for example)

SMS Encoding

Every SMS has a source -and destination encoding. The source encoding specifies how the message is encoded when it is sent to our API. The destination encoding specifies how the message should be sent out. We take care of converting it ourselves.

When sending an SMS you can specify the source/destination encodings via the parameters srcEnc (source encoding) and dstEnc (destination encoding). srcEnc defaults to utf8 and dstEnc defaults to auto.

For example: Your message text is encoded as utf8 and you know that the text might contain unicode characters. You can now either set dstEnc to auto to let us figure out what destination encoding is appropriate or you can set it to ucs2 to always send it as unicode.

Please see the tables below for valid source/destination encodings.

Source Encodings

Name Aliases Info
utf8 Default when no source encoding is specified
gsm gsm0338, plain
latin1 iso-8859-1
latin9 iso-8859-15 Same as latin1, except it contains the euro sign
ucs2 unicode, ucs-2be

Destination Encodings

Name Aliases Info
auto Auto detects the destination encoding. If the message contains any unicode characters the destination encoding gets set to ucs2, otherwise gsm. Default when no destination encoding specified
gsm gsm0338, plain See wiki table for supported characters
ucs2 unicode, ucs-2be Use if the message contains any unicode characters

Encoding

List Encodings

GET /encoding

Request Example

$ curl https://api.i-digital-m.com/v2/encoding
    -H "Authorization: Basic dHN0dXNyOnRzdHB3" \
    -H "Accept: application/json"

Response Example

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "encodings": [
        "gsm",
        "latin1",
        "latin9",
        "ucs2",
        "utf8"
    ],
    "errors": [],
    "status": 0,
    "links": {
        "convertEncoding": {
            "href": "https://api.i-digital-m.com/v2/encoding/convert",
            "method": "GET"
        }
    }
}

List the available encodings.

Response

encodings
array
The available encodings

Convert Encoding

GET /encoding/convert

Request Example

$ curl https://api.i-digital-m.com/v2/encoding/convert?message=testmessage&srcEnc=utf8&dstEnc=ucs2 \
    -X GET \
    -H "Authorization: Basic dHN0dXNyOnRzdHB3" \
    -H "Accept: application/json" 

Response Example

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "original": {
        "hex": "746573746d657373616765",
        "encoding": "utf8"
    },
    "converted": {
        "hex": "0074006500730074006d006500730073006100670065",
        "encoding": "ucs2"
    },
    "errors": [],
    "status": 0,
    "links": []
}

Convert the encoding of a message.

Request Arguments

message
stringrequired
The message to encode
srcEnc
stringrequired
The source encoding of the message parameter as it is sent to the API
dstEnc
stringrequired
The destination encoding that the message parameter should be encoded to. Use auto to auto detect the minimal necessary encoding
hex
booleanoptional
Specifies if the message parameter is a hex string

Response

original
object
Contains information about the original message
hex
string
Original message in hex representation
encoding
string
Original message encoding
converted
object
Contains information about the converted message
hex
string
Converted message in hex representation
encoding
string
Converted message encoding

Lookup

Our lookup service allows you to perform mobile number lookups to find out which operator the number belongs to. The actual output of the request depends on the type your are using. Each type is locked by default and has to be enabled by your account manager.

List Types

GET /lookup

Request Example

$ curl https://api.i-digital-m.com/v2/lookup
    -H "Authorization: Basic dHN0dXNyOnRzdHB3" \
    -H "Accept: application/json"

Response Example

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "types": [
        "mnp"
    ],
    "errors": [],
    "status": 0,
    "links": {
        "lookup": {
            "href": "https://api.i-digital-m.com/v2/lookup/{type}/{msisdn}",
            "method": "GET"
        },
        "mnp": {
            "href": "https://api.i-digital-m.com/v2/lookup/mnp/{msisdn}",
            "method": "GET"
        }
    }
}

List the currently available types. Each type responds with a different set of lookup info. Please note that every type has to be enabled for your account by your account manager.

Currently available types:

  • mnp
  • mnp_plus

Response

types
array
Available types

Perform Lookup

GET /lookup/{type}/{msisdn}

Request Example

$ curl https://api.i-digital-m.com/v2/lookup/mnp/49151123456789
    -H "Authorization: Basic dHN0dXNyOnRzdHB3" \
    -H "Accept: application/json"

Response Example

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "lookup": {
        "msisdn": "49151274634",
        "countryName": "Germany",
        "countryIso2": "DE",
        "countryIso3": "DEU",
        "countryPrefix": "49",
        "realMcc": "262",
        "realMnc": "01",
        "realOperatorName": "T-mobile\/Telekom (Germany)",
        "prefixMcc": "262",
        "prefixMnc": "01",
        "prefixOperatorName": "T-mobile\/Telekom (Germany)",
        "ported": 0,
        "subscriberStatus": ""
    },
    "errors": [],
    "status": 0,
    "links": []
}

Perform a lookup and retrieve info about the given number.

Request Arguments

msisdn
stringrequired
Number to lookup
type
string
Lookup type. This decides what info will be in the response.

Response

lookup
object
Object containing the lookup result
Available by type
msisdn
string
The looked up number
all
countryName
string
Country name of location of msisdn
all
countryIso2
string
ISO2 of country
all
countryIso3
string
ISO3 of country
all
countryPrefix
string
MSISDN prefix of country
all
realMcc
string
Real MCC by lookup
all
realMnc
string
Real MNC by lookup
all
realOperatorName
string
Real operator name by lookup
all
prefixMcc
string
MCC by prefix
all
prefixMnc
string
MNC by prefix
all
prefixOperatorName
string
Operator name by prefix
all
ported
string
1 = number is ported, 0 = number is not ported
all
subscriberStatus
string
Subscriber information. unknown, absent, or empty
mnp_plus

2 Factor Authentication

2 Factor Authentication enables you to send short codes via SMS to your own customers and users which can be used as an additional step in your authentication process.

Create 2FA

POST /2fa

Request Example

$ curl https://api.i-digital-m.com/v2/2fa \
    -X POST \
    -H "Authorization: Basic dHN0dXNyOnRzdHB3" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
        "recipient": "49151123456789",
        "sender": "75836582",
        "message": "Your code {code}"
    }' 
    
HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8

{
    "token": "9fd81d2df437068a0be4",
    "errors": [],
    "status": 0,
    "links": {
        "check2Fa": {
            "href": "http:\/\/api.i-digital-m.com\/v1\/2fa\/{token}",
            "method": "GET"
        },
        "self": {
            "href": "http:\/\/api.i-digital-m.com\/v1\/2fa\/9fd81d2df437068a0be4",
            "method": "GET"
        }
    }
}
        

Create and send a 2FA SMS to a number.

Request Arguments

recipient
stringrequired
Number the code should be sent to
sender
stringoptional
Sender ID shown on the recipient side
message
stringoptional
Custom message. Use {code} placeholder to put the code into your message
flash
booleanoptional
Send as flash SMS

Response

token
string
Token to identify the 2Fa SMS later on

Custom Message

Instead of using the short default message you can customize the message that gets sent to your user.

To put the code in the message you can use the {code} placeholder.

Example: You just tried to log in. Here is your code: {code}.

This would result in a message like this: You just tried to log in. Here is your code: 12345.

Check 2FA

GET /2fa/{token}

Request Example

$ curl https://api.i-digital-m.com/v2/2fa/9fd81d2df437068a0be4?code=12345
    -H "Accept: application/json

Response Example

HTTP/1.1 OK 200
Content-Type: application/json;charset=UTF-8

{
    "valid": 0,
    "errors": [],
    "links": {},
    "status": 0
}

Once you have sent out a 2Fa SMS and your user received the code and typed it into your own login form you have to check if the code your user has typed in is correct. For this you have to send us the token that you got from sending the 2Fa SMS and the code your user typed in.

Request Arguments

token
stringrequired
The token you got from sending a 2FA SMS
code
stringrequired
The code to check for validity

Response

valid
boolean
1 if the code if correct, otherwise 0

Account

Retrieve Account Details

GET /account

Request Example

$ curl https://api.i-digital-m.com/v2/account \
    -H "Authorization: Basic dHN0dXNyOnRzdHB3" \
    -H "Accept: application/json"  

Response Example

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "account": {
        "username": "tstusr",
        "name": "Test Company Name",
        "street": "Test Company Street",
        "postal": "123456",
        "city": "Test City",
        "country": "France",
        "compRegNo": "267934276",
        "vatIdNo": "FRAB1234567891",
        "billEmail": "idm-test-company@gmail.com"
    },
    "errors": [],
    "status": 0,
    "links": {
        "getBalance": {
            "href": "https://api.i-digital-m.com/v2/account/balance",
            "method": "GET"
        },
        "getCredits": {
            "href": "https://api.i-digital-m.com/v2/account/credits",
            "method": "GET"
        }
    }
}

Retrieve details about the currently used account.

Response

account
object
Object containing the details of your account
username
string
Name of currently used account
name
string
Company name
street
string
Company street name
postal
string
Company postal
city
string
Company city
country
string
Company country
compRegNo
string
Company registration number
vatIdNo
string
Company VAT identification number
billEmail
string
Company bill email

Retrieve Account Balance

GET /account/balance

Request Example

$ curl https://api.i-digital-m.com/v2/account/balance
    -H "Accept: application/json"

Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "balance": 200.50,
    "errors": [],
    "links": {},
    "status": 0
}

Response

balance
float
Your account balance

Retrieve Account Credits

GET /account/credits

Request Example

$ curl https://api.i-digital-m.com/v2/account/credits
    -H "Accept: application/json"

Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "credits": 20,
    "errors": [],
    "links": {},
    "status": 0
}

Response

credits
integer
Your account credits

Migration Guides

This section tells you how you can migrate from older versions of the API to newer ones.

SMSC API To REST API

There are major differences between the SMSC API and the REST API. You will have to change all URLs, parameter and possibly the way you execute the request.

While the REST API can make use of HTTP methods and headers this migration guide will only use the GET parameter version of every request to minimize the changes that have to be made.

Lookup

SMSC API Requests

http://smsc.i-digital-m.com/services/enum/mnp_de.php?msisdn=4915128348451&username=apiuser&password=apipass
http://smsc.i-digital-m.com/services/enum/profile_1.php?msisdn=4915128348451&username=apiuser&password=apipass
http://smsc.i-digital-m.com/services/enum/profile_2.php?msisdn=4915128348451&username=apiuser&password=apipass

REST API Request

https://api.i-digital-m.com/v2/lookup/mnp/4915128348451?username=apiuser&password=apipass&accept=json

SMSC API Responses

MNP DE: 4915128348451;262;1
Profile 1: 4915128348451;Germany;T-mobile/Telekom (Germany);262;1;T-mobile/Telekom (Germany);262;1;0;-1;-1;-1;1;;
Profile 2: 4915128348451;Germany;T-mobile/Telekom (Germany);262;01;T-mobile/Telekom (Germany);262;01;0;0;;;1;

REST Response

{
    "lookup": {
        "msisdn": "4915128348451",
        "countryName": "Germany",
        "countryIso2": "DE",
        "countryIso3": "DEU",
        "countryPrefix": "49",
        "realMcc": "262",
        "realMnc": "01",
        "realOperatorName": "T-mobile\/Telekom (Germany)",
        "prefixMcc": "262",
        "prefixMnc": "01",
        "prefixOperatorName": "T-mobile\/Telekom (Germany)",
        "ported": 0
    },
    "errors": [],
    "status": 0,
    "links": []
}

REST API PHP Code Example

<?php
$msisdn = "4915128348451";
$url = "https://api.i-digital-m.com/v2/lookup/mnp/" . $msisdn . "?";
$url .= http_build_query([
	"username" => "apiuser",
	"password" => "apipass",
	"accept" => "json"
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$response = json_decode($response);
if ($response->status != 0) {
	foreach($response->errors as $error) {
		echo $error->message . PHP_EOL;
	}
	exit();
}

echo "Prefix Operator Name: " . $response->lookup->prefixOperatorName . PHP_EOL;
echo "Real Operator Name: " . $response->lookup->realOperatorName . PHP_EOL;
?>

Profile 1, Profile 2 and MNP DE got merged into one URL, in the REST API there is now no difference between those three requests.

Request

The msisdn in the REST API is part of the URL path and not a GET parameter anymore and the response accept has to be specified while the username/password GET parameters stay the same.

Response

The REST API has a variable response format (like JSON or XML) that can be defined via the accept GET parameter. The old CSV format is not available anymore. No matter what SMSC API URL you used before, or what response format you choose, the scheme always stays the same.

A lookup request in the REST API is successfull when the status fields equals 0.

SMS

SendHex, SendSMS and SendTimeshift have been merged into one URL.

SMSC API Requests

http://smsc.i-digital-m.com/smsgw/sendsms.php?user=apiuser&password=apipass&sender=49151736374673&recipients=4915128348451&dlr=1&message=Test
http://smsc.i-digital-m.com/smsgw/sendhex.php?user=apiuser&password=apipass&sender=49151736374673&recipients=4915128348451&dlr=1&message=54657374&dcs=0
http://smsc.i-digital-m.com/smsgw/send_timeshift.php?user=apiuser&password=apipass&sender=49151736374673&recipients=4915128348451&dlr=1&message=Test&delivery_date=2020-10-10+00:00:00

REST API Requests

SendSMS: https://api.i-digital-m.com/v2/sms?method=POST&username=apiuser&password=apipass&sender=49151736374673&recipient=4915128348451&dlr=1&message=Test&accept=json
SendHex: https://api.i-digital-m.com/v2/sms?method=POST&username=apiuser&password=apipass&sender=49151736374673&recipient=4915128348451&dlr=1&hex=1&message=54657374&accept=json&dcs=0
SendUnicode: https://api.i-digital-m.com/v2/sms?method=POST&username=apiuser&password=apipass&sender=49151736374673&recipient=4915128348451&dlr=1&hex=1&message=0053006D0069006C0065003A0020D83DDE0000200054007200610069006E003A0020D83DDE84&accept=json&dcs=8
SendTimeshift: https://api.i-digital-m.com/v2/sms?method=POST&username=apiuser&password=apipass&sender=49151736374673&recipient=4915128348451&dlr=1&message=Test&deliveryDate=2020-10-10+00:00:00&accept=json

Request

The different functionalities of the SMSC URLs are mapped to different GET parameters on the same URL. Here are the primary changes:

  • Every request has to contain the method=POST parameter
  • To always reliably get the same response format, every request has to contain the accept header. The easiest to parse format is json
  • The message field has to be UTF-8
  • The parameter containing the recipient has been renamed to recipient (singular) and can now only contain one number
  • To send hex messages you have to set the hex parameter to 1
  • To send timeshifted messages you have to set the deliveryDate parameter
  • The prt parameter for the protocol id has been renamed to protocolId

SMSC API Response

4915128348451 43a95b49982df502 +OK

REST API Response

{
    "messageId": "43a95b49982df502",
    "errors": [],
    "status": 0,
    "links": {
        "smsStatus": {
            "href": "http://api.i-digital-m.com/vdev/sms/43a95b49982df502",
            "method": "GET"
        } 
    }
}

REST API PHP Code Example

<?php
$url = "https://api.i-digital-m.com/v2/sms?";
$url .= http_build_query([
	"username" => "apiuser",
	"password" => "apipass",
	"accept" => "json",
	"method" => "POST",
	"sender" => "49151736374673",
	"recipient" => "4915128348451",
	"message" => "Test",
	"dlr" => 1
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$response = json_decode($response);
if ($response->status != 0) {
	foreach($response->errors as $error) {
		echo $error->message . PHP_EOL;
	}
	exit();
}

echo "Message Id: " . $response->messageId . PHP_EOL;
?>

Response

The response format depends on the accept parameter in the request. No matter the choosen format, the response scheme always stays the same. The message id can now be fetched from the messageId field.

Balance

You can also request your current company balance via the REST API.

SMSC API Request

http://smsc.i-digital-m.com/clients/balance.php?username=apiuser&password=apipass

REST API Request

https://api.i-digital-m.com/v2/account/balance?username=apiuser&password=apipass&accept=plain

Request

The accept parameter has to be specified. The format plain can be used to get only the balance in the response body. The username and password parameters stay.

SMSC API Response

120.1

REST API Response

120.1

Response

When using the format plain the response body will only contain the balance amount. When using other formats the balance will be contained in the balance field.

Support

Have questions about our API? Found bugs in the API or incomplete/wrong entries in the documentation? Please tell us:

Code Samples

The following section provides some code examples to use this API. The samples provide only basic requests with no special parameters / settings. Use this saples as Template to create your own source code.

PHP

PHP send SMS


<?php
// Target url use Version v1 to send the SMS
$url = 'https://api.i-digital-m.com/v1/sms';

$username = 'PLACEHOLDER-USERNAME'; //TODO: insert your username here 
$password = 'PLACEHOLDER-PASSWORD'; //TODO: insert your password here 

$sender = 'PLACEHOLDER-SENDER'; //TODO: insert your source here for example your own phone number or company name
$recipient = 'PLACEHOLDER-DESTINATION'; //TODO: insert the destination number here like 49152123456789
$message = 'PLACEHOLDER-MESSAGE'; //TODO: insert SMS message here for example Special sale 50% off for everything  


 /*
 * prepare the POST request in two steps:
 * 1. prepare the POST body 
 * 2. prepare the POST header informations
 */

// generate request Body for POST request
$postParams = array(
	'sender' => $sender, 
	'recipient' => $recipient,
	'message' => $message,
	'dlr' => '0',
);
$postJson = json_encode($postParams);


// generate request header
$credentials = base64_encode($username.':'.$password);
$headers = array(
	"Authorization: Basic " .$credentials,
	"Accept: application/json",
	"Content-Type: application/json",
	"Content-Length: " . strlen($postJson)
);


// send the POST request using PHP curl 
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); 
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postJson);
$response = curl_exec($ch);


// evaluate the response
if($response === false){
	// print out the error if the request fails
	var_dump(curl_error($ch));
}else{
	// print out the response 
	var_dump($response);
}

?>

The script on the right will send a SMS. You need to replace the PLACEHOLDER-XYZ on the top of the sample with your data. The Request is based on PHP curl and uses json formatted content.

The sample creates only a basic request with no special attributes like srcEnc or dstEnc.

Also the response is simply printed out using var_dump.

Java

Java send SMS


import org.apache.http.HttpResponse;
import org.apache.http.client.fluent.Form;
import org.apache.http.client.fluent.Request;

import java.io.IOException;
import java.util.Base64;

public class HttpPostRequest {
	
	/**
	 * The URL to send the request to.
	 */
	private static final String URL = "https://api.i-digital-m.com/v1/sms";
	
	/**
	 * The user name to authenticate with.
	 */
	private static final String USERNAME = "PLACEHOLDER-USERNAME";
	
	/**
	 * The password to authenticate with.
	 */
	private static final String PASSWORD = "PLACEHOLDER-PASSWORD";
	
	/**
	 * Password and user name need to be base64 encoded.
	 */
	private static final String AUTHENTICATION_STRING = Base64.getEncoder().encodeToString((USERNAME + ":" + PASSWORD).getBytes());
	
	/**
	 * Executes a POST request.
	 *
	 * @param sender    the message sender
	 * @param recipient the message recipient
	 * @param message   the message text
	 * @return the response
	 * @throws IOException if the execution fails
	 */
	public HttpResponse post(String sender, String recipient, String message) throws IOException {
		// create a POST request
		return Request.Post(URL)
				// add the needed headers
				.addHeader("Authorization", "Basic " + AUTHENTICATION_STRING)
				.addHeader("Accept", "application/json")
				.addHeader("Content-Type", "application/x-www-form-urlencoded")
				// add the parameters
				.bodyForm(Form.form()
						.add("sender", sender)
						.add("recipient", recipient)
						.add("message", message)
						.add("dlr", "0")
						.build())
				// execute the request
				.execute()
				// return the response
				.returnResponse();
	}
	
	public static void main(String[] args) throws IOException {
		// perform a request
		HttpResponse response = new HttpPostRequest().post("PLACEHOLDER-SENDER", "PLACEHOLDER-RECIPIENT", "PLACEHOLDER-MESSAGE");
		// print response headers to console
		System.out.println(response);
		// print response body to console
		response.getEntity().writeTo(System.out);
	}
}

The Java class to the right will do a POST request to send a SMS. Everything named "PLACEHOLDER-xxx" needs to be replaced by the correct data.

The example uses the Apache HTTP client and its fluent API. Both is composed in the (Maven) dependency below and needed to run the example. org.apache.httpcomponents fluent-hc 4.5.6

Python

Python send SMS


# import the requests and base64 module
import requests
import base64

# set the URL and other parameters
url = "https://api.i-digital-m.com/v1/sms"
authentication_params = base64.b64encode(b'PLACEHOLDER-USERNAME:PLACEHOLDER-PASSWORD').decode()
headers = {'Authorization':'Basic ' + authentication_params, 'Accept': 'application/json', 'Content-Type':'application/x-www-form-urlencoded'}
data = {'sender':'PLACEHOLDER-SENDER', 'recipient':'PLACEHOLDER-RECIPIENT', 'message':'PLACEHOLDER-MESSAGE'}

# do the request
response = requests.post(url, data=data, headers=headers)

# print response
print(r.status_code, r.reason)
print(r.text)

The script to the right will make a POST request to send a SMS. The "PLACEHOLDER"s need to be replaced by the actual data.