SMS API (1.0.2)

Introduction

Messaging API allows you to send and receive text messages to users around the globe via multiple channels: SMS, Viber, Whatsapp.

If you use Postman, you can quickly test all of the API calls by importing this Postman collection:

Run in Postman

Overview

The SMS Connexion™ Messaging API is RESTful and is served only over HTTPS. It returns HTTP response codes to indicate errors. It also accepts and returns JSON in the HTTP body.

You can use your favorite HTTP/REST library for your programming language to consume our API, or you can use one of our SDKs.

General guidelines

  • Requests are sent over HTTPS.
  • Request and response bodies are JSON formatted.
  • Query parameters naming is snake_case (eg. short_response, start_date, end_date)
  • Request/response bodies parameters (from JSON objects) are camelCase (eg. phoneNumbers, allowInvalid)

Date Format

All dates are in UTC and the datetime format used is YYYY-MM-DD HH:MM:SS
e.g. 2021-07-12 14:54:13

Phone Number Format

All phone numbers should match the international format E.164, wich define that numbers are formatted with "+" sign, followed by the country code and the subscriber number and can have a maximum length of 15 digits.
e.g. +4915123xxxxxx for Germany, +3361231xxxx for France, +39312311xxxx for Italy

Country Format

All country names an country codes in this API are represented as two-letter country codes defined in ISO-3166 alpha 2 standard.
e.g. DE for Germany, FR for France, IT for Italy

Currency Format

The currency code is in ISO-4217 format. e.g. eur for Euro, usd for US Dollar

Authentication

All requests made to the API must be authenticated.

The API offers two methods of authentication: Oauth2 and API Key

BearerAuth

This security schema can be used to authenticate requests to API endpoints.
Authorization: Bearer REPLACE_ACCESS_TOKEN

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

ApiKeyAuth

This security schema can be used to authenticate requests to API endpoints. Use the following custom header: X-API-KEY: <API_KEY>

Security Scheme Type API Key
Header parameter name: X-API-KEY

BasicAuth

This security schema is used only for obtaining an Access Token from the authorization endpoint /oauth/token
Authorization: Basic ZDV....DJh //Base64 encoded <CLIENT_ID>:<CLIENT_SECRET>

Security Scheme Type HTTP
HTTP Authorization Scheme basic

Oauth2

The SMS.CX Messaging API supports the Oauth2 client credentials flow (RFC 6749).

The Oauth2 uses scopes to provide a certain rights management for specific endpoints. Please check the full list of available scopes.

Authenticating via Oauth2 method requires the following steps:

  1. Create a Client (or reffered as an Application) - you will get client_id and client_secret
  2. Generate an Access Token
  3. Make Authenticated Requests

1. Create a Client (or Application)

First go to the Admin Dashboard > HTTP API > Oauth2 and create a new Application (or Client).

*Admin Dashoard*

You will have to select the token expiration (1 day, 1 week or never) for all the access tokens issued by this Application, and to select the scopes allowed (sms, viber, whatsapp, groups, reports, etc.).

From the Admin Dashboard you will get the Application ID and Application Secret that will be used as parameters client_id and client_secret on the next step.

2. Generate an access token

To generate an access token your app makes a POST request to the Authorization endpoint /oauth/token, with the following parameters:

Parameter Type Description
client_id required Client ID
client_secret required Client secret
grant_type required Must be client_credentials
scope optional A url encoded list of space-delimited, case-sensitive strings. If left empty, the access token issued will be granted with all scopes (full privileges)

The POST request needs to use the HTTP Basic authentication scheme, by encoding client_id:client_secret string to Base64 string and use it in the header:

Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 

Alternatively, the authorization server supports including the client authentication in the request-body.

Including the client credentials in the request-body using the two parameters client_id and client_secret is not recommended and should be limited to apps/clients that are unable to directly utilize the HTTP Basic authentication scheme.

Example with client authentication as Basic Auth header [RECOMMENDED]

POST /oauth/token HTTP/1.1
Authorization: Basic client_id:client_secret (base64 encoded value)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Example with client authentication in request body

POST /oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&grant_type=client_credentials

The Authorization endpoint will validate the request and if successfull will respond with an access token:

An example successful response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token": "1d0d303679dba1135e372a9eccda02b0601eb4f9",
    "expires_in": 86400,
    "token_type": "Bearer",
    "scope": "sms viber whatsapp multichannel conversations reports groups originators templates shortlinks attachments optouts account applications numbers"
}

Note: Each scope represents a resource, an endpoint.

For example, if your access token does not have groups scope granted, then the resource /groups will not be available. If scopes sms, groups, templates are granted, then the access token can send SMS, create/edit/delete groups, add contacts to groups, create/edit/delete templates

3. Make authenticated requests

Once the access token is obtained, it has to be provided on each request as a bearer token within the Authorization http header (Bearer Token Usage RFC 6750).

Example using the access token as bearer authorization

POST /sms HTTP/1.1
Authorization: Bearer REPLACE_ACCESS_TOKEN
GET /groups HTTP/1.1
Authorization: Bearer REPLACE_ACCESS_TOKEN

If an access token is compromised, go to Admin Dashboard and revoke all tokens for that specific application. If needed, you can reset the application secret from the same section.


API Key

API keys, like access tokens, have a set of capabilities assigned to them. However, unlike access tokens wich provides more fine-grained access control and can have limited lifetime, API keys provides full access to all the account resources and are long-lived.

To authenticate an API request just add the custom header X-API-KEY to the request header.

You can generate and manage your API keys in the Admin Dashboard > HTTP API > API Keys.

*Admin Dashoard*

If an API Key is compromised, go to Admin Dashboard and deactivate or delete that API Key.


Successful requests

The API uses standard HTTP status codes to indicate the success or failure of the API calls.

Status code Description
200 OK The request has succeeded
201 Created This code indicates that the request led to the creation of a resource

In case of success the response body contains a JSON object with the following structure:

  • info - object of objects - contains information about the fetched/created resource, e.g. ids, summary of fetched/processed collections, etc.
  • data - array of objects - contains the collection of data fetched or processed

Request to get group details

GET /groups/4360975
Authorization: Bearer 202f9f782e***************a2e1ff58103b971

Response with info and data

200 OK
Content-Type: application/json

{
    "info": {
        "id": 17,
        "name": "My group 3",
        "totalPhoneNumbers": 3,
        "totalCost": 0.123,
        "totalOptouts": 1,
        "phoneNumbersByCountry": {
            "ES": 1,
            "FR": 1,
            "GB": 1
        },
        "createdAt": "2021-07-10 13:03:08"
    },
    "data": [
        {
            "id": 44631,
            "phoneNumber": "+33612935399",
            "countryIso": "FR",
            "firstName": "Anton",
            "lastName": "Maheu",
            "email": null,
            "field1": null,
            "field2": null,
            "field3": null,
            "field4": null,
            "field5": null,
            "groupId": 17,
            "optout": true,
            "dateAdded": "2021-07-10 13:03:09"
        },
        {
            "id": 44632,
            "phoneNumber": "+34612160806",
            "countryIso": "ES",
            "firstName": "Almanza",
            "lastName": "Quintero",
            "email": "almanza.quintero123@tempmail.com",
            "field1": null,
            "field2": null,
            "field3": null,
            "field4": null,
            "field5": null,
            "groupId": 17,
            "optout": false,
            "dateAdded": "2021-07-10 13:03:09"
        },
        {
            "id": 44633,
            "phoneNumber": "+447400547989",
            "countryIso": "GB",
            "firstName": "Hayden",
            "lastName": "Francis",
            "email": null,
            "field1": null,
            "field2": null,
            "field3": null,
            "field4": null,
            "field5": null,
            "groupId": 17,
            "optout": false,
            "dateAdded": "2021-07-10 13:03:09"
        }
    ]
}

Request to create new group of contacts

POST /groups
Content-Type: application/json
Authorization: Bearer 202f9f782e***************a2e1ff58103b971

{
    "name": "My new group"
}

Response only with info

201 Created
Content-Type: application/json

{
    "info": {
        "id": 18,
        "name": "My new group"
    }
}

Request to delete a shortlink

DELETE /shortlinks/xYuQ
Authorization: Bearer 202f9f782e***************a2e1ff58103b971

Response only with info

200 OK
Content-Type: application/json

{
    "info": {
        "id": "xYuQ"
    }
}

Errors

The API uses standard HTTP status codes to indicate the failure of and API request. The body of the error response will always be a JSON object in the following format:

HTTP/1.1 400 Bad Request

{
    "error": {
        "type": "invalid_param",
        "message": "The name is empty or parameter 'name' not set",
        "uri": "https://sms.cx/docs/api/errors",
        "code": 1204
    }
}

Description of error object

Property Type Description
type string The type of error returned (invalid_param, not_found, access_denied, invalid_client, insufficient_scope, etc)
message string A short, human-readable description of the error
uri string A URI reference in the documentation that provides further information
code integer An internal code of the error

There are some specific cases - when validating phone numbers - in wich the response body contains the error object plus the property invalid wich is an array with invalid phone numbers.

The endpoints that validate phone numbers at runtime and throw errors if invalid are:

  • /sms
  • /viber
  • /whatsapp
  • /multichannel
  • /groups/{groupId}

Note: Pparameter allowInvalid with value true can be used in the request body in order not to throw an error and continue execution. The valid phone numbers will be added to the group, the invalid numbers will be placed in the info.invalid object.

Request to add phone numbers to a group

POST /groups/4339812
Content-Type: application/json
Authorization: Bearer 202f9f782e***************a2e1ff58103b971

{
    "phoneNumbers": [
        "+336129353",
        "+33612970283",
        "+3361211",
        "+43664187834",
        "+41781218472",
        "+351912110421",
        "+4915123473140",
        "+4915123595",
        "+4915123966046"
    ]
}

Response only with error and invalid

400 Bad Request
Content-Type: application/json

{
    "error": {
        "type": "invalid_param",
        "message": "The phone numbers provided are invalid",
        "uri": "https://sms.cx/docs/api/errors",
        "code": 1210
    },
    "invalid": [
        "+336129353",
        "+3361211",
        "+4915123595"
    ]
}

SMS.CX Messaging API uses the HTTP status codes for errors:

For 4XX response there was some problem with your authentication, the privileges, the structure of your request or rate limited.

A 5XX response indicate an internal error occurred, you should retry your request with an exponential backoff method.

Error types

HTTP code Error type Description
400 invalid_param The parameters provided are invalid or are missing
400 duplicate_id The ID already exist (for shortlinks and attachments)
400 duplicate_value The value already exists
400 insufficient_credit Your account balance is too low for the request
400 otp_verified The OTP was already verified
400 otp_cancelled The OTP was canceled
400 otp_expired The OTP has expired
400 otp_failed The OTP failed (max attempts reached)
400 invalid_pin The PIN provided does not verify
400 invalid_body The request body did not contain valid JSON
400 invalid_request The request is missing a required parameter (grant_type)
400 invalid_scope The requested scope is invalid, unknown, or malformed
400 unsupported_grant_type The grant type is not supported (only client_credentials)
401 invalid_api_key The api key provided is not valid
401 invalid_client Your access token is not valid
403 no_coverage No coverage or restricted destination
403 access_denied The action is not allowed or not enough permission to perform
403 insufficient_scope The resource requested requires higher privileges than provided by the access token
404 not_found The ID provided does not exist
405 invalid_method The request method is not supported by the target resource
429 rate_limit The request was rate limited
500 server_error An internal server error occurred

Error codes

HTTP code Code Error type Description
400 1101 invalid_param The parameter groups is empty or not set
400 1102 invalid_param Group is empty
400 1103 invalid_param The phone numbers array is too big (max. allowed: 25000 numbers)
400 1104 invalid_param The parameter to is empty or not set
400 1105 invalid_param The parameter from is empty or not set
400 1106 invalid_param The parameter from is not valid (min 3, max 15 characters)
400 1107 invalid_param The parameter text is empty or not set
400 1108 invalid_param The parameter scheduledDate is not a valid date
400 1109 invalid_param The parameter dlrCallbackUrl is not a valid URL
400 1110 invalid_param Invalid alphabet. Must be one of: NONE, NON_GSM, RUSSIAN_CYRILLIC, BULGARIAN_CYRILLIC, UKRAINIAN_CYRILLIC, MACEDONIAN_CYRILLIC, BELARUSIAN_CYRILLIC, SERBIAN_CYRILLIC, POLISH, ROMANIAN, TURKISH, GREEK
400 1111 invalid_param Idempotency Id provided is not a valid UUID (v1-v5)
400 1112 invalid_param The shortlink/attachment ID provided for tracking is invalid or not found
400 1113 insufficient_credit Insufficient credit
400 1114 insufficient_credit Credit limit reached. To increase the credit limit, please contact your account manager
400 1115 invalid_param Message ID provided is not valid
400 1116 invalid_param The scheduled date is in the past
400 1117 invalid_body Invalid JSON
400 1120 invalid_param The parameter strategy is empty or not set
400 1121 invalid_param The parameter strategy must have at least two channels
400 1122 invalid_param The parameter strategy must have channel sms as last element
400 1123 invalid_param The parameter channel is not valid. Allowed values:
400 1124 invalid_param The parameter ttl is not a number
400 1125 invalid_param Min value for ttl is 300 seconds
400 1126 invalid_param The parameter templateId is not set
400 1127 invalid_param The parameter templateId is not valid
400 1128 invalid_param The template ID provided is not a valid template
400 1129 invalid_param The parameter strategy contains duplicate channels
400 1130 insufficient_credit Insufficient credit for failover sending
400 1134 invalid_param Max value for ttl is 1209600 seconds (14 days)
400 1135 invalid_param The parameter transliteration should be an object
400 1136 invalid_param Invalid number of characters for the placeholder {{numbers}}
400 1136 invalid_param Invalid number of characters for the placeholder {{letters}}
400 1136 invalid_param Invalid number of characters for the placeholder {{alphanumeric}}
400 1137 invalid_param Number of characters for placeholders can be between 1 and 20
400 1140 invalid_param Group ID is not a valid group
400 1155 invalid_param Campaign ID provided is not valid
400 1165 invalid_param Campaign ID or msg ID provided is not valid
400 1203 invalid_param The parameter phoneNumbers is empty or not set
400 1205 invalid_param The phone numbers array is too big (max. allowed: 40000 numbers)
400 1204 invalid_param The name is empty or parameter name not set
400 1206 invalid_param The name provided is invalid (min 3, max 60 characters)
400 1207 invalid_param The phone number provided is not valid
400 1208 invalid_param The parameter phoneNumbers must be an array of phone numbers
400 1209 invalid_param The parameter lookupCallbackUrl is not a valid URL
400 1210 invalid_param The phone numbers provided are invalid
400 1211 duplicate_value You already have a group with this name
400 1212 invalid_param Invalid request parameters
400 1213 invalid_param At least one parameter required (phoneNumber, firstName, lastName, email, field1, field2, field3, field4, field5, customFields)
400 1215 duplicate_value The phone number already exists
400 1216 invalid_param No valid numbers provided or no coverage
400 1217 invalid_param The lookupId provided is invalid
400 1218 invalid_param The lookupBulkId provided is invalid
400 1301 invalid_param The originator is empty or parameter originator not set
400 1303 invalid_param The parameter originator can contain only letters and numbers
400 1304 invalid_param The alphanumeric originator provided is invalid (min 3, max 11 characters)
400 1305 invalid_param The numeric originator provided is invalid (min 3, max 15 characters)
400 1306 duplicate_value Originator already exists
400 1401 invalid_param The URL is empty or parameter url not set
400 1402 invalid_param The URL provided is invalid
400 1404 invalid_param The parameter name is invalid (min 3, max 25 characters)
400 1405 duplicate_id Short ID already exists
400 1406 invalid_param At least one parameter required (name, url)
400 1407 duplicate_value You already have a shortlink with this name
400 1425 duplicate_id Attachment ID already exists
400 1427 duplicate_value You already have an attachment with this name
400 1441 invalid_param No valid phone numbers were provided or already in the optout list
400 1503 invalid_param The parameter removeEmojis is not boolean (true or false)
400 1521 invalid_param The channel requested is not valid
400 1522 invalid_param Invalid country iso or mcc
400 1801 invalid_param The text message is empty or parameter text not set
400 1802 invalid_param The parameter text is invalid
400 1803 invalid_param The name provided is invalid (min 3, max 100 characters)
400 1804 invalid_param At least one parameter required (name, text)
400 1805 duplicate_value You already have a template with this name
400 1806 invalid_param The parameter channel is not valid. Allowed values:
400 1808 invalid_param Button caption is too long (min 1, max. 30 characters)
400 1809 invalid_param Invalid target URL
400 1810 invalid_param Invalid image URL
400 1811 invalid_param Text message too long (max 1000 characters)
400 1820 invalid_param The parameter period is not a valid date (format Y-m or Y)
400 1821 invalid_param The parameter start_date is not a valid date
400 1822 invalid_param The parameter end_date is not a valid date
400 1823 invalid_param The end date is before the start date
400 1824 invalid_param No period parameter or interval (start_date, end_date)
400 1825 invalid_param The parameter source is not valid
400 1826 invalid_param The parameter delivery_report is not valid (delivered, failed or sent)
400 1827 invalid_param The parameter country_iso is not for a valid country
400 1828 invalid_param The parameter channel is not valid (sms, viber, whatsapp, multichannel)
400 1829 invalid_param Invalid dimension. Accepted dimensions: source, channel, country, traffic, delivery
400 1600 invalid_request The request is missing a required parameter (grant_type)
400 1600 invalid_scope The requested scope is invalid, unknown, or malformed
400 1600 unsupported_grant_type The grant type is not supported (only client_credentials)
400 2001 invalid_param The parameter phoneNumber is empty or not set
400 2002 invalid_param The parameter countryIso is empty or not set
400 2003 invalid_param Country ISO provided is invalid
400 2004 invalid_param The parameter from is empty or not set
400 2005 invalid_param The parameter from is not valid (min 3, max 15 characters)
400 2006 invalid_param The parameter template is empty or not set
400 2006 invalid_param The parameter template does not contain placeholder {{pin}}
400 2007 invalid_param The parameter ttl is not a number
400 2008 invalid_param Min value for ttl is 60 seconds
400 2009 invalid_param Max value for ttl is 1800 seconds (30 mins)
400 2010 invalid_param The parameter maxAttempts is not a number
400 2011 invalid_param Min value for maxAttempts is 1
400 2012 invalid_param Max value for maxAttempts is 10
400 2013 invalid_param The parameter pinType is empty or not set
400 2014 invalid_param Invalid parameter pinType. Must be one of: letters, numbers, alphanumeric
400 2015 invalid_param The parameter pinLength is not a number
400 2016 invalid_param Min value for pinLength is 4
400 2017 invalid_param Max value for pinLength is 10
400 2018 invalid_param Track ID provided (parameter trackId) is not a valid UUID (v1-v5)
400 2019 invalid_param The parameter otpCallbackUrl is not a valid URL
400 2020 invalid_param The phone number provided is invalid
404 2021 not_found Otp ID not found
400 2022 invalid_param The parameter pin is empty or not set
400 2023 otp_verified The OTP was already verified
400 2024 otp_cancelled The OTP was canceled
400 2025 otp_expired The OTP has expired
400 2026 otp_failed The OTP has failed, maximum attempts reached
400 2027 otp_failed Max attempts reached
400 2028 otp_expired The PIN has expired
400 2029 invalid_pin The PIN provided does not verify
400 1221 invalid_param The rentId provided is invalid
400 1222 invalid_param Invalid parameter numberId
400 1224 invalid_param Rent period is invalid (1, 7 or 30 days)
400 1225 invalid_param Parameter autorenew must be type boolean
400 1226 invalid_param The parameter callbackUrl is not a valid url
400 1229 invalid_param Rent period is lower than the minimum rent period of this number
400 1233 invalid_param At least one parameter required (autoRenew, callbackUrl)
400 1234 invalid_param Registration ID provided is invalid or not found
401 1601 invalid_api_key Invalid Api Key
401 1600 invalid_client Invalid client
401 1604 invalid_client Client authentication failed
403 1118 access_denied Only scheduled campaigns/messages can be deleted
403 1119 no_coverage No coverage or restricted destination
403 1214 no_coverage No coverage or restricted destination
403 1131 access_denied The strategy contains channels that are not active:
403 1132 access_denied The template ID provided is not approved
403 1133 access_denied The template ID provided is not locked
403 1181 access_denied Cannot reply with channel Viber. More than 24 hours since user reply
403 1182 access_denied Cannot reply with channel Whatsapp. More than 24 hours since user reply
403 1443 access_denied Cannot delete this phone number from the optout list because it was added via optout type link. Allowed optout type to delete: admin
403 1523 no_coverage No coverage
403 1602 access_denied The Api Key provided is not active
403 1603 insufficient_scope The request requires higher privileges than provided by the access token
403 1605 access_denied Access denied for this IP address
403 1606 access_denied The channel Viber is not active. Register from Admin Dashboard
403 1607 access_denied The channel Whatsapp is not active. Register from Admin Dashboard
403 1608 access_denied The channel Multichannel is not active. Register from Admin Dashboard
403 1812 access_denied Template is locked for editing
403 2030 access_denied Otp already cancelled
403 2031 access_denied You cannot cancel a non-pending Otp
403 3600 access_denied Account locked. Please contact your account manager
404 1100 not_found Message ID provided was not found or is not scheduled
404 1150 not_found Campaign ID provided was not found or is not scheduled
403 1227 access_denied Cannot cancel this rent. More than 30 minutes passed from start of renting period
403 1227 access_denied Cannot cancel this rent. More than 30 minutes passed from start of renting period
403 1232 access_denied Cannot cancel this rent. The number has already been used for inbound SMS
403 1231 access_denied Cannot rent this phone number (already rented)
404 1160 not_found Campaign ID or msg ID provided was not found
404 1180 not_found Conversation ID not found
404 1200 not_found Group ID not found
404 1202 not_found Phone number ID not found
404 1219 not_found Lookup ID not found
404 1220 not_found Lookup Bulk ID not found
404 1300 not_found Originator ID not found
404 1400 not_found Shortlink ID not found
404 1420 not_found Attachment ID not found
404 1440 not_found Optout ID not found
404 1500 not_found Application ID not found
404 1800 not_found Template ID not found
404 1900 not_found The requested resource could not be found
404 2021 not_found Otp ID not found
404 1223 not_found Rent ID not found
404 1230 not_found Number ID not found or number is not available for rent anymore
405 1901 invalid_method HTTP Method must be one of: GET, POST, DELETE, PATCH
429 1700 rate_limit Request rate limit exceeded, please try again later. Check Header X-Rate-Limit-Reset. Contact Support in order to change the rate limits for your account
500 1000 server_error The server encountered an unexpected condition which prevented it from fulfilling the request

Delivery reports

When sending an SMS, the API allows to track the success or failure of the SMS by providing different statuses.

The following statuses are available:

Status Status Code Type Description
ACCEPTED 0 Intermediate The initial status of an SMS. It means that your request was received and the SMS is about to be sent
SENT 3 Intermediate The message was sent to the recipient but no final status is available yet
DELIVERED 1 Final Message was delivered to the mobile phone
FAILED 2 Final Message was not delivered
NO COVERAGE 5 Final Message was not accepted for delivery because there is no coverage to specified destination. You will not be billed for messages with this status
REJECTED 4 Final Message was not accepted for delivery (the recipient is in blacklist/optout list). You will not be billed for rejected messages
SCHEDULED 9 Intermediate Message was scheduled for processing at the specified date and time

Note that statuses of type Intermediate will not trigger a request to your callback URL. They can only be reported if you request the status by message ID.

Delivery report error codes

The errorCode parameter in the DLR callback gives more information about a failed delivery. A non-null value indicates that the message could not be delivered.

