Getting Started

Endpoints

Notifications

Handling Errors

Getting Started

Overview

All services are accessed via our secured domain: https://api.xonadu.com

The Xonadu API provides methods for sending and receiving SMS. We've taken every effort to maintain a simple and useful interface to enable you to easily integrate SMS into your application. Our team is always on hand to help, just head to the Xonadu website to get in touch.

SMS Credits

When you first sign up for an account we will provide 20 free credits to get you started. Further credits can be purchased via our self service portal or by contacting the Xonadu team.

The API provides several methods for retrieving account data that will allow you to automate your credit management, your remaining balance will also be returned every time you send a message.

Rate Limiter

All accounts are provisioned with a default rate limit setting of 10 requests per minute with a maximum of 20 message destinations per request. When this limit is exceeded the platform will reject requests until the minute has elapsed. The limit can easily be increased by our team and can be removed for all trusted clients.

Authentication

Our platform authenticates your requests using API keys which will be automatically provisioned when you register. You will receive two keys, one for testing and one for live use.

Your API key must be included in the authorization header of all requests with a prefix "ApiKey", as shown in the example below.

POST /v1/message HTTP/1.1
Host: api.xonadu.com
Cache-Control: private, max-age=0, no-cache
Authorization: ApiKey live-7f3-61f6-11e5-92cb-064b2c914051
Content-Type: application/json

Application Testing

During the development of your application you are able to test all endpoints using your test API key. The test key allows you to interact with the services fully without sending any messages or incurring any charges.

Endpoints

Send SMS

POST /v1/message

This method allows you to send SMS to one or more destination handsets with a single request. Successful calls to this method will dispatch SMS to the mobile networks immediately if sufficient credit is available on your account.

Multiple Destinations

You can send multiple SMS in a single request by simply including a list of destinations in your request, as shown in the example below. There is a default limit of 20 destinations per request. If you require more destinations please contact sales@xonadu.com.

Request Validation

You can view the validation rules for each parameter in the overview tabs below. Any validation errors are reported in the response and no messages will be sent until the errors have been resolved.

All destination numbers must be valid UK mobile numbers in either E.164 or national number format. For access to international destinations please contact us to have this enabled on your account.

POST /v1/message HTTP/1.1
Host: api.xonadu.com
Cache-Control: private, max-age=0, no-cache
Authorization: ApiKey live-7f3-61f6-11e5-92cb-064b2c914051
Content-Type: application/json

{
    "destinations":["+447500000001","+447500000002"],
    "originator":"Xonadu",
    "client_ref":"example_reference",
    "body": "This is my message"
}
HTTP/1.1 202 ACCEPTED
Content-Type: application/json

{
    "status": "OK",
    "request_id": "example1-f446-4d0f-872b-7bac1141dd0e",
    "destinations": [
        {
            "destination": "+447500000001",
            "message_id": "example2-e9fd-40cf-818e-8773724a1a09"
        },
        {
            "destination": "+447500000002",
            "message_id": "example3-e9fd-40cf-818e-8773724a1a09"
        }
    ],
    "originator": "Xonadu",
    "client_ref": "example_reference",
    "body": "My SMS Content - sent with the Xonadu API",
    "credits_remaining": 998
}
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json

{
    "status": "FAILED",
    "errors": [
        {
            "error_code": "PARAM_MISSING",
            "parameter": "destinations",
            "data": null,
            "message": "Required parameter is missing"
        }
    ]
}
Name Required Type Description
destinations 1 string|array Destination list for this message. This can be a single phone number or an array in JSON requests. Form-encoded requests can provide a comma-separated list of destinations.
originator 1 string The number from which you want to send SMS. This can be a text string (up to 11 characters) or a phone number of your choice. If sending from a phone number the number must be registered to you or your organisation.
body 1 string The content of your message, up to 160 characters.
client_ref string Your own reference for this request to be included in all subsequent notifications and interactions with the messages generated with this ID. Maximum length is 128 characters.
url_delivery string URL (including protocol) for us to notify when a delivery receipt received. This will override any delivery URL specified against your key. i.e. "http://www.example.com/notify/receipt"
service_id string Assign request to a specific Xonadu service ID
route string Trusted power users only. For more information contact sales@xonadu.com

