NIMBOW API DOCUMENT

The Nimbow API provides functionality to send SMS automatically.

Additional delivery status and other information is provided through the
API responses.
The Nimbow API can easily be integrated into applications required to
send A2P (Application to Person) SMS.

Version: 2.5

API DOCUMENTATION
Table of Content
Table of Content ...................................................................................................................................... 1
Change Notes of Document ................................................................................................................... 2
Nimbow API ............................................................................................................................................. 3
Security of the Nimbow API ................................................................................................................ 3
Format rules of the API documentation ............................................................................................. 3
Nimbow API Specification....................................................................................................................... 4
API Call: SMS Parameters......................................................................................................................... 5
Call-back: Delivery Report ....................................................................................................................... 7
API Call: Balance ...................................................................................................................................... 8
Appendix A Nimbow API Calls and their Status Codes .......................................................................... 9
Appendix B GSM Character Set.............................................................................................................10
References .............................................................................................................................................12

NimbusFive GmbH
Ruhrallee 9
44139 Dortmund I Germany

API DOCUMENTATION
Change Notes of Document
Version
1.0
2.0

Date
01/04/2015
22/04/2015

2.1
2.2

30/04/2015
04/06/2015

2.3
2.4

24/06/2015
05/08/2015

2.5

07/09/2015

NimbusFive GmbH
Ruhrallee 9
44139 Dortmund I Germany

Changes
Initial Release
Add parameter test to API Call sms
Add parameter type to API Call sms
Add parameter udh to API Call sms
Add parameter flash to API Call sms
Add API Balance
Added Appendix B GSM Character Set
API Call Balance: Add remark formatted in InvariantCulture
Extended description of Status Code 5
Removed Status Code 100 (No Sender is given)
Removed Status Code 206 (Empty Sender)
Introduced new error code 211 (No Hex Encoding)
Add parameter GetFMC to API Call balance
Removed Status Code 201 (Empty Receiver)
Removed Status Code 202 (Empty Text)
Removed Status Code 207 (From used non-GSM character)
Simplified examples

API DOCUMENTATION
Nimbow API
The Nimbow API provides functionality to send SMS automatically. Additionally the delivery status
and several other information are provided through the API responses. The Nimbow API can easily
be integrated into applications required to send SMS A2P (Application to Person).
This document contains the description and explanations how to use the Nimbow API.

Security of the Nimbow API

The Nimbow API meets the demand on security supporting the possibility to call all Nimbow API
functions via an encrypted http connection. The Nimbow API uses the standardised HTTPS over
SSL/TLS protocol. The HTTPS connections are established through the port 443 whereas HTTP
connections use port 80.
To use an encrypted connection the prefix https has to be used to the Nimbow API function.
Besides the secure connection via HTTPS the HTTP can be used. Data exchanges via HTTP are not
encrypted.

Format rules of the API documentation

This section gives a short overview how to read the documentation.
Text in monospaced font is meant to be copied and taken as it is.
Text enclosed in [square brackets] must be replaced.

NimbusFive GmbH
Ruhrallee 9
44139 Dortmund I Germany

API DOCUMENTATION
Nimbow API Specification
The Nimbow
The Nimbow API is very easy to use and intuitively structured. The following scheme describes the
structure of the Nimbow API:
structure of the Nimbow API:
See following table for supported protocols.
See following table for supported protocols.
Protocol

API URL

API Call with Parameter

Format of the
Response

https://api.nimbow.com/[API-CALL]?[API-CALL-PARAMETER]&format=[TYPE]
https://api.nimbow.com/[API-CALL]?[API-CALL-PARAMETER]&format=[TYPE]

Supported Protocols of the Nimbow API.

Protocol
http
https

Meaning
Use http via Port 80
Use https via Port 443

See following table for a list of all Nimbow API calls. For a more detailed description and usage see
the correspondent sections.
Possible Nimbow API Calls.
Nimbow API Call
sms
balance

Meaning
Send a single message
Get the current balance

Following table lists all format types supported of the API Call response.
Possible Nimbow API format types.
Format Type
HTML (default)
JSON
XML

Meaning
Response of the API Call is returned as Hyper Text Mark-up Language (HTML)
Response of the API Call is returned as JavaScript Object Notation (JSON)
Response of the API Call is returned as Extensible Mark-up Language (XML)

Each Nimbow API Call returns a status code. Appendix A provides a list of all Nimbow API Calls and
the correspondent status codes.

NimbusFive GmbH
Ruhrallee 9
44139 Dortmund I Germany

API DOCUMENTATION
API Call: SMS Parameters
This API function provides the possibility to send a single SMS.
Http(s)-Methods:

GET/POST
Http GET Examples
Send a message:
http://api.nimbow.com/sms?key=COdk59Q1dmr&from=Max&to=4917212345670&text=Hi

