HTTP API Specification
V2.7
HTTP API Specification V2.7
Version information
Version Comment Date
V2.7 Added testsms call 2017-08-09
V2.6 HTTPS information added 2016-12-10
Added error code 4007
V2.5 Changed endpoints 2016-12-09
Added HLR API call
V2.4 Changed the checkoperator response 2014-02-21
V2.3 Added new API call to fetch the account pricing 2014-02-18
with the last modifications
V2.2 Added information about price, number of 2014-02-09
messages and mccmnc after sending SMS
V2.1 New call to check message status 2013-03-23
Added new error code 2017
V2.0 Rebuilt of the API, UTF-8 support 2013-03-21
V1.4.2 Added Error code 2016 - Invalid UTF-8 encoding 2012-09-21
V1.4.1 Added DLR status code 13 – No status update from 2012-01-31
SMSC after 72 hours
V1.4 Removed Fixed line support The Netherlands 2011-12-29
(deprecated)
V1.3 Added Fixed line support The Netherlands 2011-06-20
V1.2 Enhanced Error detection 2011-05-04
V1.1 Added custom messageID support 2011-04-09
V1.0 Added HTTP API IP restriction 2011-04-07
Added error messages
Complete overhaul of this documentation
V0.5 Added error messages 2011-03-31
V0.4 Added Push DLR function 2010-09-06
V0.3 Added credit check 2010-03-18
V0.2 Added operator check 2010-03-18
V0.1 Initial version 2010-03-10
[Link]
HTTP API Specification V2.7
Table of contents
Table of contents...................................................................................................................................... 3
1 - Introduction ........................................................................................................................................ 4
2 - Sending SMS ........................................................................................................................................ 5
3 - Extra information about the submitted SMS ...................................................................................... 7
Use testsms call when implementing ...................................................................................................... 8
4 - Check SMS Route .............................................................................................................................. 10
5 - HLR .................................................................................................................................................... 11
6 - Check credit ....................................................................................................................................... 12
7 - Push DLR (Status reports) ................................................................................................................. 13
8 - Pull DLR (status report) ..................................................................................................................... 14
9 - Get account pricing ........................................................................................................................... 15
10 - Error codes ...................................................................................................................................... 16
11 - DLR Statuses .................................................................................................................................... 17
12 - Troubleshooting .............................................................................................................................. 18
13 – Examples ......................................................................................................................................... 19
13.1 - Sending SMS message .............................................................................................................. 19
13.2 – Check credit ............................................................................................................................. 19
[Link]
HTTP API Specification V2.7
1 - Introduction
This document describes all the functions of the BudgetSMS HTTP API. Read it carefully, as each
chapter will have valuable information that can help implementation or debugging of problems.
[Link]
HTTP API Specification V2.7
2 - Sending SMS
To send messages though our API you need to make a HTTP GET call to our API with your account
and SMS details.
The base URL to use is:
[Link]
Use these variables to specify your account and SMS details
Variable Description Format Mandatory Example
username Your BudgetSMS username alphanumeric yes test
userid Your BudgetSMS userid numeric yes 21547
handle Your API handle alphanumeric yes 1e756dc895456f
msg Text of your SMS message alphanumeric yes This is a test
from Senderid of your SMS message alphanumeric yes BudgetSMS
to Receiver of your SMS message numeric yes 31612345678
customid Your own customMessageID Alphanumeric, no 5d3443564efab1
max 50 chars
price Receive price information of the 1 or 0 no 1
submitted SMS in your (=default)
response
mccmnc Receive country and network 1 or 0 No 20416
information in your response (=default) 204 = mcc
16 = mnc
Credit Show the remaining credit in 1 or 0 No 100.00
your response (=default)
- Username
Your BudgetSMS username.
- Userid
Your BudgetSMS userid. This can be found in the control panel after the login.
- Handle
This is a unique identifier. You can find this also in the control panel after the login.
- Msg
This is the actual message of the SMS. There is not really a maximum number of characters,
but it is considered safe to use up to 612 characters (4 SMSparts).
Please consult this URL with the allowed characters in a normal SMS:
[Link]
- From
This is the sender that will appear in the inbox of the receiver of the SMS. This can be
numeric as well as alphanumeric
o Alphanumeric: maximum length 11 characters (allowed: [a-z], [A-Z] and [0-9])
[Link]
HTTP API Specification V2.7
o Numeric: maximum length 16 numbers (allowed: [0-9])
This must be a valid MSISDN
Consult this link for more information: [Link]
- To
Receiver number of the SMS message. No spaces, do not use the + before the international
countrycode. Omit the first 0 from the number. Example: 31612345678
This must also be a valid MSISDN: [Link]
- Customid
You can add your own customid when sending SMS. This is an unique id that can only be
used once. When you use this ID on more messages you will get an error. If omitted this
function is not used.
- Price
You can add price=1 to your SMS submit. This will give you the total price of the submitted
SMS and the total number of message parts. (check chapter 2 for extra information)
- Mccmnc
You can add mccmnc=1 to your SMS submit. This will give you the mcc (=Mobile Country
Code) and the mnc (=Mobile Network Code) of the SMS message. These are based on mobile
prefixes (so the number can still be ported) (check chapter 2 for extra information)
Be sure to always use URL encoding before making the HTTP call. Use UTF-8 encoding, without this it
can lead to unexpected results (errors, missing text in SMS, etc).
Sending a message could result in the following responses:
OK 12345678
Or
ERR 3001
Please note
When an “OK xxxxx” response is received, we have successfully submitted the message to 1 of our
uplink connections. This means that SMS credit will be deducted from your SMS credit with
BudgetSMS. It is still possible that the message will not be delivered, due to network issues, blocked
routes and other possible problems.
If this happens we can analyze the problem in most cases. So be sure that you always save SMSid’s
and receiver numbers, as we need those to analyze any possible issue with delivery.
When you have received an “ERR xxxx” code, no credit is deducted from your BudgetSMS credit. This
is because there was a problem with the submitted data. Please consult the received error code for a
hint of the problem and a possible solution.
[Link]
HTTP API Specification V2.7
3 - Extra information about the submitted SMS
It is now possible to receive extra information of the SMS details and the receiver operator. In the
SMS submit URL you can add parameters that will give you extra information in the server response
about SMS price, number SMS parts and/or mcc & mnc information of the receiver.
If price information is selected you will receive the total price of the submitted message and the
number of SMS parts.
If (also) mccmnc information is selected you will receive the mcc and mnc codes of the receiver of
the message, determined by the operator prefix.
It is possible to only select 1 of these 2, none (default) or both. The selected information will be
added to the SMS submit response.
For example, if price information is selected you will receive a response like this:
OK 1234567 0.055 1
OK = successful submitted
1234567 = SMSid
0.055 = SMS price
1 = Number of SMS parts
If mccmnc information is selected, the response will look like this:
OK 1234567 20416
Ok = Successful submitted
1234567 = SMSid
20416 = mcc & mnc code combined (204 = Netherlands, 16 = T-Mobile)
If both are selected, the response will look like this:
OK 1234567 0.055 1 20416
OK = successful submitted
1234567 = SMSid
0.055 = SMS price
1 = Number of SMS parts
20416 = mcc & mnc code combined (204 = Netherlands, 16 = T-Mobile)
[Link]
HTTP API Specification V2.7
4 - Use testsms call when implementing
It is possible to do a request to the API to implement the API in your application without actually
sending any SMS. This request fakes SMS delivery, enabling you to make the implementation. This
call will simulate the sendsms call, without actually sending SMS/reducing your credit.
The base URL to use is:
[Link]
Use these variables to specify your account and SMS details
Variable Description Format Mandatory Example
username Your BudgetSMS username alphanumeric yes test
userid Your BudgetSMS userid numeric yes 21547
handle Your API handle alphanumeric yes 1e756dc895456f
msg Text of your SMS message alphanumeric yes This is a test
from Senderid of your SMS message alphanumeric yes BudgetSMS
to Receiver of your SMS message numeric yes 31612345678
customid Your own customMessageID Alphanumeric, no 5d3443564efab1
max 50 chars
price Receive price information of the 1 or 0 no 1
submitted SMS in your (=default)
response
mccmnc Receive country and network 1 or 0 No 20416
information in your response (=default) 204 = mcc
16 = mnc
Credit Show the remaining credit in 1 or 0 No 100.00
your response (=default)
- Username
Your BudgetSMS username.
- Userid
Your BudgetSMS userid. This can be found in the control panel after the login.
- Handle
This is a unique identifier. You can find this also in the control panel after the login.
- Msg
This is the actual message of the SMS. There is not really a maximum number of characters,
but it is considered safe to use up to 612 characters (4 SMSparts).
Please consult this URL with the allowed characters in a normal SMS:
[Link]
[Link]
HTTP API Specification V2.7
- From
This is the sender that will appear in the inbox of the receiver of the SMS. This can be
numeric as well as alphanumeric
o Alphanumeric: maximum length 11 characters (allowed: [a-z], [A-Z] and [0-9])
o Numeric: maximum length 16 numbers (allowed: [0-9])
This must be a valid MSISDN
Consult this link for more information: [Link]
- To
Receiver number of the SMS message. No spaces, do not use the + before the international
countrycode. Omit the first 0 from the number. Example: 31612345678
This must also be a valid MSISDN: [Link]
- Customid
You can add your own customid when sending SMS. This is an unique id that can only be
used once. When you use this ID on more messages you will get an error. If omitted this
function is not used.
- Price
You can add price=1 to your SMS submit. This will give you the total price of the submitted
SMS and the total number of message parts. (check chapter 2 for extra information)
- Mccmnc
You can add mccmnc=1 to your SMS submit. This will give you the mcc (=Mobile Country
Code) and the mnc (=Mobile Network Code) of the SMS message. These are based on mobile
prefixes (so the number can still be ported) (check chapter 2 for extra information)
Be sure to always use URL encoding before making the HTTP call. Use UTF-8 encoding, without this it
can lead to unexpected results (errors, missing text in SMS, etc).
Sending a message could result in the following responses:
OK 12345678
Or
ERR 999X
Please note
When an “OK xxxxx” response is received, no SMS is sent. No credit is deducted from your account.
This is just a test call.
[Link]
HTTP API Specification V2.7
5 - Check SMS Route
It is possible to check the country and the operator based on the mobile number prefix. Please be
advised: this is NOT an HLR service (for that see chapter 6). If a number is ported to another
operator, it will not show up in this API call. It is only able to determine the original operator.
The URL to this call is
[Link]
Use these variables to specify your account and MSISDN details
Variable Description Format Mandatory Example
username Your BudgetSMS username alphanumeric yes test
userid Your BudgetSMS userid Numeric yes 21547
handle Your API handle alphanumeric yes 1e756dc895456f
check The number to check operator numeric yes 31612345678
When the call was successful, expect a result similar to this:
OK:20416:T-Mobile Netherlands BV:0.0450
OK:[MccMnc]:[OperatorName]:[MessageCost]
Or when it was not successful:
ERR [errorcode]
[Link]
HTTP API Specification V2.7
6 - HLR
Chapter 5 describes a cheap way to determine the original operator, with HLR you can check the
actual operator. When a number is ported from 1 operator to another, this call will allow you to
know the current operator.
The URL to this call is
[Link]
Use these variables to specify your account and MSISDN details
Variable Description Format Mandatory Example
username Your BudgetSMS username alphanumeric yes test
userid Your BudgetSMS userid Numeric yes 21547
handle Your API handle alphanumeric yes 1e756dc895456f
to The number to check operator numeric yes 31612345678
When the call was successful, expect a result similar to this:
OK:20416:T-Mobile Netherlands BV:0.0450
OK:[MccMnc]:[OperatorName]:[MessageCost]
Or when it was not successful:
ERR [errorcode]
[Link]
HTTP API Specification V2.7
7 - Check credit
To check your remaining credit use this URL
[Link]
Use these variables to specify your account details
Variable Description Format Mandatory Example
username Your BudgetSMS username alphanumeric yes test
userid Your BudgetSMS userid numeric yes 21547
handle Your API handle alphanumeric yes 1e756dc895456f
Result with correct account details will be:
OK 123.12
When not correct:
ERR [errorcode]
[Link]
HTTP API Specification V2.7
8 - Push DLR (Status reports)
It is possible to receive DLR information about the messages you have sent. Our system will push
these updates to your server so you can process these updates in your software.
To enable this service for your account please login at the control panel and enter an URL where you
want to receive the status updates. When we detect that you have entered an URL we will push the
updates there.
Please make sure this URL accepts GET requests from BudgetSMS with these variables
Parameter Explanation
id SMS messageid
status New status code
date Timestamp of the DLR change (this can be a non
local timestamp)
Every GET request to your URL consists of one (1) status update. So expect at least one GET request
for every SMS submitted
[Link]
HTTP API Specification V2.7
9 - Pull DLR (status report)
It is possible to manually request the SMS status of sent messages. If somehow the push DLR
messages do not fit your application.
Please check the error code table and the DLR statuses table for use with this API call.
We do recommend to use the push DLR, instead of manually checking each SMS.
[Link]
Use these variables to specify your account details
Variable Description Format Mandatory Example
username Your BudgetSMS username alphanumeric yes test
userid Your BudgetSMS userid numeric yes 21547
handle Your API handle alphanumeric yes 1e756dc895456f
smsid The SMSid generated at sending numeric yes 25487134
Result with correct account details will be:
OK [DLR status]
When not correct:
ERR [errorcode]
[Link]
HTTP API Specification V2.7
10 - Get account pricing
To get the pricing that has been setup in your account make the following API call. You will receive a
response with the full pricing to all operators as a JSON object. Each operator has the last_modified
parameter, datetime value in GMT+1.
[Link]
Use these variables to specify your account details
Variable Description Format Mandatory Example
username Your BudgetSMS username alphanumeric yes test
userid Your BudgetSMS userid numeric yes 21547
handle Your API handle alphanumeric yes 1e756dc895456f
If the credentials are not correct you will receive:
ERR xxxx
When the request is successful you will get a JSON object with all the details of the pricing in your
account. In this object you can find:
Field Description Example
countryprefix This is the prefix for telephone numbers in this 31
specific country
countryname This is the name of the country The Netherlands
mcc This is the mcc code (mobile country code) in this 204
specific country
operatorname The name of the operator Tele2
mnc This is the mnc code (mobile network code) in 02
this specific country
price The price per smspart in euro 0.04
old_price The old price before the change 0.045
last_modified This is the last date the price has changed 2014-02-18 [Link]
(GMT+1)
[Link]
HTTP API Specification V2.7
11 - Error codes
Error codes with explanation when sending a SMS message returns an error.
Error code Description
1001 Not enough credits to send messages
1002 Identification failed. Wrong credentials
1003 Account not active, contact BudgetSMS
1004 This IP address is not added to this account. No access to the API
1005 No handle provided
1006 No UserID provided
1007 No Username provided
2001 SMS message text is empty
2002 SMS numeric senderid can be max. 16 numbers
2003 SMS alphanumeric sender can be max. 11 characters
2004 SMS senderid is empty or invalid
2005 Destination number is too short
2006 Destination is not numeric
2007 Destination is empty
2008 SMS text is not OK (check encoding?)
2009 Parameter issue (check all mandatory parameters, encoding, etc.)
2010 Destination number is invalidly formatted
2011 Destination is invalid
2012 SMS message text is too long
2013 SMS message is invalid
2014 SMS CustomID is used before
2015 Charset problem
2016 Invalid UTF-8 encoding
2017 Invalid SMSid
3001 No route to destination. Contact BudgetSMS for possible solutions
3002 No routes are setup. Contact BudgetSMS for a route setup
3003 Invalid destination. Check international mobile number formatting
4001 System error, related to customID
4002 System error, temporary issue. Try resubmitting in 2 to 3 minutes
4003 System error, temporary issue.
4004 System error, temporary issue. Contact BudgetSMS
4005 System error, permanent
4006 Gateway not reachable
4007 System error, contact BudgetSMS
5001 Send error, Contact BudgetSMS with the send details
5002 Wrong SMS type
5003 Wrong operator
6001 Unknown error
7001 No HLR provider present, Contact BudgetSMS.
7002 Unexpected results from HLR provider
7003 Bad number format
7901 Unexpected error. Contact BudgetSMS
7902 HLR provider error. Contact BudgetSMS
7903 HLR provider error. Contact BudgetSMS
[Link]
HTTP API Specification V2.7
12 - DLR Statuses
When a DLR callback to your server is done, expect the following possible status codes
Status code Status
0 Message is sent, no status yet (default)
1 Message is delivered
2 Message is not sent
3 Message delivery failed
4 Message is sent
5 Message expired
6 Message has a invalid destination address
7 SMSC error, message could not be processed
8 Message is not allowed
11 Message status unknown, usually after 24 hours without status update SMSC
12 Message status unknown, SMSC received unknown status code
13 Message status unknown, no status update received from SMSC after 72
hours after submit
[Link]
HTTP API Specification V2.7
13 - Troubleshooting
Always make sure the data is URL encoded before sending. There can be some strange
results when not decoding the data.
Also use the UTF-8 character set when encoding SMS messages. If you use other character
encoding schemas it might lead to unexpected results.
If you have questions about new SMS routes or are experiencing problems with our HTTP API
don’t hesitate to contact us with your questions. If you have questions about SMS delivery of
SMS related problems, make sure you include information that allows us to inspect your
issue. This means SMSid’s, receivernumbers and/or userid’s. Omitting these will result in
delayed investigation.
[Link]
HTTP API Specification V2.7
14 – Examples
Each example shown below uses the following fictional user details. To be able to perform the same
API calls, these values need to be replaced with the account values for it to work properly.
username = test
handle = 1234ef2354238dac2
userid = 25135
14.1 - Sending SMS message
The following URL needs to be constructed and submitted. The API will then return an SMSid
or an error code.
[Link]
msg=This%20is%20a%20test%20message&from=BudgetSMS&to=31612345678
When successful will give this output:
OK XXXXXXXX
where XXXXXXXXX is the messageID. Save this message ID when you receive status
information, as this messageID is your only way of identifying this SMS.
If there was an error (no credit, wrong login information, etc) it will be something like this:
ERR XXXX
(Where XXXX is the actual error code, please consult the list of possible errors)
Tip:
Please also consult chapter 2 for additional response options, that may be different than the
responses in the above example
14.2 – Check credit
To fetch the remaining credit the following URL can be constructed
[Link]
5
[Link]
HTTP API Specification V2.7
When successful it will return:
OK 100.00
Or when something was not right:
ERR XXXX
XXXX represents an error code. Please consult the list with possible error codes to know what
happened.
[Link]
