HTTP REST

Our HTTP REST service is available to you immediately after creating an account on our web site.

Introduction

Our REST Messaging API is designed to be a simple and powerful tool for large scale messaging with features such as:

  • Send one message to many recipients.
  • Send text messages with up to 1600 characters.
  • Collect your frequent recipients into groups.
  • Scheduling enables you to create a message to be sent at a later time.
  • Customize your message for each recipient using parameterization.
  • MO support for receiving messages from end users

Getting started

Service Plan

To use the REST API you first need to create an HTTP REST Service using the web portal. You can have multiple service plans and each one will be isolated from any other. Meaning that messages, groups or other resources cannot be reused between service plans.

Authentication

Request with token

$ curl -H "Authorization: Bearer {token}" \
"https://api.clxcommunications.com/xms/v1/{service_plan_id}/batches"

For each service plan you will be provided with an authentication token. The token is required for all requests made to the REST API.

The token is sent in the Authorization header preceded by Bearer.

Rate limit

Each service plan comes with a rate limit which sets the maximum number of messages that can be sent per second. The rate limit is per actual message so a batch with 10 recipients will count as 10 messages.

Each service plan gets it’s own message queue served in First-In-First-Out order. This means that new batches will be accepted immediately but might be delayed if earlier batches are still on queue.

Formats

This section will take a brief look at some of the formats used in the REST API.

JSON

JSON (application/json) is the content type of both requests and responses if not otherwise specified.

Requests with invalid JSON will be rejected.

Null values can be omitted in requests and will be omitted in responses. In some cases explicitly setting null will overwrite a previously set value with null. See Update a group for an example.

MSISDN

Only MSISDNs in international format are accepted by the API.

MSISDNs can be sent in with or without a leading “+” (i.e. +123456789 or 123456789) or with a leading “00”. Any spaces, dashes or brackets, will also be be ignored by the API.

All MSISDNs returned by the REST API will be without a “+” or “00” prefix, even if they were sent in with one.

Timestamp

Timestamps are used for expressing a moment in time. For example the send_at and expire_at parameters in the Send a batch message operation.