Send Two-way SMS

POST /v1/message/two-way

Send two-way SMS to one or many destinations with a single request. Successful calls to this method will dispatch SMS to the mobile networks immediately if sufficient credit is available on your account.

How it Works

When SMS are dispatched using this method a temporary virtual mobile number (VMN) will be automatically assigned as the message originator. This enables the destination mobile to reply to the message. All replies that are received will generate a notification to the reply_url registered with the original request. If no notification URL has been configured the messages will be logged on your account for manual processing.

Feature Options

You are able to configure the duration of the session on a per message basis. Reply messages will be ignored after this period. This provides you with the flexibility to control how long reply windows are maintained in order to suit the specific needs of your application.

We also provide the ability to maintain sessions beyond the first response by setting the single_use indicator. This setting indicates whether you want a single reply only or alternatively allows sessions to be maintained until the TTL window expires.

Maintaining Conversations

The pairing feature makes having conversations with your contacts simple, all you have to do is set the originator field in your subsequent requests to use the same virtual mobile number returned in the originator field of your original request. It can also be retrieved at any time by checking the status of the previous request.

If you have any issues implementing your system please feel free to contact our team who will be more than happy to offer assistance.

POST /v1/message/two-way HTTP/1.1
Host: api.xonadu.com
Cache-Control: private, max-age=0, no-cache
Authorization: ApiKey live-7f3-61f6-11e5-92cb-064b2c914051
Content-Type: application/json

{
    "destinations":["+447512345678","+447500000000"],
    "client_ref":"example_reference",
    "url_reply":"https://data.example.com/sms/reply",
    "url_delivery":"https://data.example.com/sms/receipt",
    "ttl":"30",
    "single_use":"1",
    "body": "This is my message"
}
HTTP/1.1 202 ACCEPTED
Content-Type: application/json

{
    "status": "OK",
    "request_id": "311b29f3-5833-4f5d-906b-e262143bd141",
    "destinations": [
        {
            "destination": "+447538232754",
            "session_id": "96b7b6e4-a53e-44e9-bf64-fd5a9bdbe282"
        },
        {
            "destination": "+447500000000",
            "session_id": "96b7b6e4-a53e-44e9-bf64-fd5a9bda12af"
        }
    ],
    "originator": "+44786001234",
    "client_ref": "example_reference",
    "body": "This is my message",
    "credits_remaining": 997
}
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json

{
    "status": "FAILED",
    "errors": [
        {
            "error_code": "PARAM_MISSING",
            "parameter": "destinations",
            "data": null,
            "message": "Required parameter is missing"
        }
    ]
}
Name Required Type Description
destinations 1 string|array Destination list for this message. This can be a single phone number or an array in JSON requests. Form-encoded requests can provide a comma-separated list of destinations.
body 1 string The content of your message, up to 160 characters.
originator string For use with sticky sessions only. You must enter the previously allocated VMN exactly as it appeared in the response to your original message request. For most requests the originator should be omitted to allow the number to be automatically allocated.
client_ref string Your own reference for this request to be included in all subsequent notifications and interactions with the messages generated with this ID. Maximum length is 128 characters.
url_reply string URL (including protocol) for us to notify when a reply received. i.e. "http://www.example.com/notify/reply"
url_delivery string URL (including protocol) for us to notify when a delivery receipt received. i.e. "http://www.example.com/notify/receipt"
ttl string The number of minutes to keep this pairing alive. Default value is 1440 (24 hours)
single_use int If set to 1 this will terminate the pairing on reply. When set to 0 the pairing will be maintained for the duration of the timeout period. Default value is 1
service_id string Assign request to a specific Xonadu service ID
route string Trusted power users only. For more information contact sales@xonadu.com

Check Message Status

GET /v1/message/{message_id}

This method should be called to manually retrieve details related to a single SMS dispatch. This should not be confused with checking the status of a request which may have started one or more message sessions.

Message ID

Every valid SMS dispatch request returns a formatted list of your requested destinations (see examples above) each having a unique message_id. This ID is your reference to manually check the delivery status to a particular destination. If you have requested delivery notifications you can use this ID to identify the message to which the notification relates.

