API Overview

Sinch SMS API is the one of the easiest APIs we offer and enables you to add fast and reliable global SMS to your applications. It allows for sending single messages, scheduled batch sending, message templates and more.

Download the OpenAPI specification here.

Contact Sinch support here: Support@sinch.com

Send your first SMS message

You send SMS messages using the Batches endpoint.

Get started in minutes using our REST API:

Authentication

You will be provided with an authentication token for each service plan.

The token is sent in the Authorization header preceded by Bearer. It's required for all requests made to the REST API.

Base URL

The following URLs can be used by the REST API. Sinch has servers in the US and EU. By default, your account will be created in the US environment. If you want access to the European environment, contact your Sinch account manager.

Server URL
General API https://us.sms.api.sinch.com
Geographical APIs If you want to set one up, contact your account manager
US Production https://us.sms.api.sinch.com
EU Production https://eu.sms.api.sinch.com
Australia Production https://au.sms.api.sinch.com
Great Britain Production https://gb.sms.api.sinch.com
Canada Production https://ca.sms.api.sinch.com

Rate Limits

Each service plan comes with a rate limit which sets the maximum number of messages that can be sent per second. The rate limit's calculated from all messages sent via the API. A batch with 10 recipients will count as 10 messages for rate limiting purposes.

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

SMS REST formats and conventions

Let's take a brief look at some of the formats used in the REST API.

JSON

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

Requests with invalid JSON will be rejected.

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

New features might result in additional request and response parameters. New request parameters will either have a default value or be considered optional to retain backwards compatibility. It's highly recommended to ignore any unexpected parameters when reading JSON in API responses and in callback handlers.

Phone numbers (MSISDN)

Only MSISDNs in international format are accepted by the API.

MSISDNs can be sent in with or without a leading + (+123456789 or 123456789 are both valid) or with a leading 00. Any space, dash or bracket will also be ignored by the API.

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

Timestamps

Timestamps are used for expressing a moment in time. They're represented using the ISO-8601 standard. Examples of those are the fields send_at and expire_at in the Send message operation.

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

All timestamps returned by the API will be represented in UTC time precise to the milisecond.

HTTP Status Codes

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

HTTP Statuses

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

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

HTTP Errors

Responses with status 400 Bad Request and 403 Forbidden will present a JSON object in the body explaining the error. It has the following structure:

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

Error codes

The following error codes can be returned as values for the code field:

HTTP Status Code Description
400 syntax_invalid_json The JSON in the request is invalid or doesn't conform to the API specification.
400 syntax_invalid_parameter_format The format of a field value is invalid. For example if a MSISDN is not correctly formatted.
400 syntax_constraint_violation The request body doesn't fulfill all of the constraints set by the API. For example if a required field is missing.
403 unknown_group A referenced group ID is unknown. This could happen if the ID is invalid or if the group has been deleted.
403 unknown_campaign The campaign ID doesn't match the specified originator.
403 missing_callback_url Callback has been requested but no URL is provided.
403 llegal_number_type Illegal phone number type of MSISDN for a chosen region was used.
403 blocked_account Your account has been blocked

Message Body

When specifying the message body in the request, the characters used as well as the length of the message affect how many actual SMS messages are sent out. When using parameterization, the length of each message may also vary depending on the recipient-specific data.

Supported Characters

Individual characters used in the message determine the type of encoding that will ultimately be used to send the SMS message. The API automatically detects the encoding required from the characters used, which allows us to support the delivery of SMS in any language.

Basic Character Set

You can send up to 160 characters in a single SMS message if all characters in your message are part of the GSM 7-bit character set:

GSM 7 bit default alphabet and extension table

3GPP TS 23.038 / GSM 03.38

x0 x1 x2 x3 x4 x5 x6 x7 x8 x9 xA xB xC xD xE xF
0x @ £ $ ¥ è é ù ì ò Ç LF Ø ø CR Å å
1x Δ _ Φ Γ Λ Ω Π Ψ Σ Θ Ξ ESC Æ æ ß É
2x SP ! # ¤ % & ( ) * + , . /
3x 0 1 2 3 4 5 6 7 8 9 : ; < = > ?
4x ¡ A B C D E F G H I J K L M N O
5x P Q R S T U V W X Y Z Ä Ö Ñ Ü §
6x ¿ a b c d e f g h i j k l m n o
7x p q r s t u v w x y z ä ö ñ ü à
1B 0x FF
1B 1x ^
1B 2x { } \
1B 3x [ ~ ]
1B 4x
1B 5x
1B 6x
1B 7x

LF is the Line Feed character - for JSON format, provide it as \n SP is the Space character

Extended Character Set

The following characters are also available, but they're counted as two characters in the SMS message rather than one:

| , ^ , &euro; , { , } , [ , ] , ~ , \

Other Characters

If other characters are required for different languages, 16-bit Unicode (UCS-2) encoding will be used. When using UCS-2 encoding, each character will take 2 bytes, which means up to 70 characters can be sent per UCS-2 encoded SMS message. Here is more information on this topic, including billing implications.

Long Messages

The message body in a request can contain up to 2000 characters. Longer messages will be split and sent as multiple distinct SMS messages. In most cases, those messages will be re-assembled on the handset and displayed to the end-user as a single long message. You can use the tables below to determine the actual number of SMS messages your message will use depending on its length and encoding.

Using only 7-bit Characters

Message Length Number of SMS Parts
1–160 1
161–306 2
307–459 3
460–612 4
613–765 5
766–918 6
919–1061 7
1062–1214 8
1215–1367 9
1368–1520 10
1521–1673 11
1674–1826 12
1827–1979 13
1980–2000 14

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

Using Unicode Characters

Message Length Number of SMS Parts
1–70 1
71–134 2
134–201 3
202–268 4
269–335 5
336–402 6
403–469 7
470–538 8
539–605 9
606–672 10
673–739 11
740–796 12
797–853 13
854–924 14
925–991 15
992–1058 16
1059–1115 17
1116–1182 18
1183–1249 19
1250–1316 20
1317–1383 21
1384–1450 22
1451–1517 23
1518–1584 24
1585–1651 25
1652–1781 26
1782–1848 27
1849–1915 28
1916–1982 29
1983–2000 30

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

Parameterization

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

This is done by defining a parameter key and placing it in the message body. For each parameter key, a recipient and parameter value must be provided. The position of a parameter in a message is defined by specifying placeholders in the format ${parameter_key} in the message body, where parameter_key is the name of the parameter to replace with its corresponding value.

For example, the message body Hi ${name}! How are you? contains the parameter name and will be replaced according to the rules specified in the parameters field in the Send message operation.

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

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

Parameter keys are case sensitive.