Timestamps are represented using ISO-8601 standard (see http://en.wikipedia.org/wiki/ISO_8601).

All timestamps returned by the batch will be in UTC with millisecond precision.

Time zone can be specified in accordance with ISO-8601. If no time zone offset is specified (local time in ISO-8601) then UTC will be used.

HTTP Status Codes

The REST API returns an HTTP status and code each time a request is made.

HTTP Statuses

The following HTTP status codes are used by the API. Additional codes might be added in the future and if you encounter a code not in this list please consult the HTTP specification for a definition.

Status Description
200 OK The request was successful.
201 Created The request was successful and a new resource was created.
201 Created The request was successful and a new resource was created.
400 Bad Request The request does not conform to the API. The request body should provide more information.
401 Unauthorized Authentication token is invalid for this service plan.
403 Forbidden The request syntax is valid but cannot be performed. This could for example be because a referenced resource doesn’t exist.
404 Not Found The path is invalid or no resource exists with the given ID.
405 Method Not Allowed The path is valid but not for this method.
415 Unsupported Media Type The request Content-Type is missing or unsupported. Most operations expect application/json.
500 Internal Server Error An unexpected internal error occurred and the request was not processed.
503 Service Unavailable The service is unable to perform the request at this point. Most likely due to a required subsystem being unavailable.

HTTP Errors

Responses with status 400 Bad Request and 403 Forbidden the body is a JSON object explaining the error. It has the following parameters:

Name Description JSON Type
code A code that can be used to programmatically recognize the code. String
text Human readable description of the error. Can be used for debugging String

The following HTTP error codes are available:

HTTP Status Code Description
400 syntax_invalid_json The request JSON is invalid or does not conform to the API specification.
400 syntax_invalid_parameter_format The format of a parameter is invalid. For example if an MSISDN is not possible formatted.
400 syntax_constraint_violation The request body doesn’t fulfill all of the constraints set by the API. For example if a required parameter is missing.
403 unknown_group A referenced group ID is unknown. This could happen if the ID is invalid or if the group has been deleted.
403 unknown_campaign The campaign ID does not match the specified originator.
403 missing_callback_url Callback has been requested but no URL is provided.

Callback

A callback is a HTTP POST request with a notification made by the REST API to a URI of your choosing. The REST API expects the receiving server to respond with a response code within the 2xx Success range. If no successful response is received then REST API will either schedule a retry if the error is expected to be temporary or discard the callback if the error seems to be permanent.

Delivery report callback

A delivery report contains the status and status code for each recipient of a batch. To get a delivery report callback for a batch you need to set the delivery_report field accordingly when Send a batch message. The formats of the different types of delivery reports are described in Retrieve a delivery report and in Retrieve a recipient delivery report.

The callback URL can either be provided in the Send a batch message or provisioned for your account.

Inbound message callback

An inbound message or MO (Mobile Originated) is a message sent to one of your shortcodes or longnumbers. The format of an inbound callback is described in Inbounds endpoint.

To receive inbound message callbacks a URL needs to be provisioned for your account.

Message Body

When entering the message body in the batch request, the characters used, as well as the length of the message, will affect how many SMS messages are sent out. The length of the message will also include the parameter values entered, if utilizing Parameterization.

Supported Characters

The characters used in the message will determine the type of encoding which needs to be used in the SMS message. The API automatically detects the encoding required for the characters used, which allows us to support the delivery of SMS in any language.

Basic Character Set

The following characters will be sent as plain text 7-bit encoding, which allows us to send up to 160 characters per SMS message.

@ Δ SP 0 ¡ P ¿ p
£ _ ! 1 A Q a q
$ Φ 2 B R b r
¥ Γ # 3 C S c s
è Λ ¤ 4 D T d t
é Ω % 5 E U e u
ù Π & 6 F V f v
ì Ψ 7 G W g w
ò Σ ( 8 H X h x
Ç Θ ) 9 I Y i y
LF Ξ * : J Z j z
Ø + ; K Ä k ä
ø Æ , < L Ö l ö
æ - = M Ñ m ñ
Å ß . > N Ü n ü
å É / ? O § o à
LF is the Line Feed character - for JSON format, enter this as \n
SP is the Space character

Extended Character Set

The following characters are also available, but they take up two characters in the SMS message rather than one

| , ^ , , { , } , [ , ] , ~ , \

Other Characters

If other characters are required for different languages, Unicode encoding will be used. This allows up to 70 characters per SMS message.

Long Messages

The message body in a batch request can contain up to 1600 characters. Depending on the characters used in the message, this will equate to the following numbers of SMS messages.

Using 7-bit Characters:

Message Length Number of SMS Parts
1 - 160 1
161 - 304 2
305 - 456 3
457 - 608 4
609 - 760 5
761 - 912 6
913 - 1064 7
1065 - 1216 8
1217 - 1368 9
1269 - 1520 10
1521 - 1600 11

Each SMS in a multi-part 7-bit encoded message, has a maximum of 152 characters.

Using Unicode Characters:

Message Length Number of SMS Parts
1 - 70 1
71 - 132 2
133 - 198 3
199 - 264 4
264 - 330 5
331 - 396 6
396 - 462 7
463 - 528 8
529 - 594 9
595 - 660 10
661 - 726 11
727 - 792 12
792 - 858 13
859 - 924 14
925 - 990 15
991 - 1056 16
1057 - 1122 17
1123 - 1188 18
1189 - 1254 19
1255 - 1320 20
1321 - 1386 21
1387 - 1452 22
1453 - 1518 23
1519 - 1584 24
1585 - 1600 25

Each SMS in a multi-part Unicode encoded message, has a maximum of 66 characters.

Parameterization

Parameterization enables you to customize parts of a message for each recipient.

This is done by defining a parameter key and placing it in the message body. For each parameter key, a recipeint and parameter value must be provided. The position of a parameter in a message, is defined by entering ${parameter_key} in the message body, where parameter_key is the name of the parameter.

For example the message body Hi ${name}! How are you? contains the parameter key: “name”. This would be replaced according to the rules specified in the parameters field in the Send a batch message operation.

A default parameter value can be specified that will be used when an MSISDN is not listed for a particular parameter. To set this, identify a recipient as default for each parameter key.

If a target MSISDN is missing in the parameters object and no default value has been defined for that parameter the message will fail for that MSISDN but not for the rest of the batch.

Parameter keys are case sensitive.

Delivery Reports

The REST API uses message statuses and error codes in delivery reports, which refer to the state of the SMS batch and can be either Retrieve a delivery report or sent to a Callback.

This section describes the statuses and codes returned in those delivery reports.

Delivery Report Statuses

The status field describes which state a particular message is in. Please note that statuses of type Intermediate will only be reported if you submit a status per recipient report request (Retrieve a recipient delivery report), no callback will be made to report them. The following statuses are available when using the REST API:

Status Type Description
Queued Intermediate Message is queued within REST API system and will be dispatched according to the rate of the account.
Dispatched Intermediate Message has been dispatched and accepted for delivery by the SMSC.
Aborted Final Message was aborted before reaching SMSC.
Rejected Final Message was rejected by SMSC.
Delivered Final Message has been delivered.
Failed Final Message failed to be delivered.
Expired Final Message expired before delivery to SMSC. This may happen if the expiry time for the message was very short.
Unknown Final Message was delivered to SMSC but no Delivery Receipt has been received or a Delivery Receipt that could not be interpreted was received.

Delivery Report Error Codes

The delivery report status code provides a more detailed view of what happened with a message. The REST API shares most of it’s error codes with other SMS services.

These are defined here: Error Codes

In addition to these standard error codes, the REST API adds an additional set of error codes, all within the 4xx range (vendor specific errors in the range of 0x400 to 0x4FF as referenced in the SMPP specification). These are listed below:

Status code Name Status Description
400 Queued Queued Message is queued within REST API system and will be dispatched according to the rate of the account.
401 Dispatched Dispatched Message has been dispatched to SMSC.
402 Message unroutable Aborted SMSC rejected message. Retrying is likely to cause the same error.
403 Internal error Aborted An unexpected error caused the message to fail.
404 Temporary delivery failure Aborted Message failed because of temporary delivery failure. Message can be retried.
405 Unmatched Parameter Aborted One or more parameters in the message body has no mapping for this recipient.
406 Internal Expiry Aborted Message was expired before reaching SMSC. This may happen if the expiry time for the message was very short.
407 Canceled Aborted Message was canceled by user before reaching SMSC.

NB: new codes may be added over time.

Batches endpoint

The batches endpoint provides operations for sending batch messages, retrieving previously sent batches and retrieving delivery reports.

Send a batch message

The following operation will send a batch message.

Depending on the length of the body one message might be split into multiple parts and charged accordingly.

Any groups targeted in a scheduled batch will be evaluated at the time of sending. If a group is deleted between batch creation and scheduled date it will be considered empty.

Request

POST /xms/v1/{service_plan_id}/batches

JSON body parameters:

Name Description JSON Type Default Constraints Required
to List of MSISDNs and group IDs that will receive the batch String array N/A 1 to 100 elements Yes
from Sender number String N/A Must be valid MSISDN, short code or alphanumeric. Yes
type Identifies the type of batch message String mt_text Valid types are mt_text and mt_binary Yes
body The message content. Normal text string for mt_text and Base64 encoded for mt_binary String N/A Max 1600 chars for mt_text and max 140 bytes together with udh for mt_binary Yes
udh The UDH header of a binary message HEX encoded string N/A Max 140 bytes together with body If type is mt_binary
campaign_id The campaign/service ID this message belongs to. US only. String N/A None No
delivery_report Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting String none Valid types are none, summary, full and per_recipient Yes
send_at If set in the future the message will be delayed until send_at occurs ISO-8601 string Now Must be before expire_at. If set in the past messages will be sent immediately. No
expire_at If set the system will stop trying to deliver the message at this point ISO-8601 string 3 days after send_at Must be after send_at No
callback_url Override the default callback URL for this batch URL string N/A Must be valid URL. Max 2048 characters long No
parameters Contains the parameters that will be used for customizing the message for each recipient Object N/A Not applicable to if type is mt_binary No
parameters.{parameter_key} The name of the parameter that will be replaced in the message body String N/A Letters A-Z and a-z, digits 0-9 and .-_ allowed. Max 16 characters long No
parameters.{parameter_key}.{msisdn} The recipient that should get this value String N/A Max 160 characters long No
parameters.{parameter_key}.default The fall back value for omitted recipient MSISDNs String None Max 160 characters long No

Send message to two recipients.

curl -X POST \
         -H "Authorization: Bearer {token}" \
         -H "Content-Type: application/json"  -d '
          {
                  "from": "12345",
                  "to": [
                          "123456789",
                          "987654321"
                  ],
                  "body": "Hi there! How are you?"
          }' \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/batches"

Response

201 Created

The batch was successfully created. The JSON response object contains the request parameters as well as the following additional parameters:

Name Description JSON Type
id Unique identifier for batch String
created_at Timestamp for when batch was created. ISO-8601 String
modified_at Timestamp for when batch was last updated. ISO-8601 String
canceled Indicates if the batch has been canceled or not. Boolean

NB A valid batch request will still be accepted and receive a successful “Created” response, regardless of your account balance. If your available credit reaches zero during dispatch of the batch, individual messages will begin to fail part way through. This means a batch may be only partially completed if your account balance is not high enough at the time of sending.

400 Bad Request

There was an error with your request. The body is a JSON object described in HTTP Status Codes. Possible error codes include syntax_invalid_json, syntax_invalid_parameter_format and syntax_constraint_violation.

403 Forbidden

The system was not able to fulfill your request. The body is a JSON object described in HTTP Status Codes. Possible error codes include unknown_group**m **unknown_campaign and missing_callback_url.

Response for a successfully created batch message.
{
        "from": "12345",
        "to": [
                "123456789",
                "987654321"
        ],
        "body": "Hi there! How are you?",
        "id": "{batch_id}",
        "created_at": "2014-10-02T09:34:28.542Z",
        "modified_at": "2014-10-02T09:34:28.542Z",
        "canceled": "False"
}
Send scheduled batch message with expiry.
curl -X POST \
         -H "Authorization: Bearer {token}" \
         -H "Content-Type: application/json"  -d '
          {
                  "from": "12345",
                  "to": [
                          "123456789",
                          "987654321"
                  ],
                  "body": "Hi there! How are you?",
                  "send_at": "2014-10-02T09:30Z",
                  "expire_at": "2014-10-02T12:30Z"
          }' \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/batches"
Send batch message with custom delivery report URL
curl -X POST \
         -H "Authorization: Bearer {token}" \
         -H "Content-Type: application/json"  -d '
          {
                  "from": "12345",
                  "to": [
                          "123456789",
                          "987654321"
                  ],
                  "body": "Hi there! How are you?",
                  "delivery_report": "summary",
                  "callback_url": "http://www.example.com"
          }' \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/batches"
Send parameterized message. 123456789 will get the message Hi Joe! How are you? while 987654321 will get Hi there! How are you?
curl -X POST \
         -H "Authorization: Bearer {token}" \
         -H "Content-Type: application/json"  -d '
          {
          "from": "12345",
          "to": [
                  "123456789",
                  "987654321"
           ],
          "body": "Hi ${name}! How are you?",
          "parameters": {
                  "name": {
                          "123456789": "Joe",
                          "default": "there"
                   }
          }
  }' \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/batches"

Cancel batch message

A batch can be canceled at any point. If a batch is canceled while it’s currently being delivered some messages currently being processed might still be delivered. The delivery report will indicate which messages were canceled and which weren’t.

Canceling a batch scheduled in the future will result in an empty delivery report while canceling an already sent batch would result in no change to the completed delivery report.

Request

DELETE /xms/v1/{service_plan_id}/batches/{batch_id}

Response

200 OK

The response is a JSON object described in Send a batch message.

Cancel a batch message.

curl-X DELETE \
   -H "Authorization: Bearer {token}" \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/batches/{batch_id}"

List batch messages

With the list operation you can list all batch messages that you have created. This operation supports pagination.

Batches are returned in reverse chronological order.

Request

GET /xms/v1/{service_plan_id}/batches

Query parameters:

Name Description Type Default Constraints Required
page The page number starting from 0 Integer 0 0 or larger No
page_size Determines the size of a page Integer 30 Max 100 No
from Only list batches set from this originator. Multiple originators can be comma separated MSISDN, short code or alphanumeric No No  
start_date Only list batches created at or after this date time ISO-8601 No Must be valid ISO-8601 string No
end_date Only list batches created before this date time ISO-8601 No Must be valid ISO-8601 string No

Response

200 OK

Name Description JSON Type
page The requested page Integer
page_size The number of batches returned in this request Integer
count The total number of batches matching the given filters Integer
batches The page of batches matching the given filters Array of objects described in [Send a batch message](#send-a-batch-message)

Retrieve a batch message

This operation retrieves a specific batch with the provided batch ID.

Request

GET /xms/v1/{service_plan_id}/batches/{batch_id}

Response

200 OK

The response is a JSON object described in Send a batch message response.

404 Not Found

If the batch ID is unknown to the system.

Retrieve a batch
curl -H "Authorization: Bearer {token}" \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/batches/{batch_id}"
Retrieve the first 30 batches
curl -H "Authorization: Bearer {token}" \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/batches"
Retrieve the third page of batches with a page size of 50
curl -H "Authorization: Bearer {token}" \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/batches?page=2&page_size=50"
Retrieve batches created on June 23rd, 2014 UTC.
curl -H "Authorization: Bearer {token}" \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/batches?start_date=20140623TZ&end_date=20140624TZ"
Retrieve the batches sent from 12345 or 54321.
curl -H "Authorization: Bearer {token}" \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/batches?from=12345,54321"

Retrieve a delivery report

Delivery reports can be retrieved even if no callback was requested. The difference between a summary and a full report is only that the full report contains the actual MSISDNs for each status code.

Request

GET /xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report

Query parameters:

Name Description Type Default Constraints Required
type The type of delivery report String summary Must be summary or full Yes

Response

200 OK

The response is a JSON object with the following parameters:

Name Description JSON Type
type The object type. Will always be delivery_report_sms String
batch_id The ID of the batch this delivery report belongs to String
total_message_count The total number of messages for the batch String
statuses Array with status objects. Only status codes with at least one recipient will be listed. Object
statuses.code The detailed status code. See Error Codes Integer
statuses.status The simplified status as described in Delivery Report Statuses String
statuses.count The number of messages that currently has this code. Will always be at least 1 Integer
statuses.recipients Only for full report. A list of the MSISDN recipients which messages has this status code. String array

404 Not Found

The batch ID is not known to the system or the delivery report type is not recognized.

Request summary report
curl -H "Authorization: Bearer {token}" \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report"
Summary report response
{
        "type": "delivery_report_sms",
        "batch_id": "{batch_id}",
        "total_message_count": 3,
        "statuses": [
                {
                        "code": 400,
                        "status": "Queued",
                        "count": 1
                },
                {
                        "code": 0,
                        "status": "Delivered",
                        "count": 2
                }
        ]
}
Request full report
curl -H "Authorization: Bearer {token}" \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report?type=full"
Full report response
{
        "type": "delivery_report_sms",
        "batch_id": "{batch_id}",
        "total_message_count": 3,
        "statuses": [
                {
                        "code": 400,
                        "status": "Queued",
                        "count": 1,
                        "recipients": [
                                "123456789"
                        ]
                },
                {
                        "code": 0,
                        "status": "Delivered",
                        "count": 2,
                        "recipients": [
                                "987654321",
                                "123459876"
                        ]
                }
        ]
}

Retrieve a recipient delivery report

A recipient delivery report contains the message status for a single recipient MSISDN.

Request

GET /xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report/{recipient_msisdn}

Request report for 123456789

curl -H "Authorization: Bearer {token}" \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report/123456789"

Response

Recipient delivery report for 123456789

{
        "type": "recipient_delivery_report_sms",
        "batch_id": "{batch_id}",
        "recipient": "123456789",
        "code": "0",
        "status": "Delivered",
        "at": "2016-10-02T09:34:18.542Z",
        "operator_status_at": "2016-10-02T09:34:18.101Z"
}

200 OK

The response is a JSON object with the following parameters:

Name Description JSON Type
type The object type. Will always be _recipient_delivery_report_sms String
batch_id The ID of the batch this delivery report belongs to String
recipient The recipient MSISDN String
code The detailed status code. See Error Codes Integer
status The simplified status as described in Delivery Report Statuses String
status_message A description of the status, if available. String
at A timestamp of when the Delivery Report was created in the CLX service ISO-8601 String
operator_status_at A timestamp extracted from the Delivery Receipt from the originating SMSC ISO-8601 String

404 Not Found

The batch ID is not known to the system or the recipient is not a target of this batch.

Receiving delivery report callbacks

Delivery report callbacks will be received for batches where delivery_report parameter is set to summary, full or per_recipient.

If no callback_url was specified for the batch then the default callback URL for the given service plan will be used.

Summary and full

If a batch was created with a request for full or summary delivery report then one callback will be made to the specified callback URL when all messages in the batch (which may be one message) are either delivered, failed or expired. If you want to know the delivery status for a message before all messages are completed then you can always use Retrieve a delivery report at any time.

The format for summary and full reports is the same as the Retrieve a delivery report response. The difference being that when full is requested a list of phone numbers / recipients per delivery status is provided.

Per recipient

If a batch was created with a request for per_recipient delivery_report then a callback will be made for each status change of a message. This could result in a lot of callbacks and should be used with caution for larger batches. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC.

Inbounds endpoint

Inbounds, or Mobile Originated messages, are incoming messages. Inbound messages can be listed and retrieved like batch messages and they can also be delivered by callback requests like delivery reports.

Name Description JSON Type
type The object type. Either mo_text or mo_binary. String
id The ID of this inbound message. String
from The originator MSISDN. String
to The destination MSISDN or short code. String
body Message body, Base64 encoded if type is mo_binary. String
operator The MCCMNC of the sender’s operator if known. String
sent_at When the message left the originating device. Only available if provided by operator. ISO-8601 String
received_at When the system received the message. ISO-8601 String

NB: The operator is only available for MOs sent to short codes.

List inbound messages

Retrieve the first 30 inbound messages.
curl -H "Authorization: Bearer {token}" \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/inbounds"
Retrieve the third page of inbound messages with a page size of 50.
curl -H "Authorization: Bearer {token}" \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/inbounds?page=2&page_size=50"
Retrieve inbound messages received on June 23rd, 2014 UTC.
curl -H "Authorization: Bearer {token}" \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/inbounds?start_date=20140623TZ&end_date=20140624TZ"
Retrieve the batches sent to 12345 or 54321.
curl -H "Authorization: Bearer {token}" \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/inbounds?to=12345,54321"

With the list operation you can list all inbound messages that you have received. This operation supports pagination.

Inbounds are returned in reverse chronological order.

Request

GET /xms/v1/{service_plan_id}/inbounds

Query parameters:

Name Description Type Default Constraints Required
page The page number starting from 0 Integer 0 0 or larger No
page_size Determines the size of a page Integer 30 Max 100 No
to Only list messages set to this destination. Multiple destinations can be comma separated. MSISDN or short code No No No
start_date Only list messages received at or after this date time. ISO-8601 No Must be valid ISO-8601 string No
end_date Only list messages received before this date time. ISO-8601 No Must be valid ISO-8601 string No

Response

200 OK

Name Description JSON Type
page The requested page Integer
page_size The number of inbounds returned in this request Integer
count The total number of inbounds matching the given filters Integer
inbounds The page of inbounds matching the given filters Array of objects described in [Inbounds endpoint](#inbounds-endpoint)

Retrieve inbound message

Retrieve an inbound message

This operation retrieves a specific inbound message with the provided inbound ID.

Request

GET /xms/v1/{service_plan_id}/inbounds/{inbound_id}

Response

200 OK

The response is a JSON object described in Inbounds endpoint response.

404 Not Found

If the inbound ID is unknown to the system.

curl -H "Authorization: Bearer {token}" \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/inbounds/{inbound_id}"

Groups endpoint

A group is a set of MSISDNs that can be used as a target in the Send a batch message operation. An MSISDN can only occur once in a group and any attempts to add a duplicate would be ignored but not rejected.

Groups can be combined with Parameterization. All group members will be resolved in the same manner as MSISDNs listed in the to-field itself.

Create a group

There are a three different ways to create groups:

  1. members - use a list of MSISDNs
  2. auto_update - automatically update the group based on MO replies
  3. child_groups - collect one or more groups under a single ‘parent’ group

One or more of these methods, can be used to create and maintain a group.

In addition to this, one or more tags may be applied to a group, to make it easier to identify and manage multiple groups with matching tags.

A unique name can also be optionally applied to a group if desired.

Request

POST /xms/v1/{service_plan_id}/groups

JSON object parameters:

Name Description JSON Type Default Constraints Required
name Name of the group. String N/A Max 20 characters No
members Inital list of MSISDNs for the group String array N/A Elements must be MSISDNs. Max 10,000 elements No
child_groups MSISDNs of child group will be included in this group. String array N/A Elements must be group IDs. Max 10 elements No
auto_update If present then this group will be auto populated.   N/A   No
auto_update.to Short code or long number addressed in MO.   N/A   No
auto_update.add     N/A   No
auto_update.add.first_word     N/A   No
auto_update.add.second_word     N/A   No
auto_update.remove     N/A   No
auto_update.remove.second_word     N/A   No
auto_update.remove.first_word     N/A   No
tags Tags can be used to make it easier to find the group later. String array N/A   No

Response

201 Created

The response body is a JSON object with the following parameters:

Name Description JSON Type
id The ID used to reference this group String
name Name of group if set String
size The number of members currently in the group Integer
created_at Timestamp for when the group was created. ISO-8601 String
modified_at Timestamp for when the group was last modified. ISO-8601 String

400 Bad Request

There was an error with your request. The body is a JSON object described in HTTP Status Codes. Possible error codes include syntax_invalid_json, syntax_invalid_parameter_format and syntax_constraint_violation.

403 Forbidden

The system was not able to fulfill your request. The body is a JSON object described in HTTP Status Codes. Possible error codes include conflict_group_name.

Create a group named My group with two members.
curl -X POST \
         -H "Authorization: Bearer {token}" \
         -H "Content-Type: application/json"  -d '
          {
                  "members": [
                          "123456789",
                          "987654321"
                  ],
                  "name": "My group",
                  "tags": [
                        "Examples",
                        "MembersGroup"
                        ]
}' \
Create auto update group for members sending MOs to 443456789012: keyword JOIN will add them to the group, keyword STOP will remove them from the group.
curl -X POST \
         -H "Authorization: Bearer {token}" \
         -H "Content-Type: application/json"  -d '
          {
                  "name": "My auto group",
                  "auto_update": {
                                "to": "443456789012",
                                        "add": {
                                                "first_word": "join"
                                        },
                                        "remove": {
                                                "first_word": "stop"
                                        }
                                },
                  "name": "My group",
                  "tags": [
                        "Examples",
                        "AutoGroup"
                        ]
}' \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/groups"
Create auto update group for shared short code 54321 with keyword CLX: if followed by JOIN will add them to the group, if followed by LEAVE will remove them from the group. Please note that keywords are not case sensitive so Clx, CLx, CLX and other permutations will all be treated the same.
curl -X POST \
         -H "Authorization: Bearer {token}" \
         -H "Content-Type: application/json"  -d '
          {
                  "name": "My auto group 2",
                  "auto_update": {
                                "to": "54321",
                                        "add": {
                                                "first_word": "Clx",
                                                "second_word": "Join"
                                        },
                                        "remove": {
                                                "first_word": "CLX",
                                                "second_word": "leave"
                                        }
                                },
                  "name": "My group",
                  "tags": [
                        "Examples",
                        "AutoGroupSSC"
                        ]
}' \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/groups"
Create a parent group that includes all members of groups with ID dxCJTlfb1UsF and yiinTKVNAEAu.
curl -X POST \
         -H "Authorization: Bearer {token}" \
         -H "Content-Type: application/json"  -d '
          {
                  "name": "My groups collection",
                  "child_groups": [
                                "dxCJTlfb1UsF",
                                "yiinTKVNAEAu"
                  ],
                  "name": "My group",
                  "tags": [
                        "Examples",
                        "ParentGroup"
                        ]
}' \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/groups"

List groups

With the list operation you can list all groups that you have created. This operation supports pagination.

Groups are returned in reverse chronological order.

Request

GET /xms/v1/{service_plan_id}/groups

Query parameters:

Name Description Type Default Constraints Required
page The page number starting from 0 Integer 0 0 or larger No
page_size Determines the size of a page Integer 30 Max 100 No
tags Comma separated list of tags that listed groups should match. String Array N/A   No

Response

200 OK

Name Description JSON Type
page The requested page Integer
page_size The number of groups returned in this request Integer
count The total number of groups Integer
groups The page of groups matching Array of objects described in [Create a group](#create-a-group)
Retrieve the first 30 groups
curl -H "Authorization: Bearer {token}" \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/groups"
Retrieve the third page of groups with a page size of 50
curl -H "Authorization: Bearer {token}" \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/groups?page=3&page_size=50"
Retrieve the first 30 groups with tag “Examples”
curl -H "Authorization: Bearer {token}" \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/groups?tags=Examples"

Retrieve a group

This operation retrieves a specific group with the provided group ID.

Request

GET /xms/v1/{service_plan_id}/groups/{group_id}

Response

200 OK

The response is a JSON object described in Create a group response.

404 Not Found

If the group ID is unknown to the system.

Retrieve a group

curl -H "Authorization: Bearer {token}" \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/groups/{group_id}"

Retrieve the members of a group

This operation retrieves the members of the group with the provided group ID.

Request

GET /xms/v1/{service_plan_id}/groups/{group_id}/members

Response

200 OK

The response is a JSON array with MSISDNs.

404 Not Found

If the group ID is unknown to the system.

Retrieve group members

curl -H "Authorization: Bearer {token}" \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/groups/{group_id}/members"

Update a group

With the update group operation you can add and remove members to an existing group as well as rename the group.

The request will not be rejected for duplicate adds or unknown removes.

The adds will be done before the deletes so if an MSISDN is in both lists then it will not be part of the resulting group.

To remove an existing name set name explicitly to the JSON value null. Omitting name from the JSON body will leave the name unchanged.

Updating a group targeted by a batch message scheduled in the future is allowed and changes will be reflected until the batch is sent.

Request

POST /xms/v1/{service_plan_id}/groups/{group_id}

The request is a JSON object with the following parameters:

Name Description JSON Type Default Constraints Required
add MSISDNs to add as members. String Array N/A Elements must be MSISDNs. Max 10 000 elements. No
remove MSISDNs to remove from group. String Array N/A Elements must be MSISDNs. Max 10 000 elements. No
name Name of group. String N/A Max 20 characters. No
add_from_group Copy the members from the given group into this group. String N/A Must be valid group ID No
remove_from_group Remove members in the given group from group. String N/A Must be valid group ID No

Response

200 OK

The response is a JSON object described in Create a group response.

400 Bad Request

There was an error with your request. The body is a JSON object described in HTTP Status Codes. Possible error codes include syntax_invalid_json, syntax_invalid_parameter_format and syntax_constraint_violation.

403 Forbidden

One or more groups referenced in your request could not be found.

404 Not Found

If the group ID is unknown to the system.

Update a group by adding two new members and removing one existing.
curl -X POST \
         -H "Authorization: Bearer {token}" \
         -H "Content-Type: application/json"  -d '
          {
                  "add": [
                          "123456789",
                          "987654321"
                  ],
                  "remove": [
                          "432156789"
                  ]
}' \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/groups/{group_id}"
Rename a group without changing its members.
curl -X POST \
         -H "Authorization: Bearer {token}" \
         -H "Content-Type: application/json"  -d '
          {
                  "name": "New group name"
}' \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/groups/{group_id}"
Remove the current name of a group without changing its members.
curl -X POST \
         -H "Authorization: Bearer {token}" \
         -H "Content-Type: application/json"  -d '
          {
                  "name": null
}' \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/groups/{group_id}"

Replace a group

The replace operation will replace all parameters, including members, of an existing group with new values.

Replacing a group targeted by a batch message scheduled in the future is allowed and changes will be reflected when the batch is sent.

Request

PUT /xms/v1/{service_plan_id}/groups/{group_id}

JSON object parameters:

Name Description JSON Type Default Constraints Required
name Name of group. String N/A Max 20 characters. No
members The inital members of the group String array N/A Elements must be MSISDNs. Max 10,000 elements. Yes

Response

200 OK

The response is a JSON object described in Create a group response.

400 Bad Request

There was an error with your request. The body is a JSON object described in HTTP Status Codes. Possible error codes include syntax_invalid_json, syntax_invalid_parameter_format and syntax_constraint_violation.

403 Forbidden

The system was not able to fulfill your request. The body is a JSON object described in HTTP Status Codes. Possible error codes include conflict_group_name.

404 Not Found

If the group ID is unknown to the system.

Replace a group.

curl -X PUT \
         -H "Authorization: Bearer {token}" \
         -H "Content-Type: application/json"  -d '
          {
                  "members": [
                          "123456789",
                          "987654321"
                  ],
          "name": "New name"
}' \
  "https://api.clxcommunications.com/xms/v1/{service_plan_id}/groups/{group_id}"

Delete a group

Deletes a group from the system. Any message created for a deleted group will be rejected. If a group is deleted that’s part of the to-array of a message scheduled for the future then the group will be considered empty at the time of sending.

Request

DELETE /xms/v1/{service_plan_id}/groups/{group_id}

Response

200 OK

The group was successfully deleted.

404 Not Found

If the group ID is unknown to the system.

Delete a group

curl -X DELETE \
         -H "Authorization: Bearer {token}" \
         "https://api.clxcommunications.com/xms/v1/{service_plan_id}/groups/{group_id}"