errorCode Type Description
null No error No error in the handling of the message
1 Unknown Message was not delivered, and no reason could be provided
2 Unknown Number The destination number is unknown or no longer exists
3 Roaming The destination number is in roaming and cannot accept the message
4 Number Blocked The destination number is blocked by the network operator to receive the message
5 Carrier Rejection The message was blocked by the operator's anti-spam filter. Check the content of your message
50 Regulation Error Unknown country specific regulation error
60 General Error There was an error in the routing of the message

Idempotency

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to send a SMS campaign to 20.000 phone numbers does not respond due to a network connection error, you can retry the request with the same idempotency id to guarantee that no more than one campaign is sent and you are not billed twice.

To perform an idempotent request, provide an additional idempotencyId parameter to the request body. To confirm that the server understood the request, the response will contain the header X-Idempotency-Id with your unique value.

SMS.CX Messaging API's idempotency works by saving the resulting status code and body of the first request made for any given idempotency ID, only if the incoming parameters pass validation and the API endpoint begin execution. Subsequent requests with the same id return the same result, including 500 errors. If incoming parameters failed validation (HTTP status 4XX), no idempotent result is saved because no API endpoint began execution. It is safe to retry these requests.

An idempotency ID is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. The unique values you create must be valid UUIDs (from v1 to v5) to avoid collisions.

Idempotency IDs are removed from the system automatically after they're at least 24 hours old.

Idempotency IDs are supported on POST requests that affects the billing. Sending idempotency ids in GET and DELETE requests has no effect, as these requests are idempotent by definition.

The Messaging API is fast and can validate and send up to 25.000 SMS/Viber/Whatsapp in a single request. If the response from the API is intrerrupted due to a network connectivity error and you retry the request with the same idempotency ID, if the execution of the API endpoint didn't finished you will get the following intermediary reseponse:

{
    "info": {
        "idempotencyId": "287c1e8d-4842-4106-8fe9-4debf8855743",
        "route": "/sms",
        "status": "processing"
    }
}

In this case you should safely retry the request with an exponential backoff method.

The methods that accept an idempotency id are the following:

Rate limit

There are limits to the number of API calls that your application can make against a particular endpoint. Each API response you receive will include the headers X-Rate-Limit-Limit and X-Rate-Limit-Remaining

Exceeding a rate limit will result in an HTTP 429 Too Many Requests status code. It will include an X-Rate-Limit-Reset header that indicates the remaining window before the rate limit resets, in UTC epoch seconds (e.g. 1626119010).

Request IDs

Each API request has an associated request identifier. You can find this value in the response headers, under X-Request-Id. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.

IP address filtering

For improved security you can create a list of allowed IP addresses. Only IP addresses in the allowed list can make API calls using the applications credentials (Access Tokens, API Keys). If the list is left empty, all IP addresses are allowed.

To add an IP address to the allowed list, go to Admin Dashboard.

*Admin Dashboard - HTTP API - Security*

Note: Only IPv4 addresses are supported

API requests made from an IP address not in the allowed list will result in the following response:

403 Forbidden
Content-Type: application/json

{
    "error": {
        "type": "access_denied",
        "message": "Access denied for this IP address",
        "uri": "https://developers.sms.cx/docs/rest/ip-access/errors",
        "code": 1605
    }
}

Pagination

When making data requests it is likely that there is more data than can be returned in a single response. When that is the case the response will include a paging object with a next token, previous token and size of the returned collection. Whenever a next token is provided, there is additional data to retrieve so you will need to keep making API requests. If the next token is null then you reached the end of the data collection.

To request the next page of data, you must make the exact same query as the original, and also include a next request parameter set to the value from the previous response.

The same applies for previous token, except that the first request will have the previous token as null.

You can limit the number of results returned with the query parameter limit. The default and the maximum limit in the same time is 500.

Webhooks / Callbacks

Webhooks are an addition to an API, and rather of your code making the request for data, the API sends data to you. The data makes it to your application in the form of a HTTP request.

The API will make HTTP requests to your endpoints, saved in the application settings or that are set during your API calls. Your endpoints must return status HTTP 200 OK for the callback request to be marked as successful. If not successful, the API will retry the request using an exponential backoff algorithm.

The retry policy will follow this delay from the initial attempt:

Retry attempt Delay
1 1 minute
2 2 minutes
3 5 minutes
4 10 minutes
5 30 minutes
6 1 hour
7 2 hours
8 4 hours
9 8 hours
10 24 hours

SMS.CX API allows you to set a different callback/webhook URL for each resource that accepts this parameter.

However, if you want you can use only one endpoint for receiving data from SMS.CX API. The sent data is standardized across all callbacks, every request will have two objects: event and data. This makes it easier to use only one endpoint for all callbacks and identify the correct event for specific processing.

The event parameter can have the following values:

  • dlr_update
  • receive_sms
  • receive_viber
  • receive_whatsapp
  • shortlink_hit
  • shortlink_hit_update
  • attachment_hit
  • attachment_hit_update
  • new_optout
  • otp_update
  • number_lookup

The SMS.CX API groups the data by event type in the data object and send up to 200 events in one single callback request. Therefore, your endpoint must expect to parse and iterate trough all the data object.

Note: If by any reason your endpoint cannot handle bulk event grouping, please contact us so we can switch your callback settings to single request. Also, you can request increase or decrease in the data object grouping (eg. 40 events per request, 500 events per request, etc.)

Example of callback request with event type "dlr_update" and 3 events grouped in the data object:

{
    "event": "dlr_update",
    "data": [
        {
            "campaignId": "961dbfa9-8e12-4f96-b59d-6c0c79c53edc",
            "msgId": "4dd5e899-6ced-4fd5-bbb6-34e51507e3df",
            "trackData": "7f543bdc-dcc5-47c3-b54a-ee425f78cb3c",
            "statusCode": 1,
            "status": "DELIVERED",
            "datetime": "2022-03-03 15:30:24"
        },
        {
            "campaignId": "0ef52a99-10b1-4813-af84-9b285edfbc30",
            "msgId": "a710a44a-e784-4199-b73c-a2c8bfd41b59",
            "trackData": "7f543bdc-dcc5-47c3-b54a-ee425f78cb3c",
            "statusCode": 1,
            "status": "DELIVERED",
            "datetime": "2022-03-03 15:30:24"
        },
        {
            "campaignId": "961dbfa9-8e12-4f96-b59d-6c0c79c53edc",
            "msgId": "4dd5e899-6ced-4fd5-bbb6-34e51507e3df",
            "trackData": "7f543bdc-dcc5-47c3-b54a-ee425f78cb3c",
            "statusCode": 1,
            "status": "DELIVERED",
            "datetime": "2022-03-03 15:30:24"
        }
    ]
}

For complete details of each callback event (parameters list, examples) read the specific section:

Resources overview

Sms

Method Resource Description Reference
POST /sms Send new SMS (single or bulk) Link
POST /sms/estimate Estimate cost of SMS (single or bulk) Link
POST /sms/campaign Send SMS campaign (to existing groups of contacts) Link
POST /sms/campaign/estimate Estimate cost of SMS campaign Link
DELETE /sms/scheduled/{msgId} Delete scheduled SMS Link
DELETE /sms/scheduled/campaign/{campaignId} Delete scheduled SMS campaign Link
POST https://{{your-endpoint}}/path-for-dlr-update [Webhook] Receive delivery report for a sent SMS Link
POST https://{{your-endpoint}}/path-for-receive-sms [Webhook] Receive data for inbound SMS Link

Otp

Method Resource Description Reference
POST /otp New OTP request Link
GET /otp/{otpId} Get status of an OTP request Link
POST /otp/{otpId} Verify PIN Link
DELETE /otp/{otpId} Cancel OTP request Link
POST https://{{your-endpoint}}/path-for-receive-otp-update [Webhook] Receive data for OTP update Link

Viber

Method Resource Description Reference
POST /viber Send new Viber (single or bulk) Link
POST /viber/estimate Estimate cost of Viber (single or bulk) Link
POST /viber/campaign Send Viber campaign (to existing groups of contacts) Link
POST /viber/campaign/estimate Estimate cost of Viber campaign Link
DELETE /viber/scheduled/{msgId} Delete scheduled Viber Link
DELETE /viber/scheduled/campaign/{campaignId} Delete scheduled Viber campaign Link

Whatsapp

Method Resource Description Reference
POST /whatsapp Send new Whatsapp (single or bulk) Link
POST /whatsapp/estimate Estimate cost of Whatsapp (single or bulk) Link
POST /whatsapp/campaign Send Whatsapp campaign (to existing groups of contacts) Link
POST /whatsapp/campaign/estimate Estimate cost of Whatsapp campaign Link
DELETE /whatsapp/scheduled/{msgId} Delete scheduled Whatsapp Link
DELETE /whatsapp/scheduled/campaign/{campaignId} Delete scheduled Whatsapp campaign Link

Multichannel

Method Resource Description Reference
POST /multichannel Send new Multichannel (single or bulk) Link
POST /multichannel/estimate Estimate cost of Multichannel (single or bulk) Link
POST /multichannel/campaign Send Multichannel campaign (to existing groups of contacts) Link
POST /multichannel/campaign/estimate Estimate cost of Multichannel campaign Link
DELETE /multichannel/scheduled/{msgId} Delete scheduled Multichannel Link
DELETE /multichannel/scheduled/campaign/{campaignId} Delete scheduled Multichannel campaign Link

Conversations

Method Resource Description Reference
GET /conversations Get list of conversations Link
GET /conversations/{conversationId} Get conversations details Link
GET /conversations/{conversationId}/read Mark conversation as read Link
POST /conversations/{conversationId}/sms Reply to conversation via SMS Link
POST /conversations/{conversationId}/viber Reply to conversation via Viber Link
POST /conversations/{conversationId}/whatsapp Reply to conversation via Whatsapp Link

Groups

Method Resource Description Reference
GET /groups Get list of groups Link
POST /groups Create new group Link
GET /groups/{groupId} Get all contacts in a group Link
POST /groups/{groupId} Add contacts to group Link
DELETE /groups/{groupId} Delete group Link
GET /groups/{groupId}/empty Empty a group Link
GET /groups/{groupId}/xlsx Export contacts from group as XLSX Link
GET /groups/{groupId}/csv Export contacts from group as CSV Link
DELETE /groups/{groupId}/{phoneNumberId} Delete contact from group Link
PATCH /groups/{groupId}/{phoneNumberId} Update contact in group Link

Reports

Method Resource Description Reference
GET /reports Get advanced reports Link
GET /reports/xlsx Export advanced report to XLSX Link
GET /reports/csv Export advanced report to CSV Link
GET /reports/campaigns Get list of all sent campaigns Link
GET /reports/campaigns/{campaignId} Get report for a campaign Link
GET /reports/campaigns/{campaignId}/xlsx Export campaign report to XLSX Link
GET /reports/campaigns/{campaignId}/csv Export campaign report to CSV Link
GET /reports/single/{msgId} Get report for single SMS/Viber/Whatsapp/Multichannel Link
GET /reports/summary/{dimension} Get summary report for a dimension (channel, source, etc ) Link

Numbers

Method Resource Description Reference
POST /numbers/validate Validate phone numbers in bulk Link
GET /numbers/validate/{phoneNumer} Validate single phone number Link
POST /numbers/lookup Lookup phone numbers in bulk Link
GET /numbers/lookup/{phoneNumer} Lookup single phone number Link
POST https://{{your-endpoint}}/path-for-receive-number-lookup [Webhook] Receive details for Bulk Lookup of Phone Numbers Link

Originators

Method Resource Description Reference
GET /originators Get originators list Link
POST /originators Create new originator Link
DELETE /originators/{originatorId} Delete originator Link

Templates

Method Resource Description Reference
GET /templates Get a list of templates Link
POST /templates Create new template Link
GET /templates/{templateId} Get template details Link
DELETE /templates/{templateId} Delete template Link
PATCH /templates/{templateId} Update template Link

Attachments

Method Resource Description Reference
GET /attachments Get the list of attachments Link
GET /attachments/{attachmentId} Get details for a attachment Link
GET /attachments/{attachmentId}/xlsx Export attachment details in XLSX Link
GET /attachments/{attachmentId}/csv Export attachment details in CSV Link
DELETE /attachments/{attachmentId} Delete a attachment Link
POST https://{{your-endpoint}}/path-for-attachment-hit [Webhook] Receive details of visitor of attachment Link

Optouts

Method Resource Description Reference
GET /optouts Get the list of contacts that opted out Link
GET /optouts/xlsx Export optouts contacts to XLSX Link
GET /optouts/csv Export optouts contacts to CSV Link
POST /optouts Add phone numbers to opt-out list Link
DELETE /optouts/{phoneNumberId} Delete phone number from opt-out list Link
POST https://{{your-endpoint}}/path-for-new-optout [Webhook] Receive details of a new optout Link

Account

Method Resource Description Reference
GET /account/balance Get account balance Link
GET /account/pricing/{channel} Get full pricing of channel (SMS,Viber, Whatsapp) Link
GET /account/pricing/{channel}/{countryIso} Get full pricing of channel for specific country Link
GET /account/channels/status Get status (active/inactive) of channels (SMS, Viber, Whatsapp) Link

Applications

Method Resource Description Reference
GET /applications Get list of applications Link
GET /applications/scopes Get list of allowed scopes Link
GET /applications/{applicationId} Get settings for application Link

Oauth

Get access token

Generate an access token.

The POST request must use the HTTP Basic authentication scheme, by encoding client_id:client_secret string to Base64 string and use it in the header:

Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 

The request body should have the mandatory grant_type parameter with value client_credentials

The content type must be application/x-www-form-urlencoded.

Errors for POST /oauth/token

HTTP code Error code Type Description
400 1600 invalid_request The request is missing a required parameter (grant_type)
400 1600 invalid_scope The requested scope is invalid, unknown, or malformed
400 1600 unsupported_grant_type The grant type is not supported (only client_credentials)
401 1600 invalid_client Invalid client
Authorizations:
Request Body schema: application/x-www-form-urlencoded
grant_type
required
string
Value: "client_credentials"

Grant type (or flow) represents the methods through which the application will get Access Tokens. Must have value client_credentials

scope
string

A list of space-delimited, case-sensitive strings. If left empty or ommited, the issued access token will be granted with all scopes (full privileges)

Responses

Request samples

Content type
application/x-www-form-urlencoded
grant_type=client_credentials

Response samples

Content type
application/json
{
  • "access_token": "a60e4455ec782fd54f37b8b9684dfa7a02c50cc0",
  • "expires_in": 86400,
  • "token_type": "Bearer",
  • "scope": "sms viber whatsapp multichannel conversations reports groups originators templates shortlinks attachments optouts account applications numbers"
}

Sms

Receive delivery report for a sent SMS Webhook

POST https://{{your-endpoint}}/path-for-dlr-update

The SMS.CX API will make a POST request to your webhook endpoint, which must return HTTP response 200. If the response is not HTTP 200, SMS.CX API will retry the callback request for the next 24 hours using an exponential backoff algorithm.

Authorizations:
None
Request Body schema: application/json
event
required
string
Value: "dlr_update"

Event for which the callback request is made

required
Array of objects (DataDlrUpdate)

Event data, grouped in multiple objects (up to 200 in a request)

Responses

Request samples

Content type
application/json
{
  • "event": "dlr_update",
  • "data": [
    ]
}

Receive data for inbound SMS Webhook

POST https://{{your-endpoint}}/path-for-receive-sms

The SMS.CX API will make a POST request to your webhook endpoint, which must return HTTP response 200. If the response is not HTTP 200, SMS.CX API will retry the callback request for the next 24 hours using an exponential backoff algorithm.

Authorizations:
None
Request Body schema: application/json
event
required
string
Value: "receive_sms"

Event for which the callback request is made

required
Array of objects (DataReceiveSms)

Event data, grouped in multiple objects (up to 200 in a request)

Responses

Request samples

Content type
application/json
{
  • "event": "receive_sms",
  • "data": [
    ]
}

Send SMS

Sends SMS to a single phone number or to a list of phone numbers.

This endpoint was designed to handle big data objects (up to 25.000 SMS in one request).

If you have loops or iterations we recommend building the send object in your application, and make a single request to this endpoint. The time of making the requests will decrease - by doing a single request with multiple send objects vs making requests in a loop - and you won't have to worry about making concurrent API calls.

Note: This endpoint accepts idempotent requests by providing an additional idempotencyId parameter in body with a unique value generated by the client of type UUID v1-v5. To confirm that the server understood the request, the response will contain the header X-Idempotency-Id with your unique value. By using idempotency you can retry requests in case of network error or server not responding in time, without accidentally performing the same operation twice and have a guarantee of not being billed twice.

Errors for POST /sms

HTTP code Error code Type Description
400 1103 invalid_param The phone numbers array is too big (max. allowed: 25000 numbers)
400 1104 invalid_param The parameter to is empty or not set
400 1105 invalid_param The parameter from is empty or not set
400 1106 invalid_param The parameter from is not valid (min 3, max 15 characters)
400 1107 invalid_param The parameter text is empty or not set
400 1108 invalid_param The parameter scheduledDate is not a valid date
400 1109 invalid_param The parameter dlrCallbackUrl is not a valid URL
400 1111 invalid_param Idempotency Id provided is not a valid UUID (v1-v5)
400 1112 invalid_param The shortlink/attachment ID provided for tracking is invalid or not found
400 1116 invalid_param The scheduled date is in the past
400 1207 invalid_param The phone number provided is not valid
400 1210 invalid_param The phone numbers provided are invalid
403 1119 no_coverage No coverage or restricted destination
400 1113 insufficient_credit Insufficient credit
400 1114 insufficient_credit Credit limit reached. To increase the credit limit, please contact your account manager
400 1110 invalid_param Invalid alphabet. Must be one of: NONE, NON_GSM, RUSSIAN_CYRILLIC, BULGARIAN_CYRILLIC, UKRAINIAN_CYRILLIC, MACEDONIAN_CYRILLIC, BELARUSIAN_CYRILLIC, SERBIAN_CYRILLIC, POLISH, ROMANIAN, TURKISH, GREEK
400 1135 invalid_param The parameter 'transliteration' should be an object
400 1503 invalid_param The parameter removeEmojis is not boolean (true or false)
400 1136 invalid_param Invalid number of characters for the placeholder {{numbers}}
400 1136 invalid_param Invalid number of characters for the placeholder {{letters}}
400 1136 invalid_param Invalid number of characters for the placeholder {{alphanumeric}}
400 1137 invalid_param Number of characters for placeholders can be between 1 and 20
Authorizations:
Request Body schema: application/json
to
required
Array of strings

A string with single phone number or an array of phone numbers in international E.164 format or national format. If national format is provided, for better validation you must use the parameter countryIso to provide the country code of the destination phone number.

from
required
string [ 3 .. 15 ] characters

The originator (sender name) of the text message (min 3, max 15 characters). If the originator used in this value is not approved, it will be overwritten by a default system originator (eg. InfoText). Read more about sender names

text
required
string

A standard GSM message is limited to 160 characters. If a text message contains even one (or more) Unicode characters (for example ç, ö, ü) the character limit then becomes 70 characters per message part. Long text messages are concatenated into a multipart SMS. A text message can have up to 1530 characters (10 message parts).

You can use custom fields in the text, by using the name of the field between two curly braces. The placeholders will be replaced with the availale data. If no data is found the placeholder will be replaced by a blank string. Available fields are:

  • {{optoutLink}}
  • {{shortlink:<ID>}}
  • {{attachement:<ID>}}

    The placeholder {{shortlink:<ID>}} is used when you want to track a shortlink. The API will generate a unique string for every contact, and doing so you will know what phone number clicked on the link. Eg. {{shortlink:bVc}} will be replaced by https://en.ax/bVc/r2N

    General placeholders can be used in the text, which will be replaced with data. Available general placeholders are:
  • {{numbers}} - will be replaced with a random number. Default length of the number is 4 characters. Eg. 9765
  • {{numbers:8}} - will be replaced with a random number with length of 8 characters. The minimum number length can be 1 and maximum length can be 20
  • {{letters}} - will be replaced with a random string of letters. Default length of the string is 4 characters. Eg. AJKV
  • {{letters:10}} - will be replaced with a random string with length of 10 characters. The minimum string length can be 1 and maximum length can be 20
  • {{alphanumeric}} - will be replaced with a random string of letters and numbers. Default length of the string is 4 characters. Eg. BH4V
  • {{alphanumeric:6}} - will be replaced with a random string of letters and numbers with length of 6 characters. The minimum alphanumeric string length can be 1 and maximum length can be 20
  • {{today}} - will be replaced with today date in following example format: 7 Aug 2022
countryIso
string 2 characters

Country ISO (two-letter) of the destination phone numbers (if provided in national format). Please note that if an international E.164 phone number format is provided in the to parameter, the countryIso will be ignored. Eg. FR for France, GB for United Kingdom. Note: It is "GB", not "UK", as per the ISO-3166 alpha 2.

allowInvalid
boolean
Default: false

By default an error will be thrown if any invalid numbers are detected in the to parameter. Set this parameter to true if you want to process the request even if invalid numbers are detected. The response will contain in the info object the property invalid, wich is an array with the detected invalid phone numbers

scheduledDate
string <date-time>

If you want to schedule the SMS at a later date. The date provided must be in format YYYY-MM-DD HH:MM:SS (Eg. 2021-06-23 14:26:10). By default, the date and time in this parameter is treated as UTC. So if you want to schedule a SMS to a french phone number at 16:00 (France is UTC+2), then you should set the parameter at 2021-06-23 14:00 (UTC). If you don't want to make the calculations, you can set this parameter as the date time of the destination (eg. 2021-06-23 16:00) and set the parameter isUtc to false. In this way, the API will automatically make the conversion from the destination timezone to UTC and set the scheduledDate accordingly

isUtc
boolean
Default: true

If set to false it will indicate that the scheduledDate parameter is not a date in UTC time, but the date relative to the timezone of the destination phone number. The API will calculate the offset and convert the date to UTC.

dlrCallbackUrl
string <url>

A valid URL to receive the delivery report update for the sent SMS. If this parameter is set, it will overwrite the setting from Admin Dashboard > HTTP API > Oauth2 > Application settings

trackData
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

Allows to track messages a client provided ID. The trackData value will be passed back with the response and in all callbacks (webhooks). If the value is not a valid UUID (v1-v5) the API will not return an error but will discard this parameter

shortResponse
boolean
Default: false

If set to true, it will return the full info object and empty data object. For situations when you don't need the information in the data object and want to save bandwith

noTextDetails
boolean
Default: false

The response will not have the parameters data.text and data.textAnalysis. For situations when you send to large lists of phone numbers and don't need all response parameters (save bandwith)

showTimezone
boolean
Default: false

Shows the parameter timezone in the response, for each phone number

idempotencyId
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

A unique idempotency id generated by the client. For more information, refer to Idempotent requests. The API will return an error if the value provided is not a valid UUID (v1-v5)

object (Transliteration)

Convert special characters from Unicode to GSM 03.38 charset, or replace them if no GSM equivalent.

Eg. Привет = privet (cyrillic), cześć = czesc (polish), edilmiş = edilmis (turkish), bună = buna (romanian)

If this parameter is set, it will overwrite the settings from Admin Dashboard > HTTP API > Oauth2 > Application settings

Responses

Request samples

Content type
application/json
Example
{
  • "to": [
    ],
  • "from": "InfoText",
  • "text": "Your confirmation code is 5443"
}

Response samples

Content type
application/json
Example
{
  • "info": {
    },
  • "data": [
    ]
}

Estimate new SMS

Estimate the cost of sending a SMS message.

This endpoint is identical to /sms endpoint, but it will only simulate the SMS sending (no billing).

The request body and the response are the same as for /sms endpoint.

curl --location --request POST 'https://api.sms.cx/sms/estimate' \
--header 'Authorization: Bearer d34a5e82f8d5e45ad1968deb5d3a3674ea6b46f6' \
--header 'Content-Type: application/json' \
--data-raw '{
    "to": [
        "+31612469822",
        "+31612469333"
    ],
    "from": "InfoText",
    "text": "Second text message"
}'