GET /v1/message/example3-e9fd-40cf-818e-8773724a1a09 HTTP/1.1
Host: api.xonadu.com
Cache-Control: private, max-age=0, no-cache
Authorization: ApiKey live-7f3-61f6-11e5-92cb-064b2c914051
HTTP/1.1 200 OK
Content-Type: application/json

{
    "message_id": "example3-e9fd-40cf-818e-8773724a1a09",
    "status": "DELIVERED",
    "originator": "Xonadu",
    "destination": "+447500000002",
    "body": "My SMS Content - sent with the Xonadu API",
    "receipt_date": "2015-05-14 14:17:23",
    "client_ref": "example_reference",
    "request_id": "example1-f446-4d0f-872b-7bac1141dd0e",
    "request_date": "2015-05-14 14:17:14"
}
HTTP/1.1 404 NOT FOUND
Content-Type: application/json

{
    "status": "FAILED",
    "errors": [
        {
            "error_code": "NOT_FOUND",
            "parameter": "message_id",
            "data": "example3-e9fd-40cf-818e-8773724a1a09",
            "message": "The message could not be located"
        }
    ]
}

Check Request Status

GET /v1/request/{request_id}

Call this method to manually retrieve details of all messages related to an SMS dispatch request.

Request ID

Every successful messaging request will return a unique request_id which is your reference to a particular batch of messages. Maintaining a record of your request ID's will allow you to manually check the delivery status of all the destinations in a single request.

GET /v1/request/example1-f446-4d0f-872b-7bac1141dd0e HTTP/1.1
Host: api.xonadu.com
Cache-Control: private, max-age=0, no-cache
Authorization: ApiKey live-7f3-61f6-11e5-92cb-064b2c914051
HTTP/1.1 200 OK
Content-Type: application/json

{
    "request_id": "example1-f446-4d0f-872b-7bac1141dd0e",
    "request_date": "2015-05-14 14:17:14",
    "messages": [
        {
            "message_id": "example2-e9fd-40cf-818e-8773724a1a09",
            "destination": "+447500000001",
            "status": "DELIVERED",
            "receipt_date": "2015-05-14 14:17:23"
        },
        {
            "message_id": "example3-e9fd-40cf-818e-8773724a1a09",
            "destination": "+447500000002",
            "status": "DELIVERED",
            "receipt_date": "2015-05-14 14:17:26"
        }
    ],
    "originator": "Xonadu",
    "client_ref": "example_reference",
    "body": "My SMS Content - sent with the Xonadu API"
}
HTTP/1.1 404 NOT FOUND
Content-Type: application/json

{
    "status": "FAILED",
    "errors": [
        {
            "error_code": "NOT_FOUND",
            "parameter": "request_id",
            "data": "example1-f446-4d0f-872b-7bac1141dd0e",
            "message": "The request could not be located"
        }
    ]
}

Account Overview

GET /v1/account

Retrieve full details of your account. This method exposes your remaining credit balance and services associated with your account.

Services

Services are simple logical separations for groups of messages and can be provisioned with directly associated API keys. This feature allows you to group messages for individual campaigns or teams within your organisation and can be configured on your behalf by the Xonadu team.

GET /v1/account HTTP/1.1
Host: api.xonadu.com
Cache-Control: private, max-age=0, no-cache
Authorization: ApiKey live-7f3-61f6-11e5-92cb-064b2c914051
HTTP/1.1 200 OK
Content-Type: application/json

{
    "customer_id": "example4-5833-4f5d-906b-e262143bd141",
    "customer_name": "Xonadu",
    "active": true,
    "credit": [
        "credit_sms": 200,
        "credit_sms_last_used": "2015-05-14 14:17:15"
    ],
    "services": [
        {
            "service_id": "TEST1",
            "description": "Xonadu example service 1",
            "date_created": "2014-11-11 16:22:20",
            "active": true
        },
        {
            "service_id": "TEST2",
            "description": "Xonadu example service 2",
            "date_created": "2014-12-01 14:41:51",
            "active": false
        }
    ]
}
HTTP/1.1 404 NOT FOUND
Content-Type: application/json