Send a Unicode message:

http://api.nimbow.com/sms?key=COdk59Q1dmr&from=Max&to=4917212345670&text=039303B503B903AC00
2003C303BF03C50020039A03CC03C303BC03B50021&type=unicode

On the handset the text ! from the sender Max should be received.
Send a binary message:
http://api.nimbow.com/sms?key=COdk59Q1dmr&from=Max&to=4917212345670&text=424547494E3A564341
52440A56455253494F4E3A322E310A4E3A6E696D626F772E636F6D0A54454C3B574F524B3B564F4943453A30
3330353535353535350A54454C3B574F524B3B4641583A303330353535353535340A454D41494C3A696E666F4
06E696D626F772E636F6D0A454E443A5643415244&type=binary&udh=06050423F423f4

Send a flash message:

http://api.nimbow.com/sms?key=COdk59Q1dmr&from=Max&to=4917212345670&text=Hi&flash=true

Send a Unicode flash message:

http://api.nimbow.com/sms?key=COdk59Q1dmr&from=Max&to=4917212345670&
text=041F044004380432043504420020041C04380440&type=Unicode&flash=true

NimbusFive GmbH
Ruhrallee 9
44139 Dortmund I Germany

API DOCUMENTATION
API Call: SMS Parameters
Parameter:
URL Parameter
Key
To
Text

Required/Optional
REQUIRED
REQUIRED
REQUIRED

From

OPTIONAL

ClientRef

OPTIONAL

GetMessageId
GetMessageParts
GetFrom
GetTo
GetCost
GetDeliveryReport

OPTIONAL
OPTIONAL
OPTIONAL
OPTIONAL
OPTIONAL
OPTIONAL

Test

OPTIONAL

Type

OPTIONAL

Description
API key saved in your user profile
Numeric receiver with 5-16 digits
Content of message (min. 1 character; UTF-8 coded)
If the number of characters is greater than 160 characters the SMS will
be split into parts with each max. 153 characters.
Sender can be
1. Numeric: up to 16 digits
2. Alpha-numeric: 1-11 characters
If none is given a default sender SMS will be used.
User defined reference given as string. Allowed characters are:
a-z
A-Z
0-9
Dash -
Underscore _
If set to 1 or true the API call response contains MessageId
If set to 1 or true the API call response contains MessageParts
If set to 1 or true the API call response contains From
If set to 1 or true the API call response contains To
If set to 1 or true the API call response contains Cost
If set to 0 or false no delivery report will be send to provided call
back
If set to 1 or true the message will be handled as follow
Saved like each other message
Usage of each API Call parameter
No DLR Call back handling
No transmission
No billing
Type can be used to send either Unicode or Binary coded messages:
Set to unicode to send Unicode message
Set to binary to send Binary message
Message text must be given in hexadecimal encoded characters, e.g.
&text=041F04400438043204350442

Udh
Flash

OPTIONAL
OPTIONAL

Can be used together with binary messages, i.e. if Type is set to Binary.
Can be used to send Flash messages.

The response of this API function contains at least a status code. If requested in the API call using the
correspondent parameter the response can be extended.
Response:
Key
StatusCode
MessageId
MessageParts
From
To
NetCost

NimbusFive GmbH
Ruhrallee 9
44139 Dortmund I Germany

Sent in
Response
ALWAYS
IF REQUESTED
IF REQUESTED
IF REQUESTED
IF REQUESTED
IF REQUESTED

Value
See Appendix A
Unique Id of the transmitted Message
Number of messages the SMS was split into
Sender of the transmitted Message
Receiver of the transmitted Message
Cost of the sent Message

API DOCUMENTATION
Call-back: Delivery Report
A call-back URL can be provided in the user profile at the Nimbow platform to receive SMS Delivery
Reports. The GET URL has to have a valid format containing optional Nimbow parameter. The
Nimbow parameter must be given in angle brackets - < and >.
Example:

Call customer DLR GET URL providing the message ID and delivery state:
http://customer.com/dlr?MsgID=<MessageId>&MsgState=<State>

Parameter:
Parameter
MessageId
To
From
State
ReceiveTS
SendTS
ReceiveDT
SendDT
ClientRef

NimbusFive GmbH
Ruhrallee 9
44139 Dortmund I Germany

Description
ID of the Message sent
Normalised 'To' number from sent message
Normalised 'From' alphanumeric or numeric sender
One of the following:
DELIVERED, SUBMITTED, BUFFERED and UNDELIVERED.
UTC time stamp given as Unix epoch time the DLR was received
EXAMPLE: 1423919873
UTC time stamp given as Unix epoch time the Message was sent
EXAMPLE: 1423919873
UTC date time given as ISO 8601 the DLR was received
EXAMPLE: 2015-02-14T13:17:53Z
UTC date time given as ISO 8601 the Message was sent;
EXAMPLE: 2015-02-14T13:17:53Z
Given client reference text of sent Message