Errors for POST /sms/estimate

HTTP code Error code Type Description
400 1104 invalid_param The parameter to is empty or not set
400 1105 invalid_param The parameter from is empty or not set
400 1106 invalid_param The parameter from is not valid (min 3, max 15 characters)
400 1107 invalid_param The parameter text is empty or not set
400 1108 invalid_param The parameter scheduledDate is not a valid date
400 1109 invalid_param The parameter dlrCallbackUrl is not a valid URL
400 1112 invalid_param The shortlink/attachment ID provided for tracking is invalid or not found
400 1116 invalid_param The scheduled date is in the past
400 1103 invalid_param The phone numbers array is too big (max. allowed: 25000 numbers)
400 1207 invalid_param The phone number provided is not valid
400 1210 invalid_param The phone numbers provided are invalid
403 1119 no_coverage No coverage or restricted destination
400 1113 insufficient_credit Insufficient credit
400 1114 insufficient_credit Credit limit reached. To increase the credit limit, please contact your account manager
400 1110 invalid_param Invalid alphabet. Must be one of: NONE, NON_GSM, RUSSIAN_CYRILLIC, BULGARIAN_CYRILLIC, UKRAINIAN_CYRILLIC, MACEDONIAN_CYRILLIC, BELARUSIAN_CYRILLIC, SERBIAN_CYRILLIC, POLISH, ROMANIAN, TURKISH, GREEK
400 1135 invalid_param The parameter 'transliteration' should be an object
400 1503 invalid_param The parameter removeEmojis is not boolean (true or false)
400 1136 invalid_param Invalid number of characters for the placeholder {{numbers}}
400 1136 invalid_param Invalid number of characters for the placeholder {{letters}}
400 1136 invalid_param Invalid number of characters for the placeholder {{alphanumeric}}
400 1137 invalid_param Number of characters for placeholders can be between 1 and 20
Authorizations:
Request Body schema: application/json
to
required
Array of strings

A string with single phone number or an array of phone numbers in international E.164 format or national format. If national format is provided, for better validation you must use the parameter countryIso to provide the country code of the destination phone number.

from
required
string [ 3 .. 15 ] characters

The originator (sender name) of the text message (min 3, max 15 characters). If the originator used in this value is not approved, it will be overwritten by a default system originator (eg. InfoText). Read more about sender names

text
required
string

A standard GSM message is limited to 160 characters. If a text message contains even one (or more) Unicode characters (for example ç, ö, ü) the character limit then becomes 70 characters per message part. Long text messages are concatenated into a multipart SMS. A text message can have up to 1530 characters (10 message parts).

You can use custom fields in the text, by using the name of the field between two curly braces. The placeholders will be replaced with the availale data. If no data is found the placeholder will be replaced by a blank string. Available fields are:

  • {{optoutLink}}
  • {{shortlink:<ID>}}
  • {{attachement:<ID>}}

    The placeholder {{shortlink:<ID>}} is used when you want to track a shortlink. The API will generate a unique string for every contact, and doing so you will know what phone number clicked on the link. Eg. {{shortlink:bVc}} will be replaced by https://en.ax/bVc/r2N

    General placeholders can be used in the text, which will be replaced with data. Available general placeholders are:
  • {{numbers}} - will be replaced with a random number. Default length of the number is 4 characters. Eg. 9765
  • {{numbers:8}} - will be replaced with a random number with length of 8 characters. The minimum number length can be 1 and maximum length can be 20
  • {{letters}} - will be replaced with a random string of letters. Default length of the string is 4 characters. Eg. AJKV
  • {{letters:10}} - will be replaced with a random string with length of 10 characters. The minimum string length can be 1 and maximum length can be 20
  • {{alphanumeric}} - will be replaced with a random string of letters and numbers. Default length of the string is 4 characters. Eg. BH4V
  • {{alphanumeric:6}} - will be replaced with a random string of letters and numbers with length of 6 characters. The minimum alphanumeric string length can be 1 and maximum length can be 20
  • {{today}} - will be replaced with today date in following example format: 7 Aug 2022
countryIso
string 2 characters

Country ISO (two-letter) of the destination phone numbers (if provided in national format). Please note that if an international E.164 phone number format is provided in the to parameter, the countryIso will be ignored. Eg. FR for France, GB for United Kingdom. Note: It is "GB", not "UK", as per the ISO-3166 alpha 2.

allowInvalid
boolean
Default: false

By default an error will be thrown if any invalid numbers are detected in the to parameter. Set this parameter to true if you want to process the request even if invalid numbers are detected. The response will contain in the info object the property invalid, wich is an array with the detected invalid phone numbers

scheduledDate
string <date-time>

If you want to schedule the SMS at a later date. The date provided must be in format YYYY-MM-DD HH:MM:SS (Eg. 2021-06-23 14:26:10). By default, the date and time in this parameter is treated as UTC. So if you want to schedule a SMS to a french phone number at 16:00 (France is UTC+2), then you should set the parameter at 2021-06-23 14:00 (UTC). If you don't want to make the calculations, you can set this parameter as the date time of the destination (eg. 2021-06-23 16:00) and set the parameter isUtc to false. In this way, the API will automatically make the conversion from the destination timezone to UTC and set the scheduledDate accordingly

isUtc
boolean
Default: true

If set to false it will indicate that the scheduledDate parameter is not a date in UTC time, but the date relative to the timezone of the destination phone number. The API will calculate the offset and convert the date to UTC.

dlrCallbackUrl
string <url>

A valid URL to receive the delivery report update for the sent SMS. If this parameter is set, it will overwrite the setting from Admin Dashboard > HTTP API > Oauth2 > Application settings

trackData
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

Allows to track messages a client provided ID. The trackData value will be passed back with the response and in all callbacks (webhooks). If the value is not a valid UUID (v1-v5) the API will not return an error but will discard this parameter

shortResponse
boolean
Default: false

If set to true, it will return the full info object and empty data object. For situations when you don't need the information in the data object and want to save bandwith

noTextDetails
boolean
Default: false

The response will not have the parameters data.text and data.textAnalysis. For situations when you send to large lists of phone numbers and don't need all response parameters (save bandwith)

showTimezone
boolean
Default: false

Shows the parameter timezone in the response, for each phone number

object (Transliteration)

Convert special characters from Unicode to GSM 03.38 charset, or replace them if no GSM equivalent.

Eg. Привет = privet (cyrillic), cześć = czesc (polish), edilmiş = edilmis (turkish), bună = buna (romanian)

If this parameter is set, it will overwrite the settings from Admin Dashboard > HTTP API > Oauth2 > Application settings

Responses

Request samples

Content type
application/json
Example
{
  • "to": [
    ],
  • "from": "InfoText",
  • "text": "Second text message",
  • "transliteration": {
    }
}

Response samples

Content type
application/json
Example
{
  • "info": {
    },
  • "data": [
    ]
}

Send SMS campaign


Sends SMS to existing group(s) of contacts.

Note: This endpoint accepts idempotent requests by providing an additional idempotencyId parameter in body with a unique value generated by the client of type UUID v1-v5. To confirm that the server understood the request, the response will contain the header X-Idempotency-Id with your unique value. By using idempotency you can retry requests in case of network error or server not responding in time, without accidentally performing the same operation twice and have a guarantee of not being billed twice.

We recommend to always use Idempotency ID when sending SMS campaigns

Errors for POST /sms/campaign

HTTP code Error code Type Description
400 1101 invalid_param The parameter groups is empty or not set
400 1140 invalid_param Group ID is not a valid group
400 1102 invalid_param Group is empty
400 1103 invalid_param The phone numbers array is too big (max. allowed: 25000 numbers)
400 1105 invalid_param The parameter from is empty or not set
400 1106 invalid_param The parameter from is not valid (min 3, max 15 characters)
400 1107 invalid_param The parameter text is empty or not set
400 1108 invalid_param The parameter scheduledDate is not a valid date
400 1109 invalid_param The parameter dlrCallbackUrl is not a valid URL
400 1111 invalid_param Idempotency Id provided is not a valid UUID (v1-v5)
400 1112 invalid_param The shortlink/attachment ID provided for tracking is invalid or not found
400 1116 invalid_param The scheduled date is in the past
403 1119 no_coverage No coverage or restricted destination
400 1113 insufficient_credit Insufficient credit
400 1114 insufficient_credit Credit limit reached. To increase the credit limit, please contact your account manager
400 1110 invalid_param Invalid alphabet. Must be one of: NONE, NON_GSM, RUSSIAN_CYRILLIC, BULGARIAN_CYRILLIC, UKRAINIAN_CYRILLIC, MACEDONIAN_CYRILLIC, BELARUSIAN_CYRILLIC, SERBIAN_CYRILLIC, POLISH, ROMANIAN, TURKISH, GREEK
400 1135 invalid_param The parameter 'transliteration' should be an object
400 1503 invalid_param The parameter removeEmojis is not boolean (true or false)
400 1136 invalid_param Invalid number of characters for the placeholder {{numbers}}
400 1136 invalid_param Invalid number of characters for the placeholder {{letters}}
400 1136 invalid_param Invalid number of characters for the placeholder {{alphanumeric}}
400 1137 invalid_param Number of characters for placeholders can be between 1 and 20
Authorizations:
Request Body schema: application/json
groups
required
Array of integers <int32>

An array of identifiers for groups of contacts

from
required
string [ 3 .. 15 ] characters

The originator (sender name) of the text message (min 3, max 15 characters). If the originator used in this value is not approved, it will be overwritten by a default system originator (eg. InfoText). Read more about sender names

text
required
string

A standard GSM message is limited to 160 characters. If a text message contains even one (or more) Unicode characters (for example ç, ö, ü) the character limit then becomes 70 characters per message part. Long text messages are concatenated into a multipart SMS. A text message can have up to 1530 characters (10 message parts).

You can use custom fields in the text, by using the name of the field between two curly braces. The placeholders will be replaced with the availale data. If no data is found the placeholder will be replaced by a blank string. Available fields are:

  • {{firstName}} - will be replaced with data saved when the contact was added to group
  • {{lastName}} - will be replaced with data saved when the contact was added to group
  • {{email}} - will be replaced with data saved when the contact was added to group
  • {{field1}} - {{field5}} - will be replaced with data saved when the contact was added to group
  • {{<CUSTOM-FIELD>}} - Eg. {{height}} cand be used as placeholder if this custom field was added when validating the contact to a group
  • {{optoutLink}}
  • {{shortlink:<ID>}}
  • {{attachement:<ID>}}

    The placeholder {{shortlink:<ID>}} is used when you want to track a shortlink. The API will generate a unique string for every contact, and doing so you will know what phone number clicked on the link. Eg. {{shortlink:bVc}} will be replaced by https://en.ax/bVc/r2N

    General placeholders can be used in the text, which will be replaced with data. Available general placeholders are:
  • {{numbers}} - will be replaced with a random number. Default length of the number is 4 characters. Eg. 9765
  • {{numbers:8}} - will be replaced with a random number with length of 8 characters. The minimum number length can be 1 and maximum length can be 20
  • {{letters}} - will be replaced with a random string of letters. Default length of the string is 4 characters. Eg. AJKV
  • {{letters:10}} - will be replaced with a random string with length of 10 characters. The minimum string length can be 1 and maximum length can be 20
  • {{alphanumeric}} - will be replaced with a random string of letters and numbers. Default length of the string is 4 characters. Eg. BH4V
  • {{alphanumeric:6}} - will be replaced with a random string of letters and numbers with length of 6 characters. The minimum alphanumeric string length can be 1 and maximum length can be 20
  • {{today}} - will be replaced with today date in following example format: 7 Aug 2022
scheduledDate
string <date-time>

If you want to schedule the SMS at a later date. The date provided must be in format YYYY-MM-DD HH:MM:SS (Eg. 2021-06-23 14:26:10). By default, the date and time in this parameter is treated as UTC. So if you want to schedule a SMS to a french phone number at 16:00 (France is UTC+2), then you should set the parameter at 2021-06-23 14:00 (UTC). If you don't want to make the calculations, you can set this parameter as the date time of the destination (eg. 2021-06-23 16:00) and set the parameter isUtc to false. In this way, the API will automatically make the conversion from the destination timezone to UTC and set the scheduledDate accordingly

isUtc
boolean
Default: true

If set to false it will indicate that the scheduledDate parameter is not a date in UTC time, but the date relative to the timezone of the destination phone number. The API will calculate the offset and convert the date to UTC.

dlrCallbackUrl
string <url>

A valid URL to receive the delivery report update for the sent SMS. If this parameter is set, it will overwrite the setting from Admin Dashboard > HTTP API > Oauth2 > Application settings

shortResponse
boolean
Default: false

If set to true, it will return the full info object and empty data object. For situations when you don't need the information in the data object and want to save bandwith

noTextDetails
boolean
Default: false

The response will not have the parameters data.text and data.textAnalysis. For situations when you send to large lists of phone numbers and don't need all response parameters (save bandwith)

showTimezone
boolean
Default: false

Shows the parameter timezone in the response, for each phone number

idempotencyId
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

A unique idempotency id generated by the client. For more information, refer to Idempotent requests. The API will return an error if the value provided is not a valid UUID (v1-v5)

object (Transliteration)

Convert special characters from Unicode to GSM 03.38 charset, or replace them if no GSM equivalent.

Eg. Привет = privet (cyrillic), cześć = czesc (polish), edilmiş = edilmis (turkish), bună = buna (romanian)

If this parameter is set, it will overwrite the settings from Admin Dashboard > HTTP API > Oauth2 > Application settings

Responses

Request samples

Content type
application/json
Example
{
  • "groups": [
    ],
  • "from": "InfoText",
  • "text": "Hi {{firstName}} {{lastName}}. Check out the brochure {{attachment:RytK}} Unsubscribe here: {{optoutLink}}",
  • "idempotencyId": "00d45bbc-8642-4012-b1e9-997b4a152138"
}

Response samples

Content type
application/json
Example
{
  • "info": {
    },
  • "data": [
    ]
}

Estimate SMS campaign

Estimate the cost of sending a SMS message to groups of phone numbers.

This endpoint is identical to /sms/campaign endpoint, but it will only simulate the SMS sending (no billing).

The request body and the response are the same as for /sms/campaign endpoint.

Errors for POST /sms/campaign/estimate

HTTP code Error code Type Description
400 1101 invalid_param The parameter groups is empty or not set
400 1140 invalid_param Group ID is not a valid group
400 1102 invalid_param Group is empty
400 1103 invalid_param The phone numbers array is too big (max. allowed: 25000 numbers)
400 1105 invalid_param The parameter from is empty or not set
400 1106 invalid_param The parameter from is not valid (min 3, max 15 characters)
400 1107 invalid_param The parameter text is empty or not set
400 1108 invalid_param The parameter scheduledDate is not a valid date
400 1109 invalid_param The parameter dlrCallbackUrl is not a valid URL
400 1112 invalid_param The shortlink/attachment ID provided for tracking is invalid or not found
400 1116 invalid_param The scheduled date is in the past
403 1119 no_coverage No coverage or restricted destination
400 1113 insufficient_credit Insufficient credit
400 1114 insufficient_credit Credit limit reached. To increase the credit limit, please contact your account manager
400 1110 invalid_param Invalid alphabet. Must be one of: NONE, NON_GSM, RUSSIAN_CYRILLIC, BULGARIAN_CYRILLIC, UKRAINIAN_CYRILLIC, MACEDONIAN_CYRILLIC, BELARUSIAN_CYRILLIC, SERBIAN_CYRILLIC, POLISH, ROMANIAN, TURKISH, GREEK
400 1135 invalid_param The parameter 'transliteration' should be an object
400 1503 invalid_param The parameter removeEmojis is not boolean (true or false)
400 1136 invalid_param Invalid number of characters for the placeholder {{numbers}}
400 1136 invalid_param Invalid number of characters for the placeholder {{letters}}
400 1136 invalid_param Invalid number of characters for the placeholder {{alphanumeric}}
400 1137 invalid_param Number of characters for placeholders can be between 1 and 20
Authorizations:
Request Body schema: application/json
groups
required
Array of integers <int32>

An array of identifiers for groups of contacts

from
required
string [ 3 .. 15 ] characters

The originator (sender name) of the text message (min 3, max 15 characters). If the originator used in this value is not approved, it will be overwritten by a default system originator (eg. InfoText). Read more about sender names

text
required
string

A standard GSM message is limited to 160 characters. If a text message contains even one (or more) Unicode characters (for example ç, ö, ü) the character limit then becomes 70 characters per message part. Long text messages are concatenated into a multipart SMS. A text message can have up to 1530 characters (10 message parts).

You can use custom fields in the text, by using the name of the field between two curly braces. The placeholders will be replaced with the availale data. If no data is found the placeholder will be replaced by a blank string. Available fields are:

  • {{firstName}} - will be replaced with data saved when the contact was added to group
  • {{lastName}} - will be replaced with data saved when the contact was added to group
  • {{email}} - will be replaced with data saved when the contact was added to group
  • {{field1}} - {{field5}} - will be replaced with data saved when the contact was added to group
  • {{<CUSTOM-FIELD>}} - Eg. {{height}} cand be used as placeholder if this custom field was added when validating the contact to a group
  • {{optoutLink}}
  • {{shortlink:<ID>}}
  • {{attachement:<ID>}}

    The placeholder {{shortlink:<ID>}} is used when you want to track a shortlink. The API will generate a unique string for every contact, and doing so you will know what phone number clicked on the link. Eg. {{shortlink:bVc}} will be replaced by https://en.ax/bVc/r2N

    General placeholders can be used in the text, which will be replaced with data. Available general placeholders are:
  • {{numbers}} - will be replaced with a random number. Default length of the number is 4 characters. Eg. 9765
  • {{numbers:8}} - will be replaced with a random number with length of 8 characters. The minimum number length can be 1 and maximum length can be 20
  • {{letters}} - will be replaced with a random string of letters. Default length of the string is 4 characters. Eg. AJKV
  • {{letters:10}} - will be replaced with a random string with length of 10 characters. The minimum string length can be 1 and maximum length can be 20
  • {{alphanumeric}} - will be replaced with a random string of letters and numbers. Default length of the string is 4 characters. Eg. BH4V
  • {{alphanumeric:6}} - will be replaced with a random string of letters and numbers with length of 6 characters. The minimum alphanumeric string length can be 1 and maximum length can be 20
  • {{today}} - will be replaced with today date in following example format: 7 Aug 2022
scheduledDate
string <date-time>

If you want to schedule the SMS at a later date. The date provided must be in format YYYY-MM-DD HH:MM:SS (Eg. 2021-06-23 14:26:10). By default, the date and time in this parameter is treated as UTC. So if you want to schedule a SMS to a french phone number at 16:00 (France is UTC+2), then you should set the parameter at 2021-06-23 14:00 (UTC). If you don't want to make the calculations, you can set this parameter as the date time of the destination (eg. 2021-06-23 16:00) and set the parameter isUtc to false. In this way, the API will automatically make the conversion from the destination timezone to UTC and set the scheduledDate accordingly

isUtc
boolean
Default: true

If set to false it will indicate that the scheduledDate parameter is not a date in UTC time, but the date relative to the timezone of the destination phone number. The API will calculate the offset and convert the date to UTC.

dlrCallbackUrl
string <url>

A valid URL to receive the delivery report update for the sent SMS. If this parameter is set, it will overwrite the setting from Admin Dashboard > HTTP API > Oauth2 > Application settings

shortResponse
boolean
Default: false

If set to true, it will return the full info object and empty data object. For situations when you don't need the information in the data object and want to save bandwith

noTextDetails
boolean
Default: false

The response will not have the parameters data.text and data.textAnalysis. For situations when you send to large lists of phone numbers and don't need all response parameters (save bandwith)

showTimezone
boolean
Default: false

Shows the parameter timezone in the response, for each phone number

object (Transliteration)

Convert special characters from Unicode to GSM 03.38 charset, or replace them if no GSM equivalent.

Eg. Привет = privet (cyrillic), cześć = czesc (polish), edilmiş = edilmis (turkish), bună = buna (romanian)

If this parameter is set, it will overwrite the settings from Admin Dashboard > HTTP API > Oauth2 > Application settings

Responses

Request samples

Content type
application/json
{
  • "groups": [
    ],
  • "from": "MyCompany",
  • "text": "Test message {{firstName}} {{lastName}} {{field1}}"
}

Response samples

Content type
application/json
{
  • "info": {
    },
  • "data": [
    ]
}

Delete scheduled SMS

Delete a scheduled SMS by providing a valid identifier (msgId).

The cost of the deleted scheduled SMS will be returned to the balance of the account.

Errors for DELETE /sms/scheduled/{msgId}

HTTP code Error code Type Description
403 1118 access_denied Only scheduled campaigns/messages can be deleted
404 1100 not_found Message ID provided was not found or is not scheduled
400 1115 invalid_param Message ID provided is not valid
Authorizations:
path Parameters
msgId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 3328fe13-2b99-4282-b62e-d891f5e452a8

Identifier of a scheduled message

Responses

Request samples

curl --request DELETE \
  --url https://api.sms.cx/sms/scheduled/3328fe13-2b99-4282-b62e-d891f5e452a8 \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {
    }
}

Delete scheduled SMS campaign

Delete a scheduled SMS campaign by providing a valid identifier (campaignId).

The cost of the deleted scheduled SMS campaign will be returned to the balance of the account.

If part of the SMS campaign has already started, only scheduled messages will be deleted. Messages already sent cannot be deleted.

Errors for DELETE /sms/scheduled/campaign/{campaignId}

HTTP code Error code Type Description
403 1118 access_denied Only scheduled campaigns/messages can be deleted
404 1150 not_found Campaign ID provided was not found or is not scheduled
400 1155 invalid_param Campaign ID provided is not valid
Authorizations:
path Parameters
campaignId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: cbb72a72-0dfa-4288-b3d0-05fab904f0b2

Identifier of a scheduled SMS campaign

Responses

Request samples

curl --request DELETE \
  --url https://api.sms.cx/sms/scheduled/campaign/cbb72a72-0dfa-4288-b3d0-05fab904f0b2 \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
Example
{
  • "info": {
    }
}

Otp

Receive update for OTP verification Webhook

POST https://{{your-endpoint}}/path-for-otp-update

The SMS.CX API will make a POST request to your webhook endpoint, which must return HTTP response 200. If the response is not HTTP 200, SMS.CX API will retry the callback request for the next 24 hours using an exponential backoff algorithm.

Authorizations:
None
Request Body schema: application/json
event
required
string
Value: "otp_update"

Event for which the callback request is made

required
Array of objects (DataOtpUpdate)

Event data, grouped in multiple objects (up to 200 in a request)

Responses

Request samples

Content type
application/json
{
  • "event": "otp_update",
  • "data": [
    ]
}

New OTP

Create a OTP request to verify a phone number.

Status for OTP requests

Status Description
PENDING The OTP is pending validation by user
VERIFIED The OTP was validated by user
EXPIRED The validity of OTP has expired
CANCELLED The OTP was cancelled by the user
FAILED The OTP failed because too many unsuccessful attempts

Errors for POST /otp