{
    "status": "FAILED",
    "errors": [
        {
            "error_code": "NOT_FOUND",
            "parameter": "customer_id",
            "data": "12345678-1234-1234-1234-123456789012",
            "message": "Account not found"
        }
    ]
}

Credit Check

GET /v1/account/credit

This method returns details of your credit balance.

GET /v1/account/credit HTTP/1.1
Host: api.xonadu.com
Cache-Control: private, max-age=0, no-cache
Authorization: ApiKey live-7f3-61f6-11e5-92cb-064b2c914051
HTTP/1.1 200 OK
Content-Type: application/json

{
    "credit_sms": 200,
    "credit_sms_last_used": "2015-05-14 14:17:15"
}
HTTP/1.1 404 NOT FOUND
Content-Type: application/json

{
    "status": "FAILED",
    "errors": [
        {
            "error_code": "NOT_FOUND",
            "parameter": "customer_id",
            "data": "12345678-1234-1234-1234-123456789012",
            "message": "Account not found"
        }
    ]
}

Services Overview

GET /v1/account/services

This method returns details of services associated with your account.

GET /v1/account/services HTTP/1.1
Host: api.xonadu.com
Cache-Control: private, max-age=0, no-cache
Authorization: ApiKey live-7f3-61f6-11e5-92cb-064b2c914051
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "service_id": "TEST1",
        "description": "Xonadu example service 1",
        "date_created": "2014-11-11 16:22:20",
        "active": true
    },
    {
        "service_id": "TEST2",
        "description": "Xonadu example service 2",
        "date_created": "2014-12-01 14:41:51",
        "active": false
    }
]
HTTP/1.1 404 NOT FOUND
Content-Type: application/json

{
    "status": "FAILED",
    "errors": [
        {
            "error_code": "NOT_FOUND",
            "parameter": "customer_id",
            "data": "12345678-1234-1234-1234-123456789012",
            "message": "Account not found"
        }
    ]
}

One Time Password

POST /v1/otp

Generate and dispatch ont time passwords to your users. Successful calls to this method will dispatch SMS to the mobile networks immediately if sufficient credit is available on your account.

How it Works

We generate a password based on the preferences set in your request. The password is placed into your content template and dispatched to the users handset. You will need to capture the response value and cache it with the users login session to allow you to perform validation when the user enters their code. We leave it up to you to handle timeouts and password complexity in order to provide the simplest solution which should be relatively easy to integrate into your platform.

POST /v1/otp HTTP/1.1
Host: api.xonadu.com
Authorization: ApiKey live-7f3-61f6-11e5-92cb-064b2c914051
Content-Type: application/json
Cache-Control: no-cache
Content-Length: 75

{
    "uri": "07500000000",
    "length": 10,
    "format": "alphanumeric"
}
HTTP/1.1 202 ACCEPTED
Content-Type: application/json

{
    "status": "OK",
    "otp": "5PUPFL",
    "sms_body": "Your OTP code is 5PUPFL. This service is provided by xonadu.com",
    "uri": "+447500000000",
    "credits_remaining": 1000,
    "timestamp": "20160219101337"
}
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json

{
    "status": "FAILED",
    "errors": [
        {
            "error_code": "INVALID_DATA",
            "parameter": "uri",
            "data": "075000012340000",
            "message": "Destination not recognised"
        }
    ]
}
Name Required Type Description
uri 1 string Destination mobile number for this message. UK & ROI only. Expects national and E164 formats.
length int Sets the password length between 4 and 12 characters (default: 6)
format string Set the charset for the password generation. Options are "alpha", "alphanumeric", "numeric" and "hex" (default: "numeric")
template string The content of your message, up to 160 characters (including password). Must include a password placeholder in format [OTP]. (default: "Your OTP code is [OTP]. This service is provided by xonadu.com")

Notifications

You are able to receive notifications whenever an SMS is delivered or responded to.

Delivery Receipts

When a message has been sent via the API (one-way or two-way) you can request a notification of the delivery receipt arriving on our network. Delivery receipts are the response sent to us by the mobile network operators when a message has been accepted or refused by a handset.

