You login with the password and obtain an API key that you use for further communication with the API.
This only needs to be done once. When calling the API further on use the generated key.
$ /user/newapikey/login.json?user=username&pass=password&description=YourAPP
{
"status": "success",
"success": "ADDED_KEY",
"newapikey": {
"controlapikey": 0,
"key": "dcHZ2TXvMV"
}
}
In case the user has two-factor-authentication activated, which will send a code to the users phone, you will get this response:
{
"status": "success",
"success": "ADDED_TF"
}
You provide a screen that takes the users code and make a new request:
$ /user/newapikey/login.json?user=username&pass=password&description=YourAPP&tfkey=1234
{
"status": "success",
"success": "ADDED_KEY",
"newapikey": {
"controlapikey": 0,
"key": "NGsfRk97bL"
}
}
If something is wrong with username, password or tfkey the response will be:
{
"status": "error",
"error": "USER_NOT_FOUND",
"login": {
"user": "username",
"pass": "password"
}
}
You have to append your username and key to every query you are making. Here is an example of querying your personal information:
$ /view/user/api.json?user=username&key=key
user
The provided username
key
The provided key.
Can be generated automatically using ‘Login’.
format
Change output format by switching file suffix. Fx. api.[json, xml]
When you logout of your app, webapplication or whatever you have, you can delete the key again.
$ /user/deleteapikey/api.json?user=username&key=key&apikey=key
{
"status": "success",
"success": "DELETE_APIKEY"
}
You can request the users personal information.
$ /view/user/api.json
{
"status": "success",
"success": "VIEW_USER",
"user": {
"controluser": 0,
"username": "username",
"status": 10,
"companyname": "Company",
"companyid": 00000000,
"eannumber": null,
"fullname": "Fullname",
"street": "Street",
"zipcode": 5550,
"msisdn": 4512345678,
"dialcode": 45,
"number": 12345678,
"email": "[email protected]",
"lockedname": null,
"createdtime": 1361830863,
"iplast_login": "127.0.0.1",
"iplast_gw": "127.0.0.1",
"timestamp_login": 1394326632,
"timestamp_gw": 1393975152,
"callback": "http://provider.dk/ka/",
"bcontactid": null
}
}
This is an example of your outbox. Your messages will be in 'outbox' and easy to iterate.
$ /view/outbox/api.json
{
"status": "success",
"success": "VIEW_OUTBOX",
"outbox": [
{
"smsid": 0,
"controluser": 0,
"username": "username",
"msisdn": 4512345678,
"dialcode": 45,
"number": 12345678,
"sender": "You",
"sent": 1394367850,
"received": 1394367851,
"scheduled": 0,
"price": 0.2,
"failed": true,
"error": 13,
"premium": 0,
"flash": false,
"wappush": null,
"text": "This text is on the way to you!",
"networkcode": null,
"msg-count": 1,
"premium-out": 0,
"latency": 1000,
"errortext": "Message terminated."
},
...
]
}
search
Search parameter
This is an example of your inbox. Your messages will be in 'inbox' and easy to iterate.
$ /view/inbox/api.json
{
"status": "success",
"success": "VIEW_INBOX",
"inbox": [
{
"smsid": 0,
"controluser": 0,
"username": "username",
"msisdn": 4512345678,
"dialcode": 45,
"number": 12345678,
"received": 1393799104,
"keyword": "gateway",
"gateway": 1919,
"network": "dk.telia",
"text": "hey",
"msg-count": 1,
"contact": {
"controlcontact": 0,
"fullname": "Fullname of contactperson"
}
},
...
]
}
search
Search parameter
If no errors occurred, the response will be:
$ /sms/api.json?msisdn=4512345678&sender=You&text=This+text+is+on+the+way+to+you%21
{
"status": "success",
"success": "SMS_SENT",
"sms": {
"smsid": 0,
"cost": 0.2,
"chars-count": 31,
"msg-count": 1
}
}
Should an error occur, you can typically find the reason in 'error':
{
"status": "error",
"error": "EMPTY_RECIPIENT",
"sms": {
"msisdn": null
}
}
msisdn
The recipient. Mobile number in international format e.g. 4512345678
text
The SMS content. UTF-8 and URL encoded value.
sender
Allowed characters are a-zA-Z0-9.
Max 15 numeric or max 11 alphanumeric.
contact
The contact ID - msisdn, group will be ignored.
group
The group ID - msisdn, contact will be ignored.
flash
Set to ‘true’ if you want to send the SMS as a flash.
Please note that not all phone or networks supports this.
silent
Set to ‘true’ if you want to send the SMS silently.
Please note that not all phone or networks supports this.
wappush
Provide the URL that you want to push to the phone.
Please note that not all phone or networks supports this.
schedule
Schedule a message for later sending. The format is Unix timestamp (Timezone: Europe/Copenhagen).
callback
Set an optional callback URL. This will not disable nor replace the user account specified callback.
price
Set the price. Defined in øre, e.g. 1 Danish krone = 100.
If no errors occurred, the response will be:
$ /hlr/api.json?msisdn=4512345678
{
"status": "success",
"success": "LOOKUP",
"hlr": {
"msisdn": 4512345678,
"stat": "DELIVRD",
"imsi": 000000000000000,
"mccmnc": 23820,
"err": 0,
"latest_lookup": 1394370505,
"original_dialcode": 45,
"original_country_name": "Denmark",
"original_network_name": "MVNO - BiBoB",
"original_number_prefix": 4242,
"ported_dialcode": 45,
"ported_country": "Denmark",
"ported_network_name": "Telia DK",
"ported_network_code": 23820,
"ported_number_prefix": 4211
}
}
Should an error occur, you can typically find the reason in 'error':
{
"status": "error",
"error": "EMPTY_RECIPIENT",
"hlr": {
"msisdn": null
}
}
msisdn
The recipient. Mobile number in international format fx. 4512345678
contact
The contact ID - msisdn, group will be ignored.
group
The group ID - msisdn, contact will be ignored.
roaming
Set to ‘true’ if you want to check roaming informations.
You can in one request get your prices for specific countries, balance and subscriptions.
$ /view/yourprices/api.json
{
"status": "success",
"success": "VIEW_YOURPRICES",
"yourprices": {
"prices": [
{
"country": "Denmark",
"dialcode": 45,
"price": {
"sms": 0.2,
"hlr": 0.08
}
},
{
"country": "Norway",
"dialcode": 47,
"price": {
"sms": 0.2,
"hlr": 0.08
}
},
{
"country": "Sweden",
"dialcode": 46,
"price": {
"sms": 0.2,
"hlr": 0.08
}
},
{
"country": "United Kingdom",
"dialcode": 44,
"price": {
"sms": 0.55,
"hlr": 0.08
}
},
...
{
"country": "Other countries",
"dialcode": 0,
"price": {
"sms": 0.6,
"hlr": 0.08
}
}
],
"credit": {
"balance": 95.96,
"timestamp": 1394399372
},
"subscription": {
"keywords": [
{
"gateway": 1919,
"keyword": "keyword",
"price": 120,
"shutdown": 0,
"paiduntil": 0
},
...
]
}
}
}
It's easy to get a list of all your contacts.
$ /view/contacts/api.json
{
"status": "success",
"success": "VIEW_CONTACTS",
"contacts": [
{
"birthday": null,
"controlcontact": 100,
"dialcode": 45,
"email": null,
"fullname": "Fullname",
"groups": null,
"msisdn": 4512345678,
"number": 12345678,
"sex": null,
"street": null,
"zipcode": null
},
...
]
}
Get one contact:
$ /view/contact/api.json?contact=100
{
"status": "success",
"success": "VIEW_CONTACT",
"contact": {
"birthday": null,
"controlcontact": 100,
"dialcode": 45,
"email": null,
"fullname": "Fullname",
"groups": null,
"msisdn": 4512345678,
"number": 12345678,
"sex": null,
"street": null,
"zipcode": null
}
}
If no errors occurred, the response will be:
$ /contact/create/api.json?fullname=Fullname&msisdn=4512345678
{
"status": "success",
"success": "CREATE_CONTACT",
"contact": {
"fullname": "Fullname",
"msisdn": 4512345678,
"dialcode": 45,
"number": 12345678,
"controluser": 0,
"controlcontact": 0
}
}
Should an error occurr, you can typically find the reason in 'error':
{
"status": "error",
"error": "FULLNAME_EMPTY",
"contact": {
"fullname": null
}
}
fullname
The contacts fullname.
street
The contacts street.
zipcode
The contacts zipcode.
msisdn
The contacts MSISDN.
email
The contacts e-mail.
birthday
The contacts birthday. Unix timestamp (Timezone: Europe/Copenhagen).
sex
The contacts sex. 1 = male and 2 = female.
You can assign a group to the contact:
$ /contact/addgroup/api.json?contact=100&group=100
{
"status": "success",
"success": "ADD_GROUP",
"addgroup": {
"groups": [
"100"
]
}
}
You can remove a group from the contact:
$ /contact/removegroup/api.json?contact=100&group=100
{
"status": "success",
"success": "REMOVE_GROUP",
"removegroup": {
"groups": [
"100"
]
}
}
If no errors occurred, the response will be:
$ /contact/delete/api.json?contact=100
{
"status": "success",
"success": "DELETE_CONTACT"
}
Should an error occur, you can typically find the reason in 'error':
{
"status": "error",
"error": "EMPTY_CONTACT",
"contact": {
"contact": null
}
}
contact
The contact ID.
It's easy to get a list of all your groups.
$ /view/groups/api.json
{
"status": "success",
"success": "VIEW_GROUPS",
"groups": [
{
"controlgroup": 100,
"name": "Groupname",
"contacts": [
{
"controlcontact": 100,
"fullname": "Fullname",
"street": null,
"zipcode": null,
"msisdn": 4512345678,
"dialcode": 45,
"number": 12345678,
"email": null,
"birthday": null,
"sex": null,
"groups": [
100,
126,
25
]
},
...
]
},
...
]
}
Get one group:
$ /view/group/api.json?group=100
{
"status": "success",
"success": "VIEW_GROUP",
"group": {
"controlgroup": 100,
"name": "Groupname",
"contacts": [
{
"controlcontact": 100,
"fullname": "Fullname",
"street": null,
"zipcode": null,
"msisdn": 4512345678,
"dialcode": 45,
"number": 12345678,
"email": null,
"birthday": null,
"sex": null,
"groups": [
100,
126,
25
]
},
...
]
}
}
If no errors occurred, the response will be:
$ /group/create/api.json?name=Name
{
"status": "success",
"success": "CREATE_GROUP",
"group": {
"name": "Name"
}
}
Should an error occur, you can typically find the reason in 'error':
{
"status": "error",
"error": "NAME_EMPTY",
"group": {
"name": null
}
}
name
The groups name.
If no errors occurred, the response will be:
$ /group/delete/api.json?group=100
{
"status": "success",
"success": "DELETE_GROUP"
}
Should an error occur, you can typically find the reason in 'error':
{
"status": "error",
"error": "EMPTY_GROUP",
"group": {
"group": null
}
}
group
The group ID.
If no errors occurred, the response will be:
$ /buy/checkkeyword/api.json?gateway=1919&keyword=pacman
{
"status": "success",
"success": "KEYWORD_AVAILABLE",
"buy": {
"gateway": {
"controlgateway": 1,
"controluser": 1,
"gateway": 1919,
"local": false
},
"keyword": {
"keyword": "pacman",
"price": 120
},
"period": {
"start": 1397512800,
"end": 1400104800,
"price": 120
}
}
}
Should an error occur, you can typically find the reason in 'error':
{
"status": "error",
"error": "KEYWORD_EXISTS"
}
gateway
The gateway, typically 1919, or your hosted SIM-card MSISDN.
keyword
The keyword you want to lookup.
If no errors occurred, the response will be:
$ /buy/keyword/api.json?gateway=1919&keyword=test
{
"status": "success",
"success": "BUY_SUCCESFUL",
"buy": {
"price": 120,
"buy": 100
}
}
All call to 'buy/keyword' are final. You will receive an invoice if the price are greater than 0.00. You can check the price with the 'Check keyword'-endpoint.
gateway
The gateway, typically 1919, or your hosted SIM-card MSISDN.
keyword
The keyword you want to lookup.
You will receive a HTTP GET request to the provided callback-url.
We will listen for HTTP 200 OK. If we receive nothing back or HTTP 404 Not Found (e.g. server offline) we will try every hour, but only 25 times including the first try.
msisdn
The recipient. Mobile number in international format fx. 4512345678
dialcode
Mobile numbers dialcode
number
Mobile number without dialcode
status
Status code
timestamp
The Unix timestamp (Timezone: Europe/Copenhagen) we received the request to send the SMS
delivered
The Unix timestamp (Timezone: Europe/Copenhagen) when the SMS was received on the recipients phone
smsid
Our internal SMS id
msisdn
The recipient. Mobile number in international format fx. 4512345678
dialcode
Mobile numbers dialcode
number
Mobile number without dialcode
timestamp
The Unix timestamp (Timezone: Europe/Copenhagen) we received the SMS
gateway
The gateway number the SMS was received at
keyword
The keyword which received the SMS
network
The senders network name
text
The senders message to your keyword
mms
Comma-separated list of direct URL’s to the file
1-11
Internal termination
12
Number does not exists
The number has not been assigned to a subscriber
13
Number invalid
The number is probably defined wrongly
14
Number blacklisted
22-99
External termination
100
The number is roaming
Happens when you have defined that if number is roaming, the SMS should cancel
150
Delivered