HTTP code Error code Type Description
400 2001 invalid_param The parameter 'phoneNumber' is empty or not set
400 2002 invalid_param The parameter 'countryIso' is empty or not set
400 2003 invalid_param Country ISO provided is invalid
400 2004 invalid_param The parameter 'from' is empty or not set
400 2005 invalid_param The parameter 'from' is not valid (min 3, max 15 characters)
400 2006 invalid_param The parameter 'template' is empty or not set
400 2006 invalid_param The parameter 'template' does not contain placeholder {{pin}}
400 2007 invalid_param The parameter 'ttl' is not a number
400 2008 invalid_param Min value for 'ttl' is 60 seconds
400 2009 invalid_param Max value for 'ttl' is 1800 seconds (30 mins)
400 2010 invalid_param The parameter 'maxAttempts' is not a number
400 2011 invalid_param Min value for 'maxAttempts' is 1
400 2012 invalid_param Max value for 'maxAttempts' is 10
400 2013 invalid_param The parameter 'pinType' is empty or not set
400 2014 invalid_param Invalid parameter 'pinType'. Must be one of: letters, numbers, alphanumeric
400 2015 invalid_param The parameter 'pinLength' is not a number
400 2016 invalid_param Min value for 'pinLength' is 4
400 2017 invalid_param Max value for 'pinLength' is 10
400 2018 invalid_param Track ID provided (parameter 'trackId') is not a valid UUID (v1-v5)
400 2019 invalid_param The parameter 'otpCallbackUrl' is not a valid URL
400 2020 invalid_param The phone number provided is invalid
Authorizations:
Request Body schema: application/json
phoneNumber
required
string

Phone number in international E.164 format or national format. If national format is provided, for better validation you must use the parameter countryIso to provide the country code of the destination phone number

countryIso
string 2 characters

Country ISO (two-letter) of the destination phone numbers (if provided in national format). Please note that if an international E.164 phone number format is provided in the to parameter, the countryIso will be ignored. Eg. FR for France, GB for United Kingdom. Note: It is "GB", not "UK", as per the ISO-3166 alpha 2

from
string [ 3 .. 15 ] characters

The originator (sender name) of the text message (min 3, max 11 characters). If the originator used in this value is not approved, it will be overwritten by a default system originator (eg. InfoText). Read more about sender names Note: This parameter is optional and can be used only if you want to overwrite the OTP settings of your SMS API application

template
string

The text message that will be delivered to the mobile number. It must contain the placeholder {{pin}}. Note: This parameter is optional and can be used only if you want to overwrite the OTP settings of your SMS API application. General placeholders can be used in the text template.

trackId
string 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

Client provided UUID (v1-v5) for tracking purposes

ttl
integer <int32> [ 60 .. 1800 ]

The time to live (ttl) defines the time in seconds that a pin is valid. Min 1 minute (60 seconds) and max 30 minutes (1800 seconds)
Note: If this parameter is set, it will overwrite the setting from Admin Dashboard > HTTP API > Oauth2 > Application settings

maxAttempts
integer <int32> [ 1 .. 10 ]

Number of attempts to allow the OTP to be verified before marking it as failed Note: If this parameter is set, it will overwrite the setting from Admin Dashboard > HTTP API > Oauth2 > Application settings

pinType
string
Enum: "letters" "numbers" "alphanumeric"

Type of pin that will be generated for each mobile phone and will replace the placeholder {{pin} Note: If this parameter is set, it will overwrite the setting from Admin Dashboard > HTTP API > Oauth2 > Application settings

pinLength
integer <int32> [ 4 .. 10 ]

Character length of the pin
Note: If this parameter is set, it will overwrite the setting from Admin Dashboard > HTTP API > Oauth2 > Application settings

otpCallbackUrl
string <url>

A valid URL to receive status updates for the OTP verification.
Note: If this parameter is set, it will overwrite the setting from Admin Dashboard > HTTP API > Oauth2 > Application settings

Responses

Request samples

Content type
application/json
Example
{
  • "phoneNumber": "+33612424105"
}

Response samples

Content type
application/json
Example
{
  • "otpId": "f91536c1-2aff-43b4-b6fa-15e8ade52946",
  • "phoneNumber": "+33612424105",
  • "countryIso": "FR",
  • "status": "PENDING",
  • "cost": 0.063,
  • "parts": 1,
  • "maxAttempts": 5,
  • "attempts": 0,
  • "ttl": 300,
  • "dateCreated": "2022-09-18 12:02:35",
  • "dateExpires": "2022-09-18 12:07:35"
}

Get OTP status

Retrieves the details of OTP status if a valid identifier was provided.

Status for OTP requests

Status Description
PENDING The OTP is pending validation by user
VERIFIED The OTP was validated by user
EXPIRED The validity of OTP has expired
CANCELLED The OTP was cancelled by the user
FAILED The OTP failed because too many unsuccessful attempts

Errors for GET /otp/{otpId}

HTTP code Error code Type Description
404 2021 not_found Otp ID not found
Authorizations:
path Parameters
otpId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: a17fb13d-f4ac-4d93-9439-ef41ab8de390

Identifier of the OTP request

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/otp/a17fb13d-f4ac-4d93-9439-ef41ab8de390 \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "otpId": "486a78ba-0234-4d26-a26c-079823d59ea5",
  • "trackId": "22a2e764-bd7b-4114-bacc-ffbedef15db0",
  • "phoneNumber": "+33612424105",
  • "countryIso": "FR",
  • "status": "PENDING",
  • "cost": 0.063,
  • "parts": 1,
  • "maxAttempts": 5,
  • "attempts": 0,
  • "ttl": 300,
  • "dateCreated": "2022-09-18 09:20:42",
  • "dateExpires": "2022-09-18 09:25:42"
}

Verify OTP

Verify the OTP received on the phone number.

Errors for POST /otp/{otpId}

HTTP code Error code Type Description
404 2021 not_found Otp ID not found
400 2022 invalid_param The parameter pin is empty or not set
400 2023 otp_verified The OTP was already verified
400 2024 otp_cancelled The OTP was canceled
400 2025 otp_expired The OTP has expired
400 2026 otp_failed The OTP has failed, maximum attempts reached
400 2027 otp_failed Max attempts reached
400 2028 otp_expired The PIN has expired
400 2029 invalid_pin The PIN provided does not verify
Authorizations:
path Parameters
otpId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: a17fb13d-f4ac-4d93-9439-ef41ab8de390

Identifier of the OTP request

Request Body schema: application/json
pin
required
string

The PIN code received on the mobile number

Responses

Request samples

Content type
application/json
{
  • "pin": "28822"
}

Response samples

Content type
application/json
{
  • "status": "VERIFIED"
}

Cancel OTP

Cancel OTP request if a valid identifier was provided.

Errors for DELETE /otp/{otpId}

HTTP code Error code Type Description
404 2021 not_found Otp ID not found
403 2030 access_denied Otp already cancelled
403 2031 access_denied You cannot cancel a non-pending Otp
Authorizations:
path Parameters
otpId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: a17fb13d-f4ac-4d93-9439-ef41ab8de390

Identifier of the OTP request

Responses

Request samples

curl --request DELETE \
  --url https://api.sms.cx/otp/a17fb13d-f4ac-4d93-9439-ef41ab8de390 \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {
    }
}

Viber

Send Viber message


Sends Viber message to a single phone number or to a list of phone numbers.

This endpoint was designed to handle big data objects (up to 25.000 Viber messages in one request).

If you have loops or iterations we recommend building the send object in your application, and make a single request to this endpoint. The time of making the requests will decrease - by doing a single request with multiple send objects vs making requests in a loop - and you won't have to worry about making concurrent API calls.

Note: This endpoint accepts idempotent requests by providing an additional idempotencyId parameter in body with a unique value generated by the client of type UUID v1-v5. To confirm that the server understood the request, the response will contain the header X-Idempotency-Id with your unique value. By using idempotency you can retry requests in case of network error or server not responding in time, without accidentally performing the same operation twice and have a guarantee of not being billed twice.

Errors for POST /viber

HTTP code Error code Type Description
400 1104 invalid_param The parameter to is empty or not set
400 1105 invalid_param The parameter from is empty or not set
400 1108 invalid_param The parameter scheduledDate is not a valid date
400 1109 invalid_param The parameter dlrCallbackUrl is not a valid URL
400 1111 invalid_param Idempotency Id provided is not a valid UUID (v1-v5)
400 1112 invalid_param The shortlink/attachment ID provided for tracking is invalid or not found
400 1116 invalid_param The scheduled date is in the past
400 1103 invalid_param The phone numbers array is too big (max. allowed: 25000 numbers)
400 1207 invalid_param The phone number provided is not valid
400 1210 invalid_param The phone numbers provided are invalid
403 1119 no_coverage No coverage or restricted destination
400 1113 insufficient_credit Insufficient credit
400 1114 insufficient_credit Credit limit reached. To increase the credit limit, please contact your account manager
400 1126 invalid_param The parameter templateId is not set
400 1127 invalid_param The parameter templateId is not valid
400 1128 invalid_param The template ID provided is not a valid template
403 1132 access_denied The template ID provided is not approved
403 1133 access_denied The template ID provided is not locked
Authorizations:
Request Body schema: application/json
to
required
Array of strings

A string with single phone number or an array of phone numbers in international E.164 format or national format. If national format is provided, for better validation you must use the parameter countryIso to provide the country code of the destination phone number.

from
required
string [ 3 .. 15 ] characters

The originator (sender name) of the text message (min 3, max 15 characters). If the originator used in this value is not approved, it will be overwritten by a default system originator (eg. InfoText). Read more about sender names

templateId
required
integer <int32>

Identifier of the approved Viber template

object (CustomFields)

An object with key-value pairs, where the key is the name of the custom field. An actual JSON object described by this might look like this:

{
    "customFields": {
        "height": "1.78m",
        "orderNumber": "441",
        "my_custom_field": "My Custom Value"
    }
}  

The data stored in the custom fields will be inserted in the text message template by replacing the placeholder {{<KEY>}}. Eg. {{height}}, {{orderNumber}}

countryIso
string 2 characters

Country ISO (two-letter) of the destination phone numbers (if provided in national format). Please note that if an international E.164 phone number format is provided in the to parameter, the countryIso will be ignored. Eg. FR for France, GB for United Kingdom. Note: It is "GB", not "UK", as per the ISO-3166 alpha 2.

allowInvalid
boolean
Default: false

By default an error will be thrown if any invalid numbers are detected in the to parameter. Set this parameter to true if you want to process the request even if invalid numbers are detected. The response will contain in the info object the property invalid, wich is an array with the detected invalid phone numbers

scheduledDate
string <date-time>

If you want to schedule the Viber message at a later date. The date provided must be in format YYYY-MM-DD HH:MM:SS (Eg. 2021-06-23 14:26:10). By default, the date and time in this parameter is treated as UTC. So if you want to schedule a Viber message to a french phone number at 16:00 (France is UTC+2), then you should set the parameter at 2021-06-23 14:00 (UTC). If you don't want to make the calculations, you can set this parameter as the date time of the destination (eg. 2021-06-23 16:00) and set the parameter isUtc to false. In this way, the API will automatically make the conversion from the destination timezone to UTC and set the scheduledDate accordingly

isUtc
boolean
Default: true

If set to false it will indicate that the scheduledDate parameter is not a date in UTC time, but the date relative to the timezone of the destination phone number. The API will calculate the offset and convert the date to UTC.

dlrCallbackUrl
string <url>

A valid URL to receive the delivery report update for the sent Viber message. If this parameter is set, it will overwrite the setting from Admin Dashboard > HTTP API > Oauth2 > Application settings

trackData
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

Allows to track messages a client provided ID. The trackData value will be passed back with the response and in all callbacks (webhooks). If the value is not a valid UUID (v1-v5) the API will not return an error but will discard this parameter

shortResponse
boolean
Default: false

If set to true, it will return the full info object and empty data object. For situations when you don't need the information in the data object and want to save bandwith

noTextDetails
boolean
Default: false

The response will not have the parameters data.text and data.textAnalysis. For situations when you send to large lists of phone numbers and don't need all response parameters (save bandwith)

showTimezone
boolean
Default: false

Shows the parameter timezone in the response, for each phone number

idempotencyId
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

A unique idempotency id generated by the client. For more information, refer to Idempotent requests. The API will return an error if the value provided is not a valid UUID (v1-v5)

Responses

Request samples

Content type
application/json
Example
{
  • "to": [
    ],
  • "from": "InfoText",
  • "templateId": 15,
  • "allowInvalid": true
}

Response samples

Content type
application/json
Example
{
  • "info": {
    },
  • "data": [
    ]
}

Estimate Viber message

Estimate the cost of sending a Viber message.

This endpoint is identical to /viber endpoint, but it will only simulate the Viber sending (no billing).

The request body and the response are the same as for /viber endpoint.

Errors for POST /viber/estimate

HTTP code Error code Type Description
400 1104 invalid_param The parameter to is empty or not set
400 1105 invalid_param The parameter from is empty or not set
400 1108 invalid_param The parameter scheduledDate is not a valid date
400 1109 invalid_param The parameter dlrCallbackUrl is not a valid URL
400 1112 invalid_param The shortlink/attachment ID provided for tracking is invalid or not found
400 1116 invalid_param The scheduled date is in the past
400 1103 invalid_param The phone numbers array is too big (max. allowed: 25000 numbers)
400 1207 invalid_param The phone number provided is not valid
400 1210 invalid_param The phone numbers provided are invalid
403 1119 no_coverage No coverage or restricted destination
400 1113 insufficient_credit Insufficient credit
400 1114 insufficient_credit Credit limit reached. To increase the credit limit, please contact your account manager
400 1126 invalid_param The parameter templateId is not set
400 1127 invalid_param The parameter templateId is not valid
400 1128 invalid_param The template ID provided is not a valid template
403 1132 access_denied The template ID provided is not approved
403 1133 access_denied The template ID provided is not locked
Authorizations:
Request Body schema: application/json
to
required
Array of strings

A string with single phone number or an array of phone numbers in international E.164 format or national format. If national format is provided, for better validation you must use the parameter countryIso to provide the country code of the destination phone number.

from
required
string [ 3 .. 15 ] characters

The originator (sender name) of the text message (min 3, max 15 characters). If the originator used in this value is not approved, it will be overwritten by a default system originator (eg. InfoText). Read more about sender names

templateId
required
integer <int32>

Identifier of the approved Viber template

object (CustomFields)

An object with key-value pairs, where the key is the name of the custom field. An actual JSON object described by this might look like this:

{
    "customFields": {
        "height": "1.78m",
        "orderNumber": "441",
        "my_custom_field": "My Custom Value"
    }
}  

The data stored in the custom fields will be inserted in the text message template by replacing the placeholder {{<KEY>}}. Eg. {{height}}, {{orderNumber}}

countryIso
string 2 characters

Country ISO (two-letter) of the destination phone numbers (if provided in national format). Please note that if an international E.164 phone number format is provided in the to parameter, the countryIso will be ignored. Eg. FR for France, GB for United Kingdom. Note: It is "GB", not "UK", as per the ISO-3166 alpha 2.

allowInvalid
boolean
Default: false

By default an error will be thrown if any invalid numbers are detected in the to parameter. Set this parameter to true if you want to process the request even if invalid numbers are detected. The response will contain in the info object the property invalid, wich is an array with the detected invalid phone numbers

scheduledDate
string <date-time>

If you want to schedule the Viber message at a later date. The date provided must be in format YYYY-MM-DD HH:MM:SS (Eg. 2021-06-23 14:26:10). By default, the date and time in this parameter is treated as UTC. So if you want to schedule a Viber message to a french phone number at 16:00 (France is UTC+2), then you should set the parameter at 2021-06-23 14:00 (UTC). If you don't want to make the calculations, you can set this parameter as the date time of the destination (eg. 2021-06-23 16:00) and set the parameter isUtc to false. In this way, the API will automatically make the conversion from the destination timezone to UTC and set the scheduledDate accordingly

isUtc
boolean
Default: true

If set to false it will indicate that the scheduledDate parameter is not a date in UTC time, but the date relative to the timezone of the destination phone number. The API will calculate the offset and convert the date to UTC.

dlrCallbackUrl
string <url>

A valid URL to receive the delivery report update for the sent Viber message. If this parameter is set, it will overwrite the setting from Admin Dashboard > HTTP API > Oauth2 > Application settings

trackData
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

Allows to track messages a client provided ID. The trackData value will be passed back with the response and in all callbacks (webhooks). If the value is not a valid UUID (v1-v5) the API will not return an error but will discard this parameter

shortResponse
boolean
Default: false

If set to true, it will return the full info object and empty data object. For situations when you don't need the information in the data object and want to save bandwith

noTextDetails
boolean
Default: false

The response will not have the parameters data.text and data.textAnalysis. For situations when you send to large lists of phone numbers and don't need all response parameters (save bandwith)

showTimezone
boolean
Default: false

Shows the parameter timezone in the response, for each phone number

Responses

Request samples

Content type
application/json
{
  • "to": [
    ],
  • "from": "InfoText",
  • "templateId": 15,
  • "allowInvalid": true
}

Response samples

Content type
application/json
{
  • "info": {
    },
  • "data": [
    ]
}

Send Viber campaign


Sends Viber message to existing group(s) of contacts.

Note: This endpoint accepts idempotent requests by providing an additional idempotencyId parameter in body with a unique value generated by the client of type UUID v1-v5. To confirm that the server understood the request, the response will contain the header X-Idempotency-Id with your unique value. By using idempotency you can retry requests in case of network error or server not responding in time, without accidentally performing the same operation twice and have a guarantee of not being billed twice.

We recommend to always use Idempotency ID when sending Viber campaigns

Errors for POST /viber/campaigns

HTTP code Error code Type Description
400 1101 invalid_param The parameter groups is empty or not set
400 1140 invalid_param Group ID is not a valid group
400 1102 invalid_param Group is empty
400 1103 invalid_param The phone numbers array is too big (max. allowed: 25000 numbers)
400 1105 invalid_param The parameter from is empty or not set
400 1108 invalid_param The parameter scheduledDate is not a valid date
400 1109 invalid_param The parameter dlrCallbackUrl is not a valid URL
400 1111 invalid_param Idempotency Id provided is not a valid UUID (v1-v5)
400 1112 invalid_param The shortlink/attachment ID provided for tracking is invalid or not found
400 1116 invalid_param The scheduled date is in the past
400 1207 invalid_param The phone number provided is not valid
400 1210 invalid_param The phone numbers provided are invalid
403 1119 no_coverage No coverage or restricted destination
400 1113 insufficient_credit Insufficient credit
400 1114 insufficient_credit Credit limit reached. To increase the credit limit, please contact your account manager
400 1126 invalid_param The parameter templateId is not set
400 1127 invalid_param The parameter templateId is not valid
400 1128 invalid_param The template ID provided is not a valid template
403 1132 access_denied The template ID provided is not approved
403 1133 access_denied The template ID provided is not locked
Authorizations:
Request Body schema: application/json
groups
required
Array of integers <int32>

An array of identifiers for groups of contacts

from
required
string [ 3 .. 15 ] characters

The originator (sender name) of the text message (min 3, max 15 characters). If the originator used in this value is not approved, it will be overwritten by a default system originator (eg. InfoText). Read more about sender names

templateId
required
integer <int32>

Identifier of the approved Viber template

object (CustomFields)

An object with key-value pairs, where the key is the name of the custom field. An actual JSON object described by this might look like this:

{
    "customFields": {
        "height": "1.78m",
        "orderNumber": "441",
        "my_custom_field": "My Custom Value"
    }
}  

The data stored in the custom fields will be inserted in the text message template by replacing the placeholder {{<KEY>}}. Eg. {{height}}, {{orderNumber}}

scheduledDate
string <date-time>

If you want to schedule the Viber message at a later date. The date provided must be in format YYYY-MM-DD HH:MM:SS (Eg. 2021-06-23 14:26:10). By default, the date and time in this parameter is treated as UTC. So if you want to schedule a Viber message to a french phone number at 16:00 (France is UTC+2), then you should set the parameter at 2021-06-23 14:00 (UTC). If you don't want to make the calculations, you can set this parameter as the date time of the destination (eg. 2021-06-23 16:00) and set the parameter isUtc to false. In this way, the API will automatically make the conversion from the destination timezone to UTC and set the scheduledDate accordingly

isUtc
boolean
Default: true

If set to false it will indicate that the scheduledDate parameter is not a date in UTC time, but the date relative to the timezone of the destination phone number. The API will calculate the offset and convert the date to UTC.

dlrCallbackUrl
string <url>

A valid URL to receive the delivery report update for the sent Viber. If this parameter is set, it will overwrite the setting from Admin Dashboard > HTTP API > Oauth2 > Application settings

shortResponse
boolean
Default: false

If set to true, it will return the full info object and empty data object. For situations when you don't need the information in the data object and want to save bandwith

noTextDetails
boolean
Default: false

The response will not have the parameters data.text and data.textAnalysis. For situations when you send to large lists of phone numbers and don't need all response parameters (save bandwith)

showTimezone
boolean
Default: false

Shows the parameter timezone in the response, for each phone number

idempotencyId
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

A unique idempotency id generated by the client. For more information, refer to Idempotent requests. The API will return an error if the value provided is not a valid UUID (v1-v5)

Responses

Request samples

Content type
application/json
{
  • "groups": [
    ],
  • "from": "InfoText",
  • "templateId": 17,
  • "idempotencyId": "79661419-b349-4b60-8f70-7581a1b0e333"
}

Response samples

Content type
application/json
{
  • "info": {
    },
  • "data": [
    ]
}

Estimate Viber campaign

Estimate the cost of sending a Viber message to groups of phone numbers.

This endpoint is identical to /viber/campaign endpoint, but it will only simulate the Viber sending (no billing).

The request body and the response are the same as for /viber/campaign endpoint.

Errors for POST /viber/campaigns/estimate

HTTP code Error code Type Description
400 1101 invalid_param The parameter groups is empty or not set
400 1140 invalid_param Group ID is not a valid group
400 1102 invalid_param Group is empty
400 1103 invalid_param The phone numbers array is too big (max. allowed: 25000 numbers)
400 1105 invalid_param The parameter from is empty or not set
400 1108 invalid_param The parameter scheduledDate is not a valid date
400 1109 invalid_param The parameter dlrCallbackUrl is not a valid URL
400 1112 invalid_param The shortlink/attachment ID provided for tracking is invalid or not found
400 1116 invalid_param The scheduled date is in the past
400 1207 invalid_param The phone number provided is not valid
400 1210 invalid_param The phone numbers provided are invalid
403 1119 no_coverage No coverage or restricted destination
400 1113 insufficient_credit Insufficient credit
400 1114 insufficient_credit Credit limit reached. To increase the credit limit, please contact your account manager
400 1126 invalid_param The parameter templateId is not set
400 1127 invalid_param The parameter templateId is not valid
400 1128 invalid_param The template ID provided is not a valid template
403 1132 access_denied The template ID provided is not approved
403 1133 access_denied The template ID provided is not locked
Authorizations:
Request Body schema: application/json
groups
required
Array of integers <int32>

An array of identifiers for groups of contacts

from
required
string [ 3 .. 15 ] characters

The originator (sender name) of the text message (min 3, max 15 characters). If the originator used in this value is not approved, it will be overwritten by a default system originator (eg. InfoText). Read more about sender names

templateId
required
integer <int32>

Identifier of the approved Viber template

object (CustomFields)

An object with key-value pairs, where the key is the name of the custom field. An actual JSON object described by this might look like this:

{
    "customFields": {
        "height": "1.78m",
        "orderNumber": "441",
        "my_custom_field": "My Custom Value"
    }
}  

The data stored in the custom fields will be inserted in the text message template by replacing the placeholder {{<KEY>}}. Eg. {{height}}, {{orderNumber}}

scheduledDate
string <date-time>

If you want to schedule the Viber message at a later date. The date provided must be in format YYYY-MM-DD HH:MM:SS (Eg. 2021-06-23 14:26:10). By default, the date and time in this parameter is treated as UTC. So if you want to schedule a Viber message to a french phone number at 16:00 (France is UTC+2), then you should set the parameter at 2021-06-23 14:00 (UTC). If you don't want to make the calculations, you can set this parameter as the date time of the destination (eg. 2021-06-23 16:00) and set the parameter isUtc to false. In this way, the API will automatically make the conversion from the destination timezone to UTC and set the scheduledDate accordingly

isUtc
boolean
Default: true

If set to false it will indicate that the scheduledDate parameter is not a date in UTC time, but the date relative to the timezone of the destination phone number. The API will calculate the offset and convert the date to UTC.