Delivery receipts will inform you of completed message sessions which may have been successful or failures. It is therefore important for your application to understand the meaning of the various receipts codes in order to take appropriate action.

The notification structure is shown below (all notifications are formatted as JSON POST events):

POST / HTTP/1.1
Host: receipts.example.com
Cache-Control: private, max-age=0, no-cache
Content-Type: application/json

{
    "request_id": "fd1d4bfb-60b7-4c71-ba2f-c2005f98a641",
    "request_date": "2015-12-17 13:59:36",
    "message": {
        "message_id": "8b807935-d911-433c-9387-0c1b40ec724a",
        "status": "DELIVERED",
        "destination": "+447538232754",
        "receipt_date": "2015-12-17 13:59:39",
        "originator": "+447860062130"
    },
    "client_ref": "example_reference",
    "body": "Two way SMS - sent with the Xonadu API"
}

Delivery Status List

We provide both positive and negative receipt values and expose the session result to the client application to allow further processing. A complete list of delivery statuses are shown in the list below:

Status Description
DELIVERED Your message was successfully delivered to the handset
NO_CREDIT The mobile operator requires this handset to have more credit before messages can be delivered
FAILED The mobile network failed to deliver the message
TIMEOUT The message was not delivered before the mobile network timeout period has elapsed. Handset may be switched off.
UNKNOWN The mobile network failed to deliver the message for an unknown reason

Message Replies

This is only relevant for users of two-way messaging where recipients have the ability to reply. When using this method you specify an address for us to contact whenever a reply is received.

When a message has been sent via the API you can request a notification of any SMS reply messages. We provide the original message object and details of the reply message including the message content.

The notification structure is shown below (all notifications are formatted as JSON POST events):

POST / HTTP/1.1
Host: reply.example.com
Cache-Control: private, max-age=0, no-cache
Content-Type: application/json

{
    "request_id": "fd1d4bfb-60b7-4c71-ba2f-c2005f98a641",
    "request_date": "2015-12-17 13:59:36",
    "message": {
        "message_id": "8b807935-d911-433c-9387-0c1b40ec724a",
        "status": "DELIVERED",
        "destination": "+447538232754",
        "receipt_date": "2015-12-17 13:59:39",
        "originator": "+447860062130"
    },
    "reply": {
        "message_id": "8777183d-39bc-478e-b345-b9fe58d88b5f",
        "destination": "+447860062130",
        "receive_date": "2015-12-17 13:59:54",
        "originator": "+447538232754",
        "body": "my reply body"
    },
    "client_ref": "example_reference",
    "body": "Two way SMS - sent with the Xonadu API"
}

Error Handling

Error Object

Your requests may encounter errors for many reasons and we aim to respond with information which allows you to easily and automatically detect and correct these issues. Our error object has a consistent format where one or more errors can be reported in a simple array of uniform error objects. This can be seen in the example below:

HTTP/1.1 404 NOT FOUND
Content-Type: application/json

{
    "status": "FAILED",
    "errors": [
        {
            "error_code": "INVALID_DATA",
            "parameter": "delivery_url",
            "data": "www.test.com",
            "message": "Delivery URL is not valid (must include protocol)"
        },
        {
            "error_code": "TOO_MANY_CHARACTERS",
            "parameter": "originator",
            "data": "01234657890123465789",
            "message": "Invalid origination URI, exceeded 15 character limit"
        }
    ]
}

You can prepare your application to expect the following potential error messages:

Status Description
PARAM_MISSING Required parameter was missing from the request
IS_EMPTY Required parameter was present but not set
INVALID_DATA The data provided was invalid for this parameter
NO_CREDIT Not enough credit on this account to fulfil the request
TOO_MANY_DESTINATIONS Customer destination limit was breached
TOO_MANY_CHARACTERS Data length was too great and would be truncated
NOT_FOUND Requested object was not found
TOO_FEW_CHARACTERS Data length was too short for the use case
BAD_ROUTE (internal) Trusted service user selected invalid dispatch route
TOO_MANY_PAIRS We couldn’t find a spare asset for pairing service
}