API DOCUMENTATION
API Call: Balance
This API function provides the possibility to request the current balance of the account. The balance
value is provided as InvariantCulture, i.e. the decimal mark is a point.
Http(s)-Methods:

GET/POST
Http GET Example
Request current balance:
http://api.nimbow.com/balance?key=COdk59Q1dmr

Parameter:
URL Parameter
Key
GetDT
GetTS
GetFMC

Required/Optional
REQUIRED
OPTIONAL
OPTIONAL
OPTIONAL

Description
API key saved in your user profile
If set to 1 or true the API call response contains DateTime
If set to 1 or true the API call response contains Timestamp
If set to 1 or true the API call response contains
FreeMessagesCount

Key
StatusCode
Balance
DateTime

Sent in Response
ALWAYS
ALWAYS
IF REQUESTED

Timestamp

IF REQUESTED

FreeMessagesCount

IF REQUESTED

Value
See Appendix A
The balance at the time of the request given as InvariantCulture
UTC date time given as ISO 8601 the balance value was taken
EXAMPLE: 2015-02-14T13:17:53Z
UTC time stamp given as Unix epoch time the balance value was taken
EXAMPLE: 1423919873
Number of available free messages

Response:

NimbusFive GmbH
Ruhrallee 9
44139 Dortmund I Germany

API DOCUMENTATION
Appendix A Nimbow API Calls and their Status Codes
Following table shows the Nimbow API calls and the possible status codes returned.
Nimbow API calls and their Status Codes and Meanings.
API Call
All

SMS

NimbusFive GmbH
Ruhrallee 9
44139 Dortmund I Germany

Code
0
1

Meaning
Success
Internal Error

2
3

Unknown Error
Out of Credits

4
5

Invalid API Call

Invalid API Credentials

101
102
200

to missing or empty
text missing or empty
from invalid length

203

text contains non GSM character

204

from - invalid alpha numeric length

205

to invalid length

208
209

clientref contains invalid character

Invalid Type

210

Invalid UDH

211

Message Text Needs to be Encoded

Description
The message was successfully accepted for delivery
An error has occurred in the platform while
processing this message
An undocumented error occurred
Your account does not have sufficient fund to
process this message
A valid URL to call the API must be used
The provided API key could be wrong or the IP
Addressed used is not configured to be allowed to
use the API.
The request contains no receiver information
The request contains no message content
The numeric sender is allowed to contain max. 16
digits
The message text must contain only GSM characters.
If non GSM character shall be sent, please use
type=unicode
The alpha numeric sender is allowed to have 1 to 11
character
The receiver must have a length between 5 and 16
digits. Country code is not included in that count.
The clientref must contain only valid characters
Wrong type given. See documentation of API Call
sms.
The given UDH is wrong:
UDH can only contain hexadecimal
characters (0-9 a-f)
UDH can only contain up to 14
hexadecimal characters
Using type requires the message text to be hex
encoded

API DOCUMENTATION
Appendix B GSM Character Set
If not given otherwise the text of the SMS is sent encoded using the GSM 7-bit default alphabet see
below. Each character used consumes one place in the message text, i.e. 160 characters can be used
in a single message part.
GSM 7 bit Default Alphabet [1].

SP

"

&

'

10

LF

11

1)

12

<

13

CR

14

>

15

Table above shows the extended character set. Each of those characters consumes two places in a
SMS message text.

NimbusFive GmbH
Ruhrallee 9
44139 Dortmund I Germany

10

API DOCUMENTATION
Appendix B GSM Character Set
GSM 7 bit Default Alphabet Extension [1].

1
2
3
4

6
7
8

10

3)

11

1)

12

13

14

15

NOTE 1): This code is reserved for the extension to another extension table. On receipt of this
code, a receiving entity shall display a space until another extension table is defined. It is
not intended that this extension mechanism should be used as an alternative to UCS2 to
enhance the 7bit default alphabet character repertoire for national specific character
sets.
NOTE 2): Void
NOTE 3): This code is defined as a Page Break character and may be used for example in
compressed CBS messages. Any mobile station which does not understand the GSM 7 bit
default alphabet table extension mechanism will treat this character as Line Feed.

NimbusFive GmbH
Ruhrallee 9
44139 Dortmund I Germany

11

API DOCUMENTATION
References
[1] Alphabets and language-specific information (3G TS 23.038 version 10.0.0) (zipped .doc file), ETSI, March 2011.

NimbusFive GmbH
Ruhrallee 9
44139 Dortmund I Germany

12