dlrCallbackUrl
string <url>

A valid URL to receive the delivery report update for the sent Viber. If this parameter is set, it will overwrite the setting from Admin Dashboard > HTTP API > Oauth2 > Application settings

shortResponse
boolean
Default: false

If set to true, it will return the full info object and empty data object. For situations when you don't need the information in the data object and want to save bandwith

noTextDetails
boolean
Default: false

The response will not have the parameters data.text and data.textAnalysis. For situations when you send to large lists of phone numbers and don't need all response parameters (save bandwith)

showTimezone
boolean
Default: false

Shows the parameter timezone in the response, for each phone number

Responses

Request samples

Content type
application/json
{
  • "groups": [
    ],
  • "from": "InfoText",
  • "templateId": 17
}

Response samples

Content type
application/json
{
  • "info": {
    },
  • "data": [
    ]
}

Delete scheduled Viber message

Delete a scheduled Viber message by providing a valid identifier (msgId).

The cost of the deleted scheduled Viber message will be returned to the balance of the account.

Errors for DELETE /viber/scheduled/{msgId}

HTTP code Error code Type Description
403 1118 access_denied Only scheduled campaigns/messages can be deleted
404 1100 not_found Message ID provided was not found or is not scheduled
400 1115 invalid_param Message ID provided is not valid
Authorizations:
path Parameters
msgId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 3328fe13-2b99-4282-b62e-d891f5e452a8

Identifier of a scheduled Viber message

Responses

Request samples

curl --request DELETE \
  --url https://api.sms.cx/viber/scheduled/3328fe13-2b99-4282-b62e-d891f5e452a8 \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {
    }
}

Delete scheduled Viber campaign

Delete a scheduled Viber campaign by providing a valid identifier (campaignId).

The cost of the deleted scheduled Viber campaign will be returned to the balance of the account.

If part of the Viber campaign has already started, only scheduled messages will be deleted. Messages already sent cannot be deleted.

Errors for DELETE /viber/scheduled/campaign/{campaignId}

HTTP code Error code Type Description
403 1118 access_denied Only scheduled campaigns/messages can be deleted
404 1150 not_found Campaign ID provided was not found or is not scheduled
400 1155 invalid_param Campaign ID provided is not valid
Authorizations:
path Parameters
campaignId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: cbb72a72-0dfa-4288-b3d0-05fab904f0b2

Identifier of a scheduled Viber campaign

Responses

Request samples

curl --request DELETE \
  --url https://api.sms.cx/viber/scheduled/campaign/cbb72a72-0dfa-4288-b3d0-05fab904f0b2 \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
Example
{
  • "info": {
    }
}

Whatsapp

Send Whatsapp message


Sends Whatsapp message to a single phone number or to a list of phone numbers.

Note: This endpoint accepts idempotent requests by providing an additional idempotencyId parameter in body with a unique value generated by the client of type UUID v1-v5. To confirm that the server understood the request, the response will contain the header X-Idempotency-Id with your unique value. By using idempotency you can retry requests in case of network error or server not responding in time, without accidentally performing the same operation twice and have a guarantee of not being billed twice.

Errors for POST /whatsapp

HTTP code Error code Type Description
400 1104 invalid_param The parameter to is empty or not set
400 1105 invalid_param The parameter from is empty or not set
400 1108 invalid_param The parameter scheduledDate is not a valid date
400 1109 invalid_param The parameter dlrCallbackUrl is not a valid URL
400 1111 invalid_param Idempotency Id provided is not a valid UUID (v1-v5)
400 1112 invalid_param The shortlink/attachment ID provided for tracking is invalid or not found
400 1116 invalid_param The scheduled date is in the past
400 1103 invalid_param The phone numbers array is too big (max. allowed: 25000 numbers)
400 1207 invalid_param The phone number provided is not valid
400 1210 invalid_param The phone numbers provided are invalid
403 1119 no_coverage No coverage or restricted destination
400 1113 insufficient_credit Insufficient credit
400 1114 insufficient_credit Credit limit reached. To increase the credit limit, please contact your account manager
400 1126 invalid_param The parameter templateId is not set
400 1127 invalid_param The parameter templateId is not valid
400 1128 invalid_param The template ID provided is not a valid template
403 1132 access_denied The template ID provided is not approved
403 1133 access_denied The template ID provided is not locked
Authorizations:
Request Body schema: application/json
to
required
Array of strings

A string with single phone number or an array of phone numbers in international E.164 format or national format. If national format is provided, for better validation you must use the parameter countryIso to provide the country code of the destination phone number.

from
required
string [ 3 .. 15 ] characters

The originator (sender name) of the text message (min 3, max 15 characters). If the originator used in this value is not approved, it will be overwritten by a default system originator (eg. InfoText). Read more about sender names

templateId
required
integer <int32>

Identifier of the approved Whatsapp template

object (CustomFields)

An object with key-value pairs, where the key is the name of the custom field. An actual JSON object described by this might look like this:

{
    "customFields": {
        "height": "1.78m",
        "orderNumber": "441",
        "my_custom_field": "My Custom Value"
    }
}  

The data stored in the custom fields will be inserted in the text message template by replacing the placeholder {{<KEY>}}. Eg. {{height}}, {{orderNumber}}

countryIso
string 2 characters

Country ISO (two-letter) of the destination phone numbers (if provided in national format). Please note that if an international E.164 phone number format is provided in the to parameter, the countryIso will be ignored. Eg. FR for France, GB for United Kingdom. Note: It is "GB", not "UK", as per the ISO-3166 alpha 2.

allowInvalid
boolean
Default: false

By default an error will be thrown if any invalid numbers are detected in the to parameter. Set this parameter to true if you want to process the request even if invalid numbers are detected. The response will contain in the info object the property invalid, wich is an array with the detected invalid phone numbers

scheduledDate
string <date-time>

If you want to schedule the Whatsapp message at a later date. The date provided must be in format YYYY-MM-DD HH:MM:SS (Eg. 2021-06-23 14:26:10). By default, the date and time in this parameter is treated as UTC. So if you want to schedule a Whatsapp message to a french phone number at 16:00 (France is UTC+2), then you should set the parameter at 2021-06-23 14:00 (UTC). If you don't want to make the calculations, you can set this parameter as the date time of the destination (eg. 2021-06-23 16:00) and set the parameter isUtc to false. In this way, the API will automatically make the conversion from the destination timezone to UTC and set the scheduledDate accordingly

isUtc
boolean
Default: true

If set to false it will indicate that the scheduledDate parameter is not a date in UTC time, but the date relative to the timezone of the destination phone number. The API will calculate the offset and convert the date to UTC.

dlrCallbackUrl
string <url>

A valid URL to receive the delivery report update for the sent Whatsapp message. If this parameter is set, it will overwrite the setting from Admin Dashboard > HTTP API > Oauth2 > Application settings

trackData
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

Allows to track messages a client provided ID. The trackData value will be passed back with the response and in all callbacks (webhooks). If the value is not a valid UUID (v1-v5) the API will not return an error but will discard this parameter

shortResponse
boolean
Default: false

If set to true, it will return the full info object and empty data object. For situations when you don't need the information in the data object and want to save bandwith

noTextDetails
boolean
Default: false

The response will not have the parameters data.text and data.textAnalysis. For situations when you send to large lists of phone numbers and don't need all response parameters (save bandwith)

showTimezone
boolean
Default: false

Shows the parameter timezone in the response, for each phone number

idempotencyId
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

A unique idempotency id generated by the client. For more information, refer to Idempotent requests. The API will return an error if the value provided is not a valid UUID (v1-v5)

Responses

Request samples

Content type
application/json
Example
{
  • "to": [
    ],
  • "from": "InfoText",
  • "templateId": 19,
  • "customFields": {
    }
}

Response samples

Content type
application/json
Example
{
  • "info": {
    },
  • "data": [
    ]
}

Estimate Whatsapp message

Estimate the cost of sending a Whatsapp message.

This endpoint is identical to /whatsapp endpoint, but it will only simulate the Whatsapp sending (no billing).

The request body and the response are the same as for /whatsapp endpoint.

Errors for POST /whatsapp/estimate

HTTP code Error code Type Description
400 1104 invalid_param The parameter to is empty or not set
400 1105 invalid_param The parameter from is empty or not set
400 1108 invalid_param The parameter scheduledDate is not a valid date
400 1109 invalid_param The parameter dlrCallbackUrl is not a valid URL
400 1112 invalid_param The shortlink/attachment ID provided for tracking is invalid or not found
400 1116 invalid_param The scheduled date is in the past
400 1103 invalid_param The phone numbers array is too big (max. allowed: 25000 numbers)
400 1207 invalid_param The phone number provided is not valid
400 1210 invalid_param The phone numbers provided are invalid
403 1119 no_coverage No coverage or restricted destination
400 1113 insufficient_credit Insufficient credit
400 1114 insufficient_credit Credit limit reached. To increase the credit limit, please contact your account manager
400 1126 invalid_param The parameter templateId is not set
400 1127 invalid_param The parameter templateId is not valid
400 1128 invalid_param The template ID provided is not a valid template
403 1132 access_denied The template ID provided is not approved
403 1133 access_denied The template ID provided is not locked
Authorizations:
Request Body schema: application/json
to
required
Array of strings

A string with single phone number or an array of phone numbers in international E.164 format or national format. If national format is provided, for better validation you must use the parameter countryIso to provide the country code of the destination phone number.

from
required
string [ 3 .. 15 ] characters

The originator (sender name) of the text message (min 3, max 15 characters). If the originator used in this value is not approved, it will be overwritten by a default system originator (eg. InfoText). Read more about sender names

templateId
required
integer <int32>

Identifier of the approved Viber template

object (CustomFields)

An object with key-value pairs, where the key is the name of the custom field. An actual JSON object described by this might look like this:

{
    "customFields": {
        "height": "1.78m",
        "orderNumber": "441",
        "my_custom_field": "My Custom Value"
    }
}  

The data stored in the custom fields will be inserted in the text message template by replacing the placeholder {{<KEY>}}. Eg. {{height}}, {{orderNumber}}

countryIso
string 2 characters

Country ISO (two-letter) of the destination phone numbers (if provided in national format). Please note that if an international E.164 phone number format is provided in the to parameter, the countryIso will be ignored. Eg. FR for France, GB for United Kingdom. Note: It is "GB", not "UK", as per the ISO-3166 alpha 2.

allowInvalid
boolean
Default: false

By default an error will be thrown if any invalid numbers are detected in the to parameter. Set this parameter to true if you want to process the request even if invalid numbers are detected. The response will contain in the info object the property invalid, wich is an array with the detected invalid phone numbers

scheduledDate
string <date-time>

If you want to schedule the Whatsapp message at a later date. The date provided must be in format YYYY-MM-DD HH:MM:SS (Eg. 2021-06-23 14:26:10). By default, the date and time in this parameter is treated as UTC. So if you want to schedule a Whatsapp message to a french phone number at 16:00 (France is UTC+2), then you should set the parameter at 2021-06-23 14:00 (UTC). If you don't want to make the calculations, you can set this parameter as the date time of the destination (eg. 2021-06-23 16:00) and set the parameter isUtc to false. In this way, the API will automatically make the conversion from the destination timezone to UTC and set the scheduledDate accordingly

isUtc
boolean
Default: true

If set to false it will indicate that the scheduledDate parameter is not a date in UTC time, but the date relative to the timezone of the destination phone number. The API will calculate the offset and convert the date to UTC.

dlrCallbackUrl
string <url>

A valid URL to receive the delivery report update for the sent Whatsapp message. If this parameter is set, it will overwrite the setting from Admin Dashboard > HTTP API > Oauth2 > Application settings

trackData
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

Allows to track messages a client provided ID. The trackData value will be passed back with the response and in all callbacks (webhooks). If the value is not a valid UUID (v1-v5) the API will not return an error but will discard this parameter

shortResponse
boolean
Default: false

If set to true, it will return the full info object and empty data object. For situations when you don't need the information in the data object and want to save bandwith

noTextDetails
boolean
Default: false

The response will not have the parameters data.text and data.textAnalysis. For situations when you send to large lists of phone numbers and don't need all response parameters (save bandwith)

showTimezone
boolean
Default: false

Shows the parameter timezone in the response, for each phone number

Responses

Request samples

Content type
application/json
{
  • "to": [
    ],
  • "from": "InfoText",
  • "templateId": 19,
  • "allowInvalid": true
}

Response samples

Content type
application/json
{
  • "info": {
    },
  • "data": [
    ]
}

Delete scheduled Whatsapp message

Delete a scheduled Whatsapp message by providing a valid identifier (msgId).

The cost of the deleted scheduled Whatsapp message will be returned to the balance of the account.

Errors for DELETE /whatsapp/scheduled/{msgId}

HTTP code Error code Type Description
403 1118 access_denied Only scheduled campaigns/messages can be deleted
404 1100 not_found Message ID provided was not found or is not scheduled
400 1115 invalid_param Message ID provided is not valid
Authorizations:
path Parameters
msgId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 3328fe13-2b99-4282-b62e-d891f5e452a8

Identifier of a scheduled Whatsapp message

Responses

Request samples

curl --request DELETE \
  --url https://api.sms.cx/whatsapp/scheduled/3328fe13-2b99-4282-b62e-d891f5e452a8 \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {
    }
}

Multichannel

Send Multichannel message


Sends Multichannel message to a single phone number or to a list of phone numbers.

This endpoint was designed to handle big data objects (up to 25.000 Multichannel messages in one request).

If you have loops or iterations we recommend building the send object in your application, and make a single request to this endpoint. The time of making the requests will decrease - by doing a single request with multiple send objects vs making requests in a loop - and you won't have to worry about making concurrent API calls.

Note: This endpoint accepts idempotent requests by providing an additional idempotencyId parameter in body with a unique value generated by the client of type UUID v1-v5. To confirm that the server understood the request, the response will contain the header X-Idempotency-Id with your unique value. By using idempotency you can retry requests in case of network error or server not responding in time, without accidentally performing the same operation twice and have a guarantee of not being billed twice.

Errors for POST /multichannel

HTTP code Error code Type Description
400 1104 invalid_param The parameter to is empty or not set
400 1105 invalid_param The parameter from is empty or not set
400 1106 invalid_param The parameter from is not valid (min 3, max 11 characters)
400 1107 invalid_param The parameter text is empty or not set
400 1108 invalid_param The parameter scheduledDate is not a valid date
400 1109 invalid_param The parameter dlrCallbackUrl is not a valid URL
400 1111 invalid_param Idempotency Id provided is not a valid UUID (v1-v5)
400 1112 invalid_param The shortlink/attachment ID provided for tracking is invalid or not found
400 1116 invalid_param The scheduled date is in the past
400 1103 invalid_param The phone numbers array is too big (max. allowed: 25000 numbers)
400 1207 invalid_param The phone number provided is not valid
400 1210 invalid_param The phone numbers provided are invalid
403 1119 no_coverage No coverage or restricted destination
400 1113 insufficient_credit Insufficient credit
400 1114 insufficient_credit Credit limit reached. To increase the credit limit, please contact your account manager
400 1130 insufficient_credit Insufficient credit for failover sending
400 1124 invalid_param The parameter ttl is not a number
400 1125 invalid_param Min value for ttl is 300 seconds
400 1134 invalid_param Max value for ttl is 1209600 seconds (14 days)
400 1120 invalid_param The parameter strategy is empty or not set
400 1121 invalid_param The parameter strategy must have at least two channels
400 1122 invalid_param The parameter strategy must have channel sms as last element
400 1129 invalid_param The parameter strategy contains duplicate channels
400 1123 invalid_param The parameter channel is not valid. Allowed values:
403 1131 access_denied The strategy contains channels that are not active:
400 1126 invalid_param The parameter templateId is not set
400 1127 invalid_param The parameter templateId is not valid
400 1128 invalid_param The template ID provided is not a valid template
403 1132 access_denied The template ID provided is not approved
403 1133 access_denied The template ID provided is not locked
Authorizations:
Request Body schema: application/json
to
required
Array of strings

A string with single phone number or an array of phone numbers in international E.164 format or national format. If national format is provided, for better validation you must use the parameter countryIso to provide the country code of the destination phone number.

from
required
string [ 3 .. 15 ] characters

The originator (sender name) of the text message (min 3, max 11 characters). If the originator used in this value is not approved, it will be overwritten by a default system originator (eg. InfoText). Read more about sender names

required
Array of objects (Strategy)

An array of objects, in the order of sending. The API will try sending the message with the first channel in the strategy. If the delivery failed (Eg. Viber not installed, ttl has expired), then it will trigger the sending with the next channel in the strategy object. The last failover object must be always sms. Possible values for strategy.channel: viber, whatsapp, sms. Objects with channel viber and whatsapp have element templateId (the ID of the approved text template), and failover object with channel sms have the element text

ttl
integer <int32>
Default: 300

The time to live (ttl) defines the time in seconds that a channel has to deliver the message to the destination. After the time to live has expired and no Delivered report received, the next channel in the strategy will be triggered. This procedure is repeated until the last failover channel (sms) is triggered. Default ttl is 300 seconds (5 minutes). Max value 1209600 seconds (14 days)

countryIso
string 2 characters

Country ISO (two-letter) of the destination phone numbers (if provided in national format). Please note that if an international E.164 phone number format is provided in the to parameter, the countryIso will be ignored. Eg. FR for France, GB for United Kingdom. Note: It is "GB", not "UK", as per the ISO-3166 alpha 2.

allowInvalid
boolean
Default: false

By default an error will be thrown if any invalid numbers are detected in the to parameter. Set this parameter to true if you want to process the request even if invalid numbers are detected. The response will contain in the info object the property invalid, wich is an array with the detected invalid phone numbers

scheduledDate
string <date-time>

If you want to schedule the Multichannel message at a later date. The date provided must be in format YYYY-MM-DD HH:MM:SS (Eg. 2021-06-23 14:26:10). By default, the date and time in this parameter is treated as UTC. So if you want to schedule a Multichannel message to a french phone number at 16:00 (France is UTC+2), then you should set the parameter at 2021-06-23 14:00 (UTC). If you don't want to make the calculations, you can set this parameter as the date time of the destination (eg. 2021-06-23 16:00) and set the parameter isUtc to false. In this way, the API will automatically make the conversion from the destination timezone to UTC and set the scheduledDate accordingly

isUtc
boolean
Default: true

If set to false it will indicate that the scheduledDate parameter is not a date in UTC time, but the date relative to the timezone of the destination phone number. The API will calculate the offset and convert the date to UTC.

dlrCallbackUrl
string <url>

A valid URL to receive the delivery report update for the sent Multichannel message. If this parameter is set, it will overwrite the setting from Admin Dashboard > HTTP API > Oauth2 > Application settings

trackData
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

Allows to track messages a client provided ID. The trackData value will be passed back with the response and in all callbacks (webhooks). If the value is not a valid UUID (v1-v5) the API will not return an error but will discard this parameter

shortResponse
boolean
Default: false

If set to true, it will return the full info object and empty data object. For situations when you don't need the information in the data object and want to save bandwith

noTextDetails
boolean
Default: false

The response will not have the parameters data.text and data.textAnalysis. For situations when you send to large lists of phone numbers and don't need all response parameters (save bandwith)

showTimezone
boolean
Default: false

Shows the parameter timezone in the response, for each phone number

idempotencyId
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

A unique idempotency id generated by the client. For more information, refer to Idempotent requests. The API will return an error if the value provided is not a valid UUID (v1-v5)

Responses

Request samples

Content type
application/json
Example
{
  • "to": [
    ],
  • "from": "InfoText",
  • "strategy": [
    ],
  • "ttl": 300,
  • "allowInvalid": true,
}

Response samples

Content type
application/json
Example
{
  • "info": {
    },
  • "data": [
    ]
}

Estimate Multichannel message

Estimate the cost of sending a Multichannel message.

This endpoint is identical to /multichannel endpoint, but it will only simulate the Multichannel sending (no billing).

The request body and the response are the same as for /multichannel endpoint.

Errors for POST /multichannel/estimate

HTTP code Error code Type Description
400 1104 invalid_param The parameter to is empty or not set
400 1105 invalid_param The parameter from is empty or not set
400 1106 invalid_param The parameter from is not valid (min 3, max 11 characters)
400 1107 invalid_param The parameter text is empty or not set
400 1108 invalid_param The parameter scheduledDate is not a valid date
400 1109 invalid_param The parameter dlrCallbackUrl is not a valid URL
400 1112 invalid_param The shortlink/attachment ID provided for tracking is invalid or not found
400 1116 invalid_param The scheduled date is in the past
400 1103 invalid_param The phone numbers array is too big (max. allowed: 25000 numbers)
400 1207 invalid_param The phone number provided is not valid
400 1210 invalid_param The phone numbers provided are invalid
403 1119 no_coverage No coverage or restricted destination
400 1113 insufficient_credit Insufficient credit
400 1114 insufficient_credit Credit limit reached. To increase the credit limit, please contact your account manager
400 1130 insufficient_credit Insufficient credit for failover sending
400 1124 invalid_param The parameter ttl is not a number
400 1125 invalid_param Min value for ttl is 300 seconds
400 1134 invalid_param Max value for ttl is 1209600 seconds (14 days)
400 1120 invalid_param The parameter strategy is empty or not set
400 1121 invalid_param The parameter strategy must have at least two channels
400 1122 invalid_param The parameter strategy must have channel sms as last element
400 1129 invalid_param The parameter strategy contains duplicate channels
400 1123 invalid_param The parameter channel is not valid. Allowed values:
403 1131 access_denied The strategy contains channels that are not active:
400 1126 invalid_param The parameter templateId is not set
400 1127 invalid_param The parameter templateId is not valid
400 1128 invalid_param The template ID provided is not a valid template
403 1132 access_denied The template ID provided is not approved
403 1133 access_denied The template ID provided is not locked
Authorizations:
Request Body schema: application/json
to
required
Array of strings

A string with single phone number or an array of phone numbers in international E.164 format or national format. If national format is provided, for better validation you must use the parameter countryIso to provide the country code of the destination phone number.

from
required
string [ 3 .. 15 ] characters

The originator (sender name) of the text message (min 3, max 11 characters). If the originator used in this value is not approved, it will be overwritten by a default system originator (eg. InfoText). Read more about sender names

required
Array of objects (Strategy)

An array of objects, in the order of sending. The API will try sending the message with the first channel in the strategy. If the delivery failed (Eg. Viber not installed, ttl has expired), then it will trigger the sending with the next channel in the strategy object. The last failover object must be always sms. Possible values for strategy.channel: viber, whatsapp, sms. Objects with channel viber and whatsapp have element templateId (the ID of the approved text template), and failover object with channel sms have the element text

ttl
integer <int32>
Default: 300

The time to live (ttl) defines the time in seconds that a channel has to deliver the message to the destination. After the time to live has expired and no Delivered report received, the next channel in the strategy will be triggered. This procedure is repeated until the last failover channel (sms) is triggered. Default ttl is 300 seconds (5 minutes). Max value 1209600 seconds (14 days)

countryIso
string 2 characters

Country ISO (two-letter) of the destination phone numbers (if provided in national format). Please note that if an international E.164 phone number format is provided in the to parameter, the countryIso will be ignored. Eg. FR for France, GB for United Kingdom. Note: It is "GB", not "UK", as per the ISO-3166 alpha 2.

allowInvalid
boolean
Default: false

By default an error will be thrown if any invalid numbers are detected in the to parameter. Set this parameter to true if you want to process the request even if invalid numbers are detected. The response will contain in the info object the property invalid, wich is an array with the detected invalid phone numbers

scheduledDate
string <date-time>

If you want to schedule the Multichannel message at a later date. The date provided must be in format YYYY-MM-DD HH:MM:SS (Eg. 2021-06-23 14:26:10). By default, the date and time in this parameter is treated as UTC. So if you want to schedule a Multichannel message to a french phone number at 16:00 (France is UTC+2), then you should set the parameter at 2021-06-23 14:00 (UTC). If you don't want to make the calculations, you can set this parameter as the date time of the destination (eg. 2021-06-23 16:00) and set the parameter isUtc to false. In this way, the API will automatically make the conversion from the destination timezone to UTC and set the scheduledDate accordingly

isUtc
boolean
Default: true

If set to false it will indicate that the scheduledDate parameter is not a date in UTC time, but the date relative to the timezone of the destination phone number. The API will calculate the offset and convert the date to UTC.

dlrCallbackUrl
string <url>

A valid URL to receive the delivery report update for the sent Multichannel message. If this parameter is set, it will overwrite the setting from Admin Dashboard > HTTP API > Oauth2 > Application settings

trackData
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

Allows to track messages a client provided ID. The trackData value will be passed back with the response and in all callbacks (webhooks). If the value is not a valid UUID (v1-v5) the API will not return an error but will discard this parameter

shortResponse
boolean
Default: false

If set to true, it will return the full info object and empty data object. For situations when you don't need the information in the data object and want to save bandwith

noTextDetails
boolean
Default: false

The response will not have the parameters data.text and data.textAnalysis. For situations when you send to large lists of phone numbers and don't need all response parameters (save bandwith)

showTimezone
boolean
Default: false

Shows the parameter timezone in the response, for each phone number

Responses

Request samples

Content type
application/json
{
  • "to": [
    ],
  • "from": "InfoText",
  • "strategy": [
    ],
  • "ttl": 300,
  • "allowInvalid": true,
}

Response samples

Content type
application/json
{
  • "info": {
    },
  • "data": [
    ]
}

Send Multichannel campaign


Sends Multichannel message to existing group(s) of contacts.

Note: This endpoint accepts idempotent requests by providing an additional idempotencyId parameter in body with a unique value generated by the client of type UUID v1-v5. To confirm that the server understood the request, the response will contain the header X-Idempotency-Id with your unique value. By using idempotency you can retry requests in case of network error or server not responding in time, without accidentally performing the same operation twice and have a guarantee of not being billed twice.

We recommend to always use Idempotency ID when sending Multichannel campaigns

Errors for POST /multichannel/campaigns

HTTP code Error code Type Description
400 1101 invalid_param The parameter groups is empty or not set
400 1140 invalid_param Group ID is not a valid group
400 1102 invalid_param Group is empty
400 1103 invalid_param The phone numbers array is too big (max. allowed: 25000 numbers)
400 1105 invalid_param The parameter from is empty or not set
400 1106 invalid_param The parameter from is not valid (min 3, max 11 characters)
400 1107 invalid_param The parameter text is empty or not set
400 1108 invalid_param The parameter scheduledDate is not a valid date
400 1109 invalid_param The parameter dlrCallbackUrl is not a valid URL
400 1111 invalid_param Idempotency Id provided is not a valid UUID (v1-v5)
400 1112 invalid_param The shortlink/attachment ID provided for tracking is invalid or not found
400 1116 invalid_param The scheduled date is in the past
400 1103 invalid_param The phone numbers array is too big (max. allowed: 25000 numbers)
403 1119 no_coverage No coverage or restricted destination
400 1113 insufficient_credit Insufficient credit
400 1114 insufficient_credit Credit limit reached. To increase the credit limit, please contact your account manager
400 1124 invalid_param The parameter ttl is not a number
400 1125 invalid_param Min value for ttl is 300 seconds
400 1134 invalid_param Max value for ttl is 1209600 seconds (14 days)
400 1120 invalid_param The parameter strategy is empty or not set
400 1121 invalid_param The parameter strategy must have at least two channels
400 1122 invalid_param The parameter strategy must have channel sms as last element
400 1129 invalid_param The parameter strategy contains duplicate channels
400 1123 invalid_param The parameter channel is not valid. Allowed values:
403 1131 access_denied The strategy contains channels that are not active:
400 1126 invalid_param The parameter templateId is not set
400 1127 invalid_param The parameter templateId is not valid
400 1128 invalid_param The template ID provided is not a valid template
403 1132 access_denied The template ID provided is not approved
403 1133 access_denied The template ID provided is not locked
400 1130 insufficient_credit Insufficient credit for failover sending
Authorizations:
Request Body schema: application/json
groups
required
Array of integers <int32>

An array of identifiers for groups of contacts

from
required
string [ 3 .. 15 ] characters

The originator (sender name) of the text message (min 3, max 11 characters). If the originator used in this value is not approved, it will be overwritten by a default system originator (eg. InfoText). Read more about sender names

required
Array of objects (Strategy)

An array of objects, in the order of sending. The API will try sending the message with the first channel in the strategy. If the delivery failed (Eg. Viber not installed, ttl has expired), then it will trigger the sending with the next channel in the strategy object. The last failover object must be always sms. Possible values for strategy.channel: viber, whatsapp, sms. Objects with channel viber and whatsapp have element templateId (the ID of the approved text template), and failover object with channel sms have the element text

ttl
integer <int32>
Default: 300

The time to live (ttl) defines the time in seconds that a channel has to deliver the message to the destination. After the time to live has expired and no Delivered report received, the next channel in the strategy will be triggered. This procedure is repeated until the last failover channel (sms) is triggered. Default ttl is 300 seconds (5 minutes). Max value 1209600 seconds (14 days)

scheduledDate
string <date-time>

If you want to schedule the Multichannel message at a later date. The date provided must be in format YYYY-MM-DD HH:MM:SS (Eg. 2021-06-23 14:26:10). By default, the date and time in this parameter is treated as UTC. So if you want to schedule a Multichannel message to a french phone number at 16:00 (France is UTC+2), then you should set the parameter at 2021-06-23 14:00 (UTC). If you don't want to make the calculations, you can set this parameter as the date time of the destination (eg. 2021-06-23 16:00) and set the parameter isUtc to false. In this way, the API will automatically make the conversion from the destination timezone to UTC and set the scheduledDate accordingly

isUtc
boolean
Default: true

If set to false it will indicate that the scheduledDate parameter is not a date in UTC time, but the date relative to the timezone of the destination phone number. The API will calculate the offset and convert the date to UTC.

dlrCallbackUrl
string <url>

A valid URL to receive the delivery report update for the sent Multichannel message. If this parameter is set, it will overwrite the setting from Admin Dashboard > HTTP API > Oauth2 > Application settings

shortResponse
boolean
Default: false

If set to true, it will return the full info object and empty data object. For situations when you don't need the information in the data object and want to save bandwith

noTextDetails
boolean
Default: false

The response will not have the parameters data.text and data.textAnalysis. For situations when you send to large lists of phone numbers and don't need all response parameters (save bandwith)

showTimezone
boolean
Default: false

Shows the parameter timezone in the response, for each phone number

idempotencyId
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

A unique idempotency id generated by the client. For more information, refer to Idempotent requests. The API will return an error if the value provided is not a valid UUID (v1-v5)

Responses

Request samples

Content type
application/json
{
  • "groups": [
    ],
  • "from": "InfoText",
  • "strategy": [
    ],
  • "ttl": 300,
}

Response samples

Content type
application/json
{
  • "info": {
    },
  • "data": [
    ]
}

Estimate Multichannel campaign

Estimate the cost of sending a Multichannel message to groups of phone numbers.

This endpoint is identical to /multichannel/campaign endpoint, but it will only simulate the Multichannel sending (no billing).

The request body and the response are the same as for /multichannel/campaign endpoint.

Errors for POST /multichannel/campaigns/estimate

HTTP code Error code Type Description
400 1101 invalid_param The parameter groups is empty or not set
400 1140 invalid_param Group ID is not a valid group
400 1102 invalid_param Group is empty
400 1103 invalid_param The phone numbers array is too big (max. allowed: 25000 numbers)
400 1105 invalid_param The parameter from is empty or not set
400 1106 invalid_param The parameter from is not valid (min 3, max 11 characters)
400 1107 invalid_param The parameter text is empty or not set
400 1108 invalid_param The parameter scheduledDate is not a valid date
400 1109 invalid_param The parameter dlrCallbackUrl is not a valid URL
400 1112 invalid_param The shortlink/attachment ID provided for tracking is invalid or not found
400 1116 invalid_param The scheduled date is in the past
400 1103 invalid_param The phone numbers array is too big (max. allowed: 25000 numbers)
403 1119 no_coverage No coverage or restricted destination
400 1113 insufficient_credit Insufficient credit
400 1114 insufficient_credit Credit limit reached. To increase the credit limit, please contact your account manager
400 1124 invalid_param The parameter ttl is not a number
400 1125 invalid_param Min value for ttl is 300 seconds
400 1134 invalid_param Max value for ttl is 1209600 seconds (14 days)
400 1120 invalid_param The parameter strategy is empty or not set
400 1121 invalid_param The parameter strategy must have at least two channels
400 1122 invalid_param The parameter strategy must have channel sms as last element
400 1129 invalid_param The parameter strategy contains duplicate channels
400 1123 invalid_param The parameter channel is not valid. Allowed values:
403 1131 access_denied The strategy contains channels that are not active:
400 1126 invalid_param The parameter templateId is not set
400 1127 invalid_param The parameter templateId is not valid
400 1128 invalid_param The template ID provided is not a valid template
403 1132 access_denied The template ID provided is not approved
403 1133 access_denied The template ID provided is not locked
400 1130 insufficient_credit Insufficient credit for failover sending
Authorizations:
Request Body schema: application/json
groups
required
Array of integers <int32>

An array of identifiers for groups of contacts

from
required
string [ 3 .. 15 ] characters

The originator (sender name) of the text message (min 3, max 11 characters). If the originator used in this value is not approved, it will be overwritten by a default system originator (eg. InfoText). Read more about sender names

required
Array of objects (Strategy)

An array of objects, in the order of sending. The API will try sending the message with the first channel in the strategy. If the delivery failed (Eg. Viber not installed, ttl has expired), then it will trigger the sending with the next channel in the strategy object. The last failover object must be always sms. Possible values for strategy.channel: viber, whatsapp, sms. Objects with channel viber and whatsapp have element templateId (the ID of the approved text template), and failover object with channel sms have the element text

ttl
integer <int32>
Default: 300

The time to live (ttl) defines the time in seconds that a channel has to deliver the message to the destination. After the time to live has expired and no Delivered report received, the next channel in the strategy will be triggered. This procedure is repeated until the last failover channel (sms) is triggered. Default ttl is 300 seconds (5 minutes). Max value 1209600 seconds (14 days)

scheduledDate
string <date-time>

If you want to schedule the Multichannel message at a later date. The date provided must be in format YYYY-MM-DD HH:MM:SS (Eg. 2021-06-23 14:26:10). By default, the date and time in this parameter is treated as UTC. So if you want to schedule a Multichannel message to a french phone number at 16:00 (France is UTC+2), then you should set the parameter at 2021-06-23 14:00 (UTC). If you don't want to make the calculations, you can set this parameter as the date time of the destination (eg. 2021-06-23 16:00) and set the parameter isUtc to false. In this way, the API will automatically make the conversion from the destination timezone to UTC and set the scheduledDate accordingly

isUtc
boolean
Default: true

If set to false it will indicate that the scheduledDate parameter is not a date in UTC time, but the date relative to the timezone of the destination phone number. The API will calculate the offset and convert the date to UTC.

dlrCallbackUrl
string <url>

A valid URL to receive the delivery report update for the sent Multichannel message. If this parameter is set, it will overwrite the setting from Admin Dashboard > HTTP API > Oauth2 > Application settings

shortResponse
boolean
Default: false

If set to true, it will return the full info object and empty data object. For situations when you don't need the information in the data object and want to save bandwith

noTextDetails
boolean
Default: false

The response will not have the parameters data.text and data.textAnalysis. For situations when you send to large lists of phone numbers and don't need all response parameters (save bandwith)

showTimezone
boolean
Default: false

Shows the parameter timezone in the response, for each phone number

Responses

Request samples

Content type
application/json
{
  • "groups": [
    ],
  • "from": "InfoText",
  • "strategy": [
    ],
  • "ttl": 300,
  • "shortResponse": true
}

Response samples

Content type
application/json
{
  • "info": {
    },
  • "data": [ ]
}

Delete scheduled Multichannel message

Delete a scheduled Multichannel message by providing a valid identifier (msgId).

The cost of the deleted scheduled Multichannel message will be returned to the balance of the account.

Errors for DELETE /multichannel/scheduled/{msgId}

HTTP code Error code Type Description
403 1118 access_denied Only scheduled campaigns/messages can be deleted
404 1100 not_found Message ID provided was not found or is not scheduled
400 1115 invalid_param Message ID provided is not valid
Authorizations:
path Parameters
msgId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 396d2afa-1440-4f36-a365-b99a5ceaea23

Identifier of a scheduled Multichannel message

Responses

Request samples

curl --request DELETE \
  --url https://api.sms.cx/multichannel/scheduled/396d2afa-1440-4f36-a365-b99a5ceaea23 \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {
    }
}

Delete scheduled Multichannel campaign

Delete a scheduled Multichannel campaign by providing a valid identifier (campaignId).

The cost of the deleted scheduled Multichannel campaign will be returned to the balance of the account.

If part of the Multichannel campaign has already started, only scheduled messages will be deleted. Messages already sent cannot be deleted.

Errors for DELETE /multichannel/scheduled/campaign/{campaignId}

HTTP code Error code Type Description
403 1118 access_denied Only scheduled campaigns/messages can be deleted
404 1150 not_found Campaign ID provided was not found or is not scheduled
400 1155 invalid_param Campaign ID provided is not valid
Authorizations:
path Parameters
campaignId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 9f90f919-9b19-43db-921f-c8e05ae7054c

Identifier of a scheduled Multichannel campaign

Responses

Request samples

curl --request DELETE \
  --url https://api.sms.cx/multichannel/scheduled/campaign/9f90f919-9b19-43db-921f-c8e05ae7054c \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
Example
{
  • "info": {
    }
}

Groups

Get list of groups

Retrieves the list of existing groups of contacts. The groups are returned sorted by creation date, with the most recent group appearing first.

This endpoint should not return an error. If no groups are available, an empty data object is returned.

Authorizations:

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/groups \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create new group

Creates a new group.

Errors for POST /groups

HTTP code Error code Type Description
400 1204 invalid_param The name is empty or parameter name not set
400 1206 invalid_param The name provided is invalid (min 3, max 60 characters)
400 1211 duplicate_value You already have a group with this name
Authorizations:
Request Body schema: application/json
name
required
string [ 3 .. 60 ] characters

Name of the group

Responses

Request samples

Content type
application/json
{
  • "name": "My new group"
}

Response samples

Content type
application/json
{
  • "info": {
    }
}

Get group details

Retrieves the details of a group if a valid identifier was provided.

Errors for GET /groups/{groupId}

HTTP code Error code Type Description
404 1200 not_found Group ID not found
Authorizations:
path Parameters
groupId
required
integer <int32>
Example: 2245

Identifier of a group of contacts

query Parameters
short_response
boolean
Default: false

If set to true, it will return the full info object and an empty data object

limit
integer <int32>
Default: 500
Example: limit=100

A limit on the number of objects to be returned

next
string
Example: next=NTM2NTA

The next token used to retrieve additional data

previous
string
Example: previous=NTQxNTA

The previous token used to retrieve additional data

Responses

Request samples

curl --request GET \
  --url 'https://api.sms.cx/groups/2245?short_response=SOME_BOOLEAN_VALUE' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
Example
{
  • "info": {
    },
  • "data": [
    ]
}

Add contacts to group

Add contacts to a group if a valid identifier was provided.

Errors for POST /groups/{groupId}

HTTP code Error code Type Description
400 1203 invalid_param The parameter phoneNumbers is empty or not set
400 1208 invalid_param The parameter phoneNumbers must be an array of phone numbers
400 1207 invalid_param The phone number provided is not valid
400 1210 invalid_param The phone numbers provided are invalid
404 1200 not_found Group ID not found
Authorizations:
path Parameters
groupId
required
integer <int32>
Example: 2245

Identifier of a group of contacts

Request Body schema: application/json
One of
phoneNumbers
required
Array of strings

Array of phone numbers in international E.164 format or national format. If national format is provided, for better validation you must use the parameter countryIso to provide the country code of the destination phone number.

allowInvalid
boolean
Default: false

Set value true to not throw an error if invalid numbers are detected

countryIso
string 2 characters

Two-letter country ISO of the phone number you want to validate. If an international E.164 phone number format is provided the countryIso will be ignored

Responses

Request samples

Content type
application/json
Example
{
  • "phoneNumbers": [
    ],
  • "allowInvalid": true
}

Response samples

Content type
application/json
Example
{
  • "info": {
    }
}

Delete group

Deletes a group and all the contacts in the group

Errors for DELETE /groups/{groupId}

HTTP code Error code Type Description
404 1200 not_found Group ID not found
Authorizations:
path Parameters
groupId
required
integer <int32>
Example: 2245

Identifier of a group of contacts

Responses

Request samples

curl --request DELETE \
  --url https://api.sms.cx/groups/2245 \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {
    }
}

Empty group

Deletes all the contacts in a group.

Returns HTTP 204 No content if group is already empty.

Errors for GET /groups/{groupId}/empty

HTTP code Error code Type Description
404 1200 not_found Group ID not found
Authorizations:
path Parameters
groupId
required
integer <int32>
Example: 2245

Identifier of a group of contacts

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/groups/2245/empty \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {
    }
}

Export group to CSV

Exports the contacts from a group to a CSV file.

If the group is empty, an empty CSV file is returned (with first line headers).

Errors for GET /groups/{groupId}/csv

HTTP code Error code Type Description
404 1200 not_found Group ID not found
Authorizations:
path Parameters
groupId
required
integer <int32>
Example: 2245

Identifier of a group of contacts

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/groups/2245/csv \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/csv

Export group to XLSX

Exports the contacts from a group to a XLSX file (Excel).

If the group is empty, an empty XLSX file is returned (with first line headers).

Errors for GET /groups/{groupId}/xlsx

HTTP code Error code Type Description
404 1200 not_found Group ID not found
Authorizations:
path Parameters
groupId
required
integer <int32>
Example: 2245

Identifier of a group of contacts

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/groups/2245/xlsx \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Delete contact from group

Deletes a contact from a group if a valid group identifier was provided.

Errors for DELETE /groups/{groupId}/{phoneNumberId}

HTTP code Error code Type Description
404 1200 not_found Group ID not found
404 1202 not_found Phone number ID not found
Authorizations:
path Parameters
groupId
required
integer <int32>
Example: 2245

Identifier of a group of contacts

phoneNumberId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 68aa4d9f-ee25-4a32-95d0-7272efe3b238

Identifier of the phone number

Responses

Request samples

curl --request DELETE \
  --url https://api.sms.cx/groups/2245/68aa4d9f-ee25-4a32-95d0-7272efe3b238 \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {
    }
}

Update contact from group

Updates the specified contact by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Returns HTTP 204 No content if the parameters provided did not update the contact because the data was already the same.

Errors for PATCH /groups/{groupId}/{phoneNumberId}

HTTP code Error code Type Description
404 1202 not_found Phone number ID not found
400 1213 invalid_param At least one parameter required (phoneNumber, firstName, lastName, email, field1, field2, field3, field4, field5, customFields)
400 1215 duplicate_value The phone number already exists
Authorizations:
path Parameters
groupId
required
integer <int32>
Example: 2245

Identifier of a group of contacts

phoneNumberId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 68aa4d9f-ee25-4a32-95d0-7272efe3b238

Identifier of the phone number

Request Body schema: application/json
phoneNumber
string

Phone number in international E.164 format to replace the current phone number.

firstName
string

Data field for first name of the contact. Use placeholder {{firstName}} in text message for data replacement

lastName
string

Data field for last name of the contact. Use placeholder {{lastName}} in text message for data replacement

email
string

Data field for email of the contact. Use placeholder {{email}} in text message for data replacement

field1
string

Data field for extra information of the contact. Use placeholder {{field1}} in text message for data replacement

field2
string

Data field for extra information of the contact. Use placeholder {{field2}} in text message for data replacement

field3
string

Data field for extra information of the contact. Use placeholder {{field3}} in text message for data replacement

field4
string

Data field for extra information of the contact. Use placeholder {{field4}} in text message for data replacement

field5
string

Data field for extra information of the contact. Use placeholder {{field5}} in text message for data replacement

object (CustomFieldsObj)

An object with key-value pairs, where the key is the name of the custom field. An actual JSON object described by this might look like this:

{
    "customFields": {
        "height": "1.78m",
        "orderNumber": "441",
        "my_custom_field": "My Custom Value"
    }
}  

Maximum 20 custom fields allowed. The data stored in the custom fields can be used in the text message by using the placeholder {{<KEY>}}. Eg. {{height}}, {{orderNumber}}

Responses

Request samples

Content type
application/json
Example
{
  • "phoneNumber": "+447400772233"
}

Response samples

Content type
application/json
{
  • "info": {
    }
}

Conversations

Get conversations list

Retrieves the list of existing conversations. The list is sorted by last reply date, with the most recent reply appearing first.

This endpoint should not return an error. If no conversations are available, an empty data object is returned.

Authorizations:

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/conversations \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get conversation

Retrieves the details of a conversation if a valid identifier was provided.

Errors for GET /conversations/{conversationId}

HTTP code Error code Type Description
404 1180 not_found Conversation ID not found
Authorizations:
path Parameters
conversationId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: c38fa60d-ce8f-4918-8b9d-d991bc44cb73

Identifier of the conversation

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/conversations/c38fa60d-ce8f-4918-8b9d-d991bc44cb73 \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {
    },
  • "data": [
    ]
}

Mark conversation as read

Marks a conversation as read

Errors for GET /conversations/{conversationId}/read

HTTP code Error code Type Description
404 1180 not_found Conversation ID not found
Authorizations:
path Parameters
conversationId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: c38fa60d-ce8f-4918-8b9d-d991bc44cb73

Identifier of the conversation

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/conversations/c38fa60d-ce8f-4918-8b9d-d991bc44cb73/read \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {
    }
}

Send conversation reply via SMS

Sends a reply to a conversation using sms channel.

Errors for POST /conversations/{conversationId}/sms

HTTP code Error code Type Description
404 1180 not_found Conversation ID not found
400 1801 invalid_param The text message is empty or parameter text not set
400 1802 invalid_param The parameter text is invalid
400 1111 invalid_param Idempotency Id provided is not a valid UUID (v1-v5)
Authorizations:
path Parameters
conversationId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: c38fa60d-ce8f-4918-8b9d-d991bc44cb73

Identifier of the conversation

Request Body schema: application/json
text
required
string

The reply text message

Responses

Request samples

Content type
application/json
{
  • "text": "Text message with reply"
}

Response samples

Content type
application/json
{
  • "info": {
    },
  • "data": {
    }
}

Send conversation reply via Viber

Sends a reply to a conversation using viber channel.

Errors for POST /conversations/{conversationId}/viber

HTTP code Error code Type Description
404 1180 not_found Conversation ID not found
403 1181 access_denied Cannot reply with channel Viber. More than 24 hours since user reply
400 1801 invalid_param The text message is empty or parameter text not set
400 1802 invalid_param The parameter text is invalid
400 1811 invalid_param Text message too long (max 1000 characters)
400 1111 invalid_param Idempotency Id provided is not a valid UUID (v1-v5)
Authorizations:
path Parameters
conversationId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: c38fa60d-ce8f-4918-8b9d-d991bc44cb73

Identifier of the conversation

Request Body schema: application/json
text
required
string <= 1000 characters

The reply text message

richMedia
required
object

Responses

Request samples

Content type
application/json
{
  • "text": "Please give us more details",
  • "richMedia": { }
}

Response samples

Content type
application/json
{
  • "info": {
    },
  • "data": {
    }
}

Send conversation reply via Whatsapp

Sends a reply to a conversation using whatsapp channel.

Errors for POST /conversations/{conversationId}/whatsapp

HTTP code Error code Type Description
404 1180 not_found Conversation ID not found
403 1182 access_denied Cannot reply with channel Whatsapp. More than 24 hours since user reply
400 1801 invalid_param The text message is empty or parameter text not set
400 1802 invalid_param The parameter text is invalid
400 1811 invalid_param Text message too long (max 1000 characters)
400 1111 invalid_param Idempotency Id provided is not a valid UUID (v1-v5)
Authorizations:
path Parameters
conversationId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: c38fa60d-ce8f-4918-8b9d-d991bc44cb73

Identifier of the conversation

Request Body schema: application/json
text
required
string <= 1000 characters

The reply text message

richMedia
required
object

Responses

Request samples

Content type
application/json
{
  • "text": "Please give us more details",
  • "richMedia": { }
}

Response samples

Content type
application/json
{
  • "info": {
    },
  • "data": {
    }
}

Reports

Get advanced report

Retrieves the report for the specified filters. The only required parameters are the dates filters: period parameter or start_date and end_date.

If no data is available for the report, an empty data object is returned.

Errors for GET /reports

HTTP code Error code Type Description
400 1820 invalid_param The parameter period is not a valid date (format Y-m or Y)
400 1821 invalid_param The parameter start_date is not a valid date
400 1822 invalid_param The parameter end_date is not a valid date
400 1823 invalid_param The end date is before the start date
400 1824 invalid_param No period parameter or interval (start_date, end_date)
400 1825 invalid_param The parameter source is not valid
400 1826 invalid_param The parameter delivery_report is not valid (delivered, failed or sent)
400 1827 invalid_param The parameter country_iso is not for a valid country
Authorizations:
query Parameters
period
required
string
Example: period=2021-07

Period for the requested report in format Y-M or Y

start_date
required
string
Example: start_date=2021-03-01

The start date of the report in format Y-M-D

end_date
required
string
Example: end_date=2021-04-30

The end date of the report in format Y-M-D

channel
string
Enum: "sms" "viber" "whatsapp" "multichannel"
Example: channel=sms

Channel of the sent messages

source
string
Enum: "api" "excel" "webapp" "smpp" "plugin" "alerts"
Example: source=api

Source of the sent messages

delivery_report
string
Enum: "delivered" "failed" "sent" "accepted" "rejected" "scheduled"
Example: delivery_report=delivered
country_iso
string
Example: country_iso=fr

Two-letter country code defined in ISO-3166 alpha 2 standard (case insensitive)

short_response
boolean
Default: false

If set to true, it will return the full info object and an empty data object

limit
integer <int32>
Default: 500
Example: limit=100

A limit on the number of objects to be returned

next
string
Example: next=NTM2NTA

The next token used to retrieve additional data

previous
string
Example: previous=NTQxNTA

The previous token used to retrieve additional data

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/reports \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
Example
{
  • "info": {
    },
  • "data": [
    ]
}

Export advanced report to CSV

Exports the report for for the specified filters to a CSV file. The only required parameters are the dates filters: period parameter or start_date and end_date.

If no data is available for the report, an empty CSV file is returned (with first line headers).

Errors for GET /reports/csv

HTTP code Error code Type Description
400 1820 invalid_param The parameter period is not a valid date (format Y-m or Y)
400 1821 invalid_param The parameter start_date is not a valid date
400 1822 invalid_param The parameter end_date is not a valid date
400 1823 invalid_param The end date is before the start date
400 1824 invalid_param No period parameter or interval (start_date, end_date)
400 1825 invalid_param The parameter source is not valid
400 1826 invalid_param The parameter delivery_report is not valid (delivered, failed or sent)
400 1827 invalid_param The parameter country_iso is not for a valid country
400 1828 invalid_param The parameter channel is not valid (sms, viber, whatsapp, multichannel)
Authorizations:
query Parameters
period
required
string
Example: period=2021-07

Period for the requested report in format Y-M or Y

start_date
required
string
Example: start_date=2021-03-01

The start date of the report in format Y-M-D

end_date
required
string
Example: end_date=2021-04-30

The end date of the report in format Y-M-D

channel
string
Enum: "sms" "viber" "whatsapp" "multichannel"
Example: channel=sms

Channel of the sent messages

source
string
Enum: "api" "excel" "webapp" "smpp" "plugin" "alerts"
Example: source=api

Source of the sent messages

delivery_report
string
Enum: "delivered" "failed" "sent" "accepted" "rejected" "scheduled"
Example: delivery_report=delivered
country_iso
string
Example: country_iso=fr

Two-letter country code defined in ISO-3166 alpha 2 standard (case insensitive)

limit
integer <int32>
Default: 500
Example: limit=100

A limit on the number of objects to be returned

Responses

Request samples

curl --request GET \
  --url 'https://api.sms.cx/reports/csv?period=2021-07&start_date=2021-03-01&end_date=2021-04-30&channel=sms&source=api&delivery_report=delivered&country_iso=fr&limit=10' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/csv

Export advanced report to XLSX

Exports the report for for the specified filters to a XLSX file (Excel). The only required parameters are the dates filters: period parameter or start_date and end_date.

If no data is available for the report, an empty XLSX file is returned (with first line headers).

Errors for GET /reports/xlsx

HTTP code Error code Type Description
400 1820 invalid_param The parameter period is not a valid date (format Y-m or Y)
400 1821 invalid_param The parameter start_date is not a valid date
400 1822 invalid_param The parameter end_date is not a valid date
400 1823 invalid_param The end date is before the start date
400 1824 invalid_param No period parameter or interval (start_date, end_date)
400 1825 invalid_param The parameter source is not valid
400 1826 invalid_param The parameter delivery_report is not valid (delivered, failed or sent)
400 1827 invalid_param The parameter country_iso is not for a valid country
400 1828 invalid_param The parameter channel is not valid (sms, viber, whatsapp, multichannel)
Authorizations:
query Parameters
period
required
string
Example: period=2021-07

Period for the requested report in format Y-M or Y

start_date
required
string
Example: start_date=2021-03-01

The start date of the report in format Y-M-D

end_date
required
string
Example: end_date=2021-04-30

The end date of the report in format Y-M-D

channel
string
Enum: "sms" "viber" "whatsapp" "multichannel"
Example: channel=sms

Channel of the sent messages

source
string
Enum: "api" "excel" "webapp" "smpp" "plugin" "alerts"
Example: source=api

Source of the sent messages

delivery_report
string
Enum: "delivered" "failed" "sent" "accepted" "rejected" "scheduled"
Example: delivery_report=delivered
country_iso
string
Example: country_iso=fr

Two-letter country code defined in ISO-3166 alpha 2 standard (case insensitive)

limit
integer <int32>
Default: 500
Example: limit=100

A limit on the number of objects to be returned

Responses

Request samples

curl --request GET \
  --url 'https://api.sms.cx/reports/xlsx?period=2021-07&start_date=2021-03-01&end_date=2021-04-30&channel=sms&source=api&delivery_report=delivered&country_iso=fr&limit=10' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Get report for single SMS or Viber or Whatsapp or Multichannel

Returns the details of a single message if a valid identifier was provided.

Errors for GET /reports/single/{msgId}

HTTP code Error code Type Description
404 1160 not_found Campaign ID or msg ID provided was not found
400 1165 invalid_param Campaign ID or msg ID provided is not valid
Authorizations:
path Parameters
msgId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 9eeed792-9c8c-463c-a8e2-43ebf4494c02

Identifier of a sent message

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/reports/single/9eeed792-9c8c-463c-a8e2-43ebf4494c02 \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get list of sent campaigns

Returns a list of sent Campaigns, with the most recent appearing first.

If no data is available, an empty data object is returned.

Authorizations:
query Parameters
delivery_reports
boolean
Example: delivery_reports=true

The response will contain an object data.status with delivery report summary for each campaign

source
string
Enum: "api" "excel" "webapp" "smpp" "plugin" "alerts"
Example: source=api

Source of the sent messages

limit
integer <int32>
Default: 500
Example: limit=100

A limit on the number of objects to be returned

next
string
Example: next=NTM2NTA

The next token used to retrieve additional data

previous
string
Example: previous=NTQxNTA

The previous token used to retrieve additional data

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/reports/campaigns \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {
    },
  • "data": [
    ]
}

Get campaign report

Returns the details of a sent campaign if a valid identifier was provided.

Errors for GET /reports/campaigns/{campaignId}

HTTP code Error code Type Description
404 1150 not_found Campaign ID provided was not found
400 1155 invalid_param Campaign ID provided is not valid
Authorizations:
path Parameters
campaignId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 4baf0298-0c21-4df1-a60a-6e3476e95e0b

Identifier of a sent campaign

query Parameters
short_response
boolean
Default: false

If set to true, it will return the full info object and an empty data object

limit
integer <int32>
Default: 500
Example: limit=100

A limit on the number of objects to be returned

next
string
Example: next=NTM2NTA

The next token used to retrieve additional data

previous
string
Example: previous=NTQxNTA

The previous token used to retrieve additional data

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/reports/campaigns/4baf0298-0c21-4df1-a60a-6e3476e95e0b \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {
    },
  • "data": [
    ]
}

Export campaign report to CSV

Exports the details of a sent campaign to a CSV file.

Errors for GET /reports/campaigns/{campaignId}/csv

HTTP code Error code Type Description
404 1160 not_found Campaign ID or msg ID provided was not found
400 1165 invalid_param Campaign ID or msg ID provided is not valid
Authorizations:
path Parameters
campaignId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 4baf0298-0c21-4df1-a60a-6e3476e95e0b

Identifier of a sent campaign

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/reports/campaigns/4baf0298-0c21-4df1-a60a-6e3476e95e0b/csv \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/csv

Export campaign report to XLSX

Exports the details of a sent campaign to a XLSX file (Excel).

Errors for GET /reports/campaigns/{campaignId}/xlsx

HTTP code Error code Type Description
404 1160 not_found Campaign ID or msg ID provided was not found
400 1165 invalid_param Campaign ID or msg ID provided is not valid
Authorizations:
path Parameters
campaignId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 4baf0298-0c21-4df1-a60a-6e3476e95e0b

Identifier of a sent campaign

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/reports/campaigns/4baf0298-0c21-4df1-a60a-6e3476e95e0b/xlsx \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Get summary reports for a dimension

Retrieves a summary report for the specified dimensions.

The only required parameters are the dates for the report. The date filters can be: with period parameter or with start_date and end_date

For some dimensions (traffic and delivery) the summary report will aggregate on dates. If the summary report was requested with period parameter, the dates will be months or days. If it was requested with interval start_date - end_date, the dates will be the days between the interval.

Eg. period=2011, the property will be all months in the year period=2011-06, the property will be all days in month start_date=2021-06-15, end_date=2021-06-30, the properties will be all days between the interval

If no data is available for the summary report an empty data object is returned.

Errors for GET /reports/summary/{dimension}

HTTP code Error code Type Description
400 1829 invalid_param Invalid dimension. Accepted dimensions: source, channel, country, traffic, delivery
400 1820 invalid_param The parameter period is not a valid date (format Y-m or Y)
400 1821 invalid_param The parameter start_date is not a valid date
400 1822 invalid_param The parameter end_date is not a valid date
400 1823 invalid_param The end date is before the start date
400 1824 invalid_param No period parameter or interval (start_date, end_date)
Authorizations:
path Parameters
dimension
required
string
Enum: "source" "channel" "country" "traffic" "delivery"

Dimension for wich the summary report is requested

query Parameters
period
required
string
Example: period=2021-07

Period for the requested report in format Y-M or Y

start_date
required
string
Example: start_date=2021-03-01

The start date of the report in format Y-M-D

end_date
required
string
Example: end_date=2021-04-30

The end date of the report in format Y-M-D

limit
integer <int32>
Default: 500
Example: limit=100

A limit on the number of objects to be returned

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/reports/summary/%7Bdimension%7D \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
Example
{
  • "data": {
    }
}

Numbers

Receive details for a phone number lookup Webhook

POST https://{{your-endpoint}}/path-for-number-lookup

The SMS.CX API will make a POST request to your webhook endpoint, which must return HTTP response 200. If the response is not HTTP 200, SMS.CX API will retry the callback request for the next 24 hours using an exponential backoff algorithm.

Authorizations:
None
Request Body schema: application/json
event
required
string
Value: "number_lookup"

Event for which the callback request is made

required
Array of objects (DataNumberLookupWebhook)

Event data, grouped in multiple objects (up to 200 in a request)

Responses

Request samples

Content type
application/json
{
  • "event": "number_lookup",
  • "data": [
    ]
}

Validate number

Validates a single phone number, provided in international E.164 format.

The endpoint returns error if phone number is invalid.

Errors for GET /numbers/validate/{phoneNumber}

HTTP code Error code Type Description
400 1207 invalid_param The phone number is invalid
Authorizations:
path Parameters
phoneNumber
required
string
Example: +33612246450

Phone number in international E.164 format (eg. +33612424105). The leading plus sign of the international format can be set as is, ommited or url encoded. The API will automatically format and set the plus sign.
The following values are considered valid:

  • +33612424105
  • 33612424105
  • %2B33612424105

Responses

Request samples

curl --request GET \
  --url 'https://api.sms.cx/numbers/validate/+33612246450' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Validate numbers in bulk

Validate a list of phone numbers. You can validate in bulk up to 40.000 phone numbers.

The endpoint does not return error if phone numbers are invalid.

This method will validate the list of phone numbers and return an array of objects, preserving the order of the list provided and not excluding the invalid phone numbers.

An invalid phone number will have the parameter invalid with value true in the response object.

Errors for POST /numbers/validate

HTTP code Error code Type Description
400 1203 invalid_param The parameter phoneNumbers is empty or not set
400 1208 invalid_param The parameter phoneNumbers must be an array of phone numbers
400 1205 invalid_param The phone numbers array is too big (max. allowed: 40000 numbers)
Authorizations:
Request Body schema: application/json
phoneNumbers
required
Array of strings

Array of phone numbers in international E.164 format or national format. If national format is provided, for better validation you must use the parameter countryIso to provide the country code of the destination phone number.

countryIso
string 2 characters

Two-letter country ISO of the phone number you want to validate. If an international E.164 phone number format is provided the countryIso will be ignored

Responses

Request samples

Content type
application/json
Example
{
  • "phoneNumbers": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "info": {
    },
  • "data": [
    ]
}

Lookup number

Lookup a single phone number, provided in international E.164 format. Returns info about status of the number (ACTIVE, ABSENT), if the phone number is ported, roaming, original and current network operator.

The endpoint returns error if phone number is invalid.

Statuses of phone number lookup

Status Description
ACTIVE Phone number is reachable
ABSENT Phone number is not reachable
BARRED Phone number has a block from their operator
UNKNOWN Unknown subscriber. Phone number is not reachable
FAILED Lookup for this phone number failed

Errors for GET /numbers/lookup/{phoneNumber}

HTTP code Error code Type Description
400 1207 invalid_param The phone number is invalid
403 1214 no_coverage No coverage or restricted destination
400 1113 insufficient_credit Insufficient credit
400 1114 insufficient_credit Credit limit reached. To increase the credit limit, please contact your account manager
400 1212 invalid_param Invalid request parameters
Authorizations:
path Parameters
phoneNumber
required
string
Example: +33612246450

Phone number in international E.164 format (eg. +33612424105). The leading plus sign of the international format can be set as is, ommited or url encoded. The API will automatically format and set the plus sign.
The following values are considered valid:

  • +33612424105
  • 33612424105
  • %2B33612424105

Responses

Request samples

curl --request GET \
  --url 'https://api.sms.cx/numbers/lookup/+33612246450' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
Example
{
  • "data": {
    }
}

Get list of bulk lookup campaigns

Get list of bulk lookup campaigns

Authorizations:
query Parameters
limit
integer <int32>
Default: 500
Example: limit=100

A limit on the number of objects to be returned

next
string
Example: next=NTM2NTA

The next token used to retrieve additional data

previous
string
Example: previous=NTQxNTA

The previous token used to retrieve additional data

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/numbers/lookup \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Lookup numbers in bulk

Lookup a list of phone numbers. The result of the bulk phone lookup: status of the number (ACTIVE, ABSENT), if the phone numbers are ported, roaming, original and current network operator. You can lookup in bulk up to 40.000 phone numbers.

The endpoint does not return error if phone numbers are invalid.

Statuses of phone number lookup

Status Description
ACTIVE Phone number is reachable
ABSENT Phone number is not reachable
BARRED Phone number has a block from their operator
UNKNOWN Unknown subscriber. Phone number is not reachable
FAILED Lookup for this phone number failed

Errors for POST /numbers/lookup

HTTP code Error code Type Description
400 1203 invalid_param The parameter 'phoneNumbers' is empty or not set
400 1208 invalid_param The parameter 'phoneNumbers' must be an array of phone numbers
400 1205 invalid_param The phone numbers array is too big (max. allowed: 40000 numbers)
400 1209 invalid_param The parameter 'lookupCallbackUrl' is not a valid URL
403 1214 no_coverage No coverage or restricted destination
400 1216 invalid_param No valid numbers provided or no coverage
400 1113 insufficient_credit Insufficient credit
400 1114 insufficient_credit Credit limit reached. To increase the credit limit, please contact your account manager
Authorizations:
Request Body schema: application/json
phoneNumbers
required
Array of strings

Array of phone numbers in international E.164 format or national format. If national format is provided, for better validation/lookup you must use the parameter countryIso to provide the country code of the destination phone number.

countryIso
string 2 characters

Two-letter country ISO of the phone number you want to lookup. If an international E.164 phone number format is provided the countryIso will be ignored

lookupCallbackUrl
string <url>

A valid URL to receive results for the phone number lookup.
Note: If this parameter is set, it will overwrite the setting from Admin Dashboard > HTTP API > Oauth2 > Application settings

Responses

Request samples

Content type
application/json
Example
{
  • "phoneNumbers": [
    ],
}

Response samples

Content type
application/json
Example
{
  • "info": {
    },
  • "data": [
    ]
}

Get Single Lookup result

Get details of a single number lookup.

Errors for GET /numbers/lookup/lookupId/{lookupId}

HTTP code Error code Type Description
400 1217 invalid_param The lookupId provided is invalid
404 1219 not_found Lookup ID not found
Authorizations:
path Parameters
lookupId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 68aa4d9f-ee25-4a32-95d0-7272efe3b238

Identifier of the number lookup

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/numbers/lookup/lookupId/68aa4d9f-ee25-4a32-95d0-7272efe3b238 \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Bulk Lookup result

Get details of a bulk phone number lookup.

Errors for GET /numbers/lookup/lookupBulkId/{lookupBulkId}

HTTP code Error code Type Description
400 1218 invalid_param The lookupBulkId provided is invalid
404 1220 not_found Lookup Bulk ID not found
Authorizations:
path Parameters
lookupBulkId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 68aa4d9f-ee25-4a32-95d0-7272efe3b238

Identifier of the bulk number lookup campaign

query Parameters
limit
integer <int32>
Default: 500
Example: limit=100

A limit on the number of objects to be returned

next
string
Example: next=NTM2NTA

The next token used to retrieve additional data

previous
string
Example: previous=NTQxNTA

The previous token used to retrieve additional data

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/numbers/lookup/lookupBulkId/68aa4d9f-ee25-4a32-95d0-7272efe3b238 \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {
    },
  • "data": [
    ]
}

Export number lookup campaign to CSV

Exports the details of a phone number lookup campaign to a CSV file.

Errors for GET /numbers/lookup/lookupBulkId/{lookupBulkId}/csv

HTTP code Error code Type Description
400 1218 invalid_param The lookupBulkId provided is invalid
404 1220 not_found Lookup Bulk ID not found
Authorizations:
path Parameters
lookupBulkId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 68aa4d9f-ee25-4a32-95d0-7272efe3b238

Identifier of the bulk number lookup campaign

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/numbers/lookup/lookupBulkId/4baf0298-0c21-4df1-a60a-6e3476e95e0b/csv \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/csv

Export number lookup campaign to XLSX

Exports the details of a phone number lookup campaign to a XLSX file.

Errors for GET /numbers/lookup/lookupBulkId/{lookupBulkId}/xlsx

HTTP code Error code Type Description
400 1218 invalid_param The lookupBulkId provided is invalid
404 1220 not_found Lookup Bulk ID not found
Authorizations:
path Parameters
lookupBulkId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 68aa4d9f-ee25-4a32-95d0-7272efe3b238

Identifier of the bulk number lookup campaign

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/numbers/lookup/lookupBulkId/4baf0298-0c21-4df1-a60a-6e3476e95e0b/xlsx \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Get available numbers for rent

Get the list of available phone numbers for rent

Errors for GET /numbers/rent/available/{countryIso}

HTTP code Error code Type Description
400 2003 invalid_param Country ISO provided is invalid
Authorizations:
path Parameters
countryIso
required
string 2 characters
Example: FR
query Parameters
features
integer <int32>
Enum: "1" "2" "3"
Example: features=3

Filter by number features (1 - receive SMS, 2 - send SMS, 1 + 2 = 3 - send and receive SMS)

number_type
string
Enum: "mobile" "landline"
Example: number_type=mobile

Filter by type of phone number

setup_time
string
Enum: "instant" "delayed"
Example: setup_time=instant

Filter by time of setup

registration
boolean
Example: registration=true

Filter by registration

inbound_sms_sender
boolean
Example: inbound_sms_sender=true

Filter numbers that support inbound SMS from alphanumeric sender ID

include
string [ 17 .. 1 ] characters
Example: include=4559

Filter phone numbers that include the following digits

exclude
string [ 17 .. 1 ] characters
Example: exclude=1554

Filter phone numbers that exclude the following digits

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/numbers/rent/available/FR \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get list of your rented numbers

Get the list of your rented phone numbers

Authorizations:
query Parameters
features
integer <int32>
Enum: "1" "2" "3"
Example: features=3

Filter by number features (1 - receive SMS, 2 - send SMS, 1 + 2 = 3 - send and receive SMS)

country_iso
string
Example: country_iso=fr

Filter by country iso. Two-letter country code defined in ISO-3166 alpha 2 standard (case insensitive)

number_type
string
Enum: "mobile" "landline"
Example: number_type=mobile

Filter by type of phone number

active_rent
boolean
Example: active_rent=true

Filter by active rent

inbound_sms_sender
boolean
Example: inbound_sms_sender=true

Filter numbers that support inbound SMS from alphanumeric sender ID

include
string [ 17 .. 1 ] characters
Example: include=4559

Filter phone numbers that include the following digits

exclude
string [ 17 .. 1 ] characters
Example: exclude=1554

Filter phone numbers that exclude the following digits

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/numbers/rent \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Rent phone number

Rent a phone number for a period of time (1, 7 or 30 days).

Errors for POST /numbers/rent

HTTP code Error code Type Description
400 1222 invalid_param Invalid parameter numberId
400 1224 invalid_param Rent period is invalid (1, 7 or 30 days)
400 1225 invalid_param Parameter autorenew must be type boolean
400 1226 invalid_param The parameter callbackUrl is not a valid url
400 1229 invalid_param Rent period is lower than the minimum rent period of this number
400 1113 insufficient_credit Insufficient credit
400 1234 invalid_param Registration ID provided is invalid or not found
403 1231 access_denied Cannot rent this phone number (already rented)
404 1230 not_found Number ID not found or number is not available for rent anymore
Authorizations:
Request Body schema: application/json
numberId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

Unique identifier of the phone number from the available rental list

rentPeriod
required
integer <int32>
Enum: "1" "7" "30"

Rental period of the phone number (in days)

autoRenew
boolean
Default: false

Auto renew the rental of the phone number at the end of the rental period

callbackUrl
string or null <url>

Callback URL (or webhook) to get the received SMS on the rented phone number

registrationId
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

Applicable if the phone number requires registration. Unique identifier of the registration details for this phone number

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "info": {
    }
}

Get status of rent

Get details of an existing rental.

Errors for GET /numbers/rent/{rentId}

HTTP code Error code Type Description
400 1221 invalid_param The rentId provided is invalid
404 1223 not_found Rent ID not found
Authorizations:
path Parameters
rentId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 471ddea7-930c-49e8-8e99-2683834dd92e

Identifier of the rental operation

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/numbers/rent/471ddea7-930c-49e8-8e99-2683834dd92e \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {
    }
}

Cancel rent for phone number

Cancel rent for a phone number. Phone numbers rentals can be canceled within the first 30 minutes of renting period. Your account will be credited for the phone number rental cost.

Errors for DELETE /numbers/rent/{rentId}

HTTP code Error code Type Description
400 1221 invalid_param The rentId provided is invalid
403 1227 access_denied Cannot cancel this rent. More than 30 minutes passed from start of renting period
403 1232 access_denied Cannot cancel this rent. The number has already been used for inbound SMS
404 1223 not_found Rent ID not found
Authorizations:
path Parameters
rentId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 471ddea7-930c-49e8-8e99-2683834dd92e

Identifier of the rental operation

Responses

Request samples

curl --request DELETE \
  --url https://api.sms.cx/numbers/rent/471ddea7-930c-49e8-8e99-2683834dd92e \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {
    }
}

Renew rent for phone number

Renew the rental of a phone number.

Errors for PATCH /numbers/rent/{rentId}

HTTP code Error code Type Description
400 1221 invalid_param The rentId provided is invalid
400 1224 invalid_param Rent period is invalid (1, 7 or 30 days)
400 1225 invalid_param Parameter autorenew must be type boolean
400 1226 invalid_param The parameter callbackUrl is not a valid url
400 1229 invalid_param Rent period is lower than the minimum rent period of this number
400 1113 insufficient_credit Insufficient credit
403 1228 access_denied The rent cannot be renewed (rent already expired or phone number is not available for future rent)
404 1223 not_found Rent ID not found
Authorizations:
path Parameters
rentId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 471ddea7-930c-49e8-8e99-2683834dd92e

Identifier of the rental operation

Request Body schema: application/json
rentPeriod
integer <int32>
Enum: "1" "7" "30"

Rental period of the phone number (in days). This parameter is optional. If not present, the phone number rent will renew with the current rent period.

autoRenew
boolean
Default: false

Auto renew the rent of the phone number at the end of the rental period

callbackUrl
string or null <url>

Callback URL (or webhook) to get the SMS that is received on the rented phone number (inbound SMS)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "info": {
    }
}

Get inbound SMS from rented number

Get a list of SMS received on the rented phone number.

Errors for GET /numbers/rent/{rentId}/inbound

HTTP code Error code Type Description
400 1221 invalid_param The rentId provided is invalid
404 1223 not_found Rent ID not found
Authorizations:
path Parameters
rentId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 471ddea7-930c-49e8-8e99-2683834dd92e

Identifier of the rental operation

query Parameters
limit
integer <int32>
Default: 500
Example: limit=100

A limit on the number of objects to be returned

next
string
Example: next=NTM2NTA

The next token used to retrieve additional data

previous
string
Example: previous=NTQxNTA

The previous token used to retrieve additional data

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/numbers/rent/471ddea7-930c-49e8-8e99-2683834dd92e/inbound \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {
    },
  • "data": [
    ]
}

Edit settings for active rent

Edit settings of active rent

Errors for GET /numbers/rent/{rentId}/edit

HTTP code Error code Type Description
400 1221 invalid_param The rentId provided is invalid
400 1225 invalid_param Parameter autorenew must be type boolean
400 1226 invalid_param The parameter callbackUrl is not a valid url
400 1233 invalid_param At least one parameter required (autoRenew, callbackUrl)
404 1223 not_found Rent ID not found
Authorizations:
path Parameters
rentId
required
string <uuid> 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 471ddea7-930c-49e8-8e99-2683834dd92e

Identifier of the rental operation

Request Body schema: application/json
autoRenew
boolean
Default: false

Auto renew the rent of the phone number at the end of the rental period

callbackUrl
string or null <url>

Callback URL (or webhook) to get the SMS that is received on the rented phone number (inbound SMS)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "info": {
    }
}

Originators

Delete originator

Deletes an originator if a valid identifier was provided.

Errors for DELETE /originators/{originatorId}

HTTP code Error code Type Description
404 1300 not_found Originator ID not found
Authorizations:
path Parameters
originatorId
required
integer <int32>
Example: 1388

Identifier of the originator

Responses

Request samples

curl --request DELETE \
  --url https://api.sms.cx/originators/1388 \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {
    }
}

Get originators list

Retrieves the list of existing originators (sender ids). The originators are returned sorted by creation date, with the most recent group appearing first.

This endpoint should not return an error. If no originators are available, an empty data object is returned

Authorizations:

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/originators \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create new originator

Creates and submits an originator for approval.

Errors for POST /originators

HTTP code Error code Type Description
400 1301 invalid_param The originator is empty or parameter originator not set
400 1303 invalid_param The parameter originator can contain only letters and numbers
400 1304 invalid_param The alphanumeric originator provided is invalid (min 3, max 11 characters)
400 1305 invalid_param The numeric originator provided is invalid (min 3, max 15 characters)
400 1306 duplicate_value Originator already exists
Authorizations:
Request Body schema: application/json
originator
required
string [ 3 .. 15 ] characters ^[a-zA-Z0-9]+$

Responses

Request samples

Content type
application/json
{
  • "originator": "MyCompany"
}

Response samples

Content type
application/json
{
  • "info": {
    }
}

Templates

Get templates list

Retrieves the list of existing templates. The templates are returned sorted by creation date, with the most recent templates appearing first.

This endpoint should not return an error. If no templates are available, an empty data object is returned.

Authorizations:

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/templates \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create template

Creates a new template.

Errors for POST /templates

HTTP code Error code Type Description
400 1801 invalid_param The text message is empty or parameter text not set
400 1802 invalid_param The parameter text is invalid
400 1803 invalid_param The name provided is invalid (min 3, max 100 characters)
400 1806 invalid_param The parameter channel is not valid. Allowed values:
400 1805 duplicate_value You already have a template with this name
400 1811 invalid_param Text message too long (max 1000 characters)
400 1808 invalid_param Button caption is too long (min 1, max. 30 characters)
400 1809 invalid_param Invalid target URL
400 1810 invalid_param Invalid image URL
Authorizations:
Request Body schema: application/json
name
string [ 3 .. 100 ] characters

The name of the template. If this parameter is omitted the name of the template will be set by the API eg. "Template 2021-06-11 21:00:00"

text
required
string

Template text. For channels viber and whatsapp the max. length is 1000 characters

channel
string
Enum: "sms" "viber" "whatsapp"

The channel for wich the template is saved

object (RichMedia)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Summer Sale 2021",
  • "text": "Redeem this voucher in the next 30 days to get a 30% discount off all Summer Fashion {shortlink:xSgW}"
}

Response samples

Content type
application/json
Example
{
  • "info": {
    }
}

Get template

Retrieves the details of a template if a valid identifier was provided.

Errors for GET /templates/{templateId}

HTTP code Error code Type Description
404 1800 not_found Template ID not found
Authorizations:
path Parameters
templateId
required
integer <int32>
Example: 39774

Identifier of the template

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/templates/39774 \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
Example
{
  • "data": {
    }
}

Delete template

Deletes a template if a valid identifier was provided.

Errors for DELETE /templates/{templateId}

HTTP code Error code Type Description
404 1800 not_found Template ID not found
Authorizations:
path Parameters
templateId
required
integer <int32>
Example: 39774

Identifier of the template

Responses

Request samples

curl --request DELETE \
  --url https://api.sms.cx/templates/39774 \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {
    }
}

Update template

Updates the specified template by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Returns HTTP 204 No content if the parameters provided did not update the template because the data was already the same.

Errors for PATCH /templates/{templateId}

HTTP code Error code Type Description
404 1800 not_found Template ID not found
400 1802 invalid_param The parameter text is invalid
400 1803 invalid_param The name provided is invalid (min 3, max 100 characters)
400 1804 invalid_param At least one parameter required (name, text)
400 1811 invalid_param Text message too long (max 1000 characters)
403 1812 access_denied Template is locked for editing
400 1810 invalid_param Invalid image URL
400 1808 invalid_param Button caption is too long (min 1, max. 30 characters)
400 1809 invalid_param Invalid target URL
400 1805 duplicate_value You already have a template with this name
Authorizations:
path Parameters
templateId
required
integer <int32>
Example: 39774

Identifier of the template

Request Body schema: application/json
name
string [ 3 .. 100 ] characters

The name of the template. If this parameter is omitted the name of the template will be set by the API eg. "Template 2021-06-11 21:00:00"

text
string

Template text. For channels viber and whatsapp the max. length is 1000 characters

channel
string
Enum: "sms" "viber" "whatsapp"

The channel for wich the template is saved

object (RichMedia)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "My new template name",
  • "text": "My new template text."
}

Response samples

Content type
application/json
Example
{
  • "info": {
    }
}

Receive details of visitor of shortlink Webhook

POST https://{{your-endpoint}}/path-for-shortlink-hit

The SMS.CX API will make a POST request to your webhook endpoint, which must return HTTP response 200. If the response is not HTTP 200, SMS.CX API will retry the callback request for the next 24 hours using an exponential backoff algorithm.

Authorizations:
None
Request Body schema: application/json
event
required
string
Enum: "shortlink_hit" "shortlink_hit_update"

Event for which the callback request is made

required
Array of objects (DataShortlinkHit)

Event type data, grouped in multiple objects (up to 200 in a request)

Responses

Request samples

Content type
application/json
{
  • "event": "shortlink_hit",
  • "data": [
    ]
}

Get shortlink hits

Retrieves the hits details (phone number, device, model, operating system, browser, city, country, etc.) of a shortlink if a valid identifier was provided.

Errors for GET /shortlinks/{shortId}

HTTP code Error code Type Description
404 1400 not_found Shortlink ID not found
Authorizations:
path Parameters
shortId
required
string
Example: KgTX

Identifier of the shortlink

query Parameters
short_response
boolean
Default: false

If set to true, it will return the full info object and an empty data object

limit
integer <int32>
Default: 500
Example: limit=100

A limit on the number of objects to be returned

next
string
Example: next=NTM2NTA

The next token used to retrieve additional data

previous
string
Example: previous=NTQxNTA

The previous token used to retrieve additional data

Responses

Request samples

curl --request GET \
  --url 'https://api.sms.cx/shortlinks/KgTX?short_response=SOME_BOOLEAN_VALUE' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {},
  • "data": [
    ]
}

Export shortlink hits to CSV

Exports the hits details of a shortlink (phone number, device, model, operating system, browser, city, country, etc.) to a CSV file.

If there are no hits for the shortlink, an empty CSV file is returned (with first line headers).

Errors for GET /shortlinks/{shortId}/csv

HTTP code Error code Type Description
404 1400 not_found Shortlink ID not found
Authorizations:
path Parameters
shortId
required
string
Example: KgTX

Identifier of the shortlink

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/shortlinks/KgTX/csv \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/csv

Export shortlink hits to XLSX

Exports the hits details of a shortlink (phone number, device, model, operating system, browser, city, country, etc.) to a XLSX file (Excel).

If there are no hits for the shortlink, an empty XLSX file is returned (with first line headers).

Errors for GET /shortlinks/{shortId}/xlsx

HTTP code Error code Type Description
404 1400 not_found Shortlink ID not found
Authorizations:
path Parameters
shortId
required
string
Example: KgTX

Identifier of the shortlink

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/shortlinks/KgTX/xlsx \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Attachments

Receive details of visitor of attachment Webhook

POST https://{{your-endpoint}}//path-for-attachment-hit

The SMS.CX API will make a POST request to your webhook endpoint, which must return HTTP response 200. If the response is not HTTP 200, SMS.CX API will retry the callback request for the next 24 hours using an exponential backoff algorithm.

Authorizations:
None
Request Body schema: application/json
event
required
string
Enum: "attachment_hit" "attachment_hit_update"

Event for which the callback request is made

required
Array of objects (DataShortlinkHit)

Event type data, grouped in multiple objects (up to 200 in a request)

Responses

Request samples

Content type
application/json
{
  • "event": "attachment_hit",
  • "data": [
    ]
}

Get attachments list

Retrieves the list of existing attachments. The attachments are returned sorted by creation date, with the most recent attachment appearing first.

This endpoint should not return an error. If no attachments are available, an empty data object is returned.

Authorizations:

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/attachments \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{}

Get attachment hits

Retrieves the hits details (phone number, device, model, operating system, browser, city, country, etc.) of an attachment if a valid identifier was provided.

Errors for GET /attachments/{attachmentId}

HTTP code Error code Type Description
404 1420 not_found Attachment ID not found
Authorizations:
path Parameters
attachmentId
required
string
Example: KgTX

Identifier of the attachment

query Parameters
short_response
boolean
Default: false

If set to true, it will return the full info object and an empty data object

limit
integer <int32>
Default: 500
Example: limit=100

A limit on the number of objects to be returned

next
string
Example: next=NTM2NTA

The next token used to retrieve additional data

previous
string
Example: previous=NTQxNTA

The previous token used to retrieve additional data

Responses

Request samples

curl --request GET \
  --url 'https://api.sms.cx/attachments/KgTX?short_response=SOME_BOOLEAN_VALUE' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {},
  • "data": [
    ]
}

Delete attachment

Deletes an attachment and all the hits data associated, if a valid identifier was provided.

Errors for DELETE /attachments/{attachmentId}

HTTP code Error code Type Description
404 1420 not_found Attachment ID not found
Authorizations:
path Parameters
attachmentId
required
string
Example: KgTX

Identifier of the attachment

Responses

Request samples

curl --request DELETE \
  --url https://api.sms.cx/attachments/KgTX \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {
    }
}

Export attachment hits to CSV

Exports the hits details of an attachment (phone number, device, model, operating system, browser, city, country, etc.) to a CSV file.

If there are no hits for the attachment, an empty CSV file is returned (with first line headers).

Errors for GET /attachments/{attachmentId}/csv

HTTP code Error code Type Description
404 1420 not_found Attachment ID not found
Authorizations:
path Parameters
attachmentId
required
string
Example: KgTX

Identifier of the attachment

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/attachments/KgTX/csv \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/csv

Export attachment hits to XLSX

Exports the hits details of an attachment (phone number, device, model, operating system, browser, city, country, etc.) to a XLSX file (Excel).

If there are no hits for the attachment, an empty XLSX file is returned (with first line headers).

Errors for GET /attachments/{attachmentId}/xlsx

HTTP code Error code Type Description
404 1420 not_found Attachment ID not found
Authorizations:
path Parameters
attachmentId
required
string
Example: KgTX

Identifier of the attachment

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/attachments/KgTX/xlsx \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Optouts

Receive details of a new optout Webhook

POST https://{{your-endpoint}}/path-for-new-optout

The SMS.CX API will make a POST request to your webhook endpoint, which must return HTTP response 200. If the response is not HTTP 200, SMS.CX API will retry the callback request for the next 24 hours using an exponential backoff algorithm.

Authorizations:
None
Request Body schema: application/json
event
required
string
Value: "new_optout"

Event for which the callback request is made

required
Array of objects (DataNewOptout)

Event data, grouped in multiple objects (up to 200 in a request)

Responses

Request samples

Content type
application/json
{
  • "event": "new_optout",
  • "data": [
    ]
}

Get optouts list

Retrieves the list of existing contacts that opted out. The optouts are returned sorted by creation date, with the most recent optout contact appearing first.

This endpoint should not return an error. If no optouts are available, an empty data object is returned.

Authorizations:
query Parameters
limit
integer <int32>
Default: 500
Example: limit=100

A limit on the number of objects to be returned

next
string
Example: next=NTM2NTA

The next token used to retrieve additional data

previous
string
Example: previous=NTQxNTA

The previous token used to retrieve additional data

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/optouts \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {},
  • "data": [
    ]
}

Add contact to optouts list

Add contacts to the optout list. Even if you mistakenly send SMS to a contact that is in the optouts list, the SMS.CX API will detect the contact and not send any messages to unsubscribed contacts. Also, you will not be billed - sending a SMS to an unsubscribed contact will be saved as 0 cost.

Errors for POST /optouts

HTTP code Error code Type Description
400 1203 invalid_param The parameter phoneNumbers is empty or not set
400 1208 invalid_param The parameter phoneNumbers must be an array of phone numbers
400 1210 invalid_param The phone numbers provided are invalid
400 1441 invalid_param No valid phone numbers were provided or already in the optout list
Authorizations:
Request Body schema: application/json
phoneNumbers
required
Array of strings

Array of phone numbers in international E.164 format or national format. If national format is provided, for better validation you must use the parameter countryIso to provide the country code of the destination phone number.

allowInvalid
boolean
Default: false

Set value true to not throw an error if invalid numbers are detected

countryIso
string 2 characters

Two-letter country ISO of the phone number you want to validate. If an international E.164 phone number format is provided the countryIso will be ignored

Responses

Request samples

Content type
application/json
Example
{
  • "phoneNumbers": [
    ],
  • "allowInvalid": true
}

Response samples

Content type
application/json
Example
{
  • "info": {
    }
}

Delete contact from optouts list

Removes a contact from the optout list if a valid phone number identifier was provided.

Only contacts that were added with the API can be deleted.

Contacts that opted out via link cannot be deleted.

Errors for DELETE /optouts/{optoutId}

HTTP code Error code Type Description
404 1202 not_found Phone number ID not found
403 1443 access_denied Cannot delete this phone number from the optout list because it was added via optout type link. Allowed optout type to delete: admin
Authorizations:
path Parameters
optoutId
required
integer <int32>
Example: 458

Identifier of the phone number in the optout list

Responses

Request samples

curl --request DELETE \
  --url https://api.sms.cx/optouts/458 \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "info": {
    }
}

Export optouts to CSV

Exports the contacts from the optout list to a CSV file.

If the optout list is empty, an empty CSV file is returned (with first line headers).

Authorizations:

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/optouts/csv \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/csv

Export optouts to XLSX

Exports the contacts from the optout list to a XLSX file (Excel).

If the optout list is empty, an empty XLSX file is returned (with first line headers).

Authorizations:

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/optouts/xlsx \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Account

Get account balance

Retrieves the account balance, currency (eur, usd), billing (prepaid, postpaid).

Authorizations:

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/account/balance \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "balance": 8947.27,
  • "currency": "eur",
  • "billing": "prepaid"
}

Get status of all channels

Retrieves the active status of all channels (true for active, false for inactive)

Authorizations:

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/account/channels/status \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "sms": true,
  • "viber": false,
  • "whatsapp": true,
  • "multichannel": true
}

Get channels pricing

Retrieves the full pricing for the requested channel.

Errors for GET /account/pricing/{channel}/{trafficType}

HTTP code Error code Type Description
400 1521 invalid_param The channel requested is not valid
403 1523 no_coverage No coverage
Authorizations:
path Parameters
channel
required
string
Enum: "sms" "viber" "whatsapp"
trafficType
required
string
Enum: "transactional" "promotional" "2way"

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/account/pricing/%7Bchannel%7D \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
Example
{
  • "AD": {
    },
  • "AE": {
    },
  • "FR": {
    },
  • "NL": {
    },
  • "DE": {
    }
}

Get pricing for channel by country iso

Retrieves the pricing for the requested channel, for a specific country ISO.

Errors for /account/pricing/{channel}/{trafficType}/{countryIso}

HTTP code Error code Type Description
400 1521 invalid_param The channel requested is not valid
400 1522 invalid_param Invalid country iso
403 1523 no_coverage No coverage
Authorizations:
path Parameters
channel
required
string
Enum: "sms" "viber" "whatsapp"
trafficType
required
string
Enum: "transactional" "promotional" "2way"
countryIso
required
string 2 characters
Example: FR

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/account/pricing/%7Bchannel%7D/FR \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
Example
{
  • "NL": {
    }
}

Applications

Get applications list

Retrieves the list of existing applications. The applications are returned sorted by creation date, with the most recent applications appearing first.

This endpoint should not return an error. If no applications are available, an empty data object is returned.

Authorizations:

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/applications \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get scopes

Retrieves the list of available scopes for the API.

Authorizations:

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/applications/scopes \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
[
  • "sms",
  • "viber",
  • "whatsapp",
  • "multichannel",
  • "conversations",
  • "reports",
  • "groups",
  • "originators",
  • "templates",
  • "shortlinks",
  • "attachments",
  • "optouts",
  • "account",
  • "applications",
  • "numbers",
  • "lookup",
  • "otp"
]

Get application settings

Retrieves the settings of an application if a valid identifier was provided.

The method returns all scopes settings.

Errors for GET /applications/{applicationId}

HTTP code Error code Type Description
404 1500 not_found Application ID not found
Authorizations:
path Parameters
applicationId
required
string
Example: 7873310555ea4ee972518ae9559f276707c77fae

Identifier of the application id

Responses

Request samples

curl --request GET \
  --url https://api.sms.cx/applications/7873310555ea4ee972518ae9559f276707c77fae \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{}

Changelog

This section represents a list of recent and upcoming changes to our API.

1.0.2 (10.10.2022)

  • New endpoint /numbers/rent to rent phone numbers
    • GET /numbers/rent/available/{countryIso} to get list of available numbers for rent
    • GET /numbers/rent to get list of your rented numbers
    • POST /numbers/rent to rent phone number
    • GET /numbers/rent/{rentId} to get the status of a rented number
    • DELETE /numbers/rent/{rentId} to cancel a rented number
    • PATCH /numbers/rent/{rentId} to renew rent for a phone number
    • GET /numbers/rent/{rentId}/inbound to get inbound SMS from rented number
    • PATCH /numbers/rent/{rentId}/edit to edit settings for an active rent

1.0.1 (19.09.2022)

  • New endpoint /numbers/lookup to lookup phone numbers (single or bulk lookup)
    • GET /numbers/lookup/{phoneNumber} to lookup a single mobile number
    • POST /numbers/lookup for bulk lookup of phone numbers
  • New event number_lookup for webhook to receive data from number lookup
  • New endpoint /otp and /otp/{otpId} to create new OTP request, verify OTP, get OTP details and status, cancel OTP.
    • POST /otp to create new OTP request
    • GET and POST /otp/{otpId} to get details or to verify a pending OTP
    • DELETE /otp/{otpId} to cancel a pending OTP request
  • New event otp_update for webhook to receive updates about verifying the phone number

1.0.0 - initial

1.0.2 (10.10.2022)

  • New endpoint /numbers/rent to rent phone numbers
    • GET /numbers/rent/available/{countryIso} to get list of available numbers for rent
    • GET /numbers/rent to get list of your rented numbers
    • POST /numbers/rent to rent phone number
    • GET /numbers/rent/{rentId} to get the status of a rented number
    • DELETE /numbers/rent/{rentId} to cancel a rented number
    • PATCH /numbers/rent/{rentId} to renew rent for a phone number
    • GET /numbers/rent/{rentId}/inbound to get inbound SMS from rented number
    • PATCH /numbers/rent/{rentId}/edit to edit settings for an active rent

1.0.1 (19.09.2022)

  • New endpoint /numbers/lookup to lookup phone numbers (single or bulk lookup)
    • GET /numbers/lookup/{phoneNumber} to lookup a single mobile number
    • POST /numbers/lookup for bulk lookup of phone numbers
  • New event number_lookup for webhook to receive data from number lookup
  • New endpoint /otp and /otp/{otpId} to create new OTP request, verify OTP, get OTP details and status, cancel OTP.
    • POST /otp to create new OTP request
    • GET and POST /otp/{otpId} to get details or to verify a pending OTP
    • DELETE /otp/{otpId} to cancel a pending OTP request
  • New event otp_update for webhook to receive updates about verifying the phone number

1.0.0 - initial

Pronto a partire? Connettiti con i tuoi clienti in pochi minuti

Registrati Contattaci