Overview

Send and receive SMS through a single connection for timely and cost-efficient communications using the Sinch SMS API.

Authentication

Find your API token for each service plan in the Sinch Customer Dashboard. First under APIs, then REST configuration.

The token is sent in the Authorization header of each endpoint preceded by Bearer. It's required for all requests made to the Sinch SMS API.

Example

Here's an example of authentication within the header. This example is written in Node.js.

curl -X POST \
     -H "Authorization: Bearer {YOUR_API_Token}" \
     -H "Content-Type: application/json"  -d '
      {
          "from": "+19876543210",
          "to": [
              "+12345678900"
          ],
          "body": "Hi there! How are you?"
      }' \
  "https://us.sms.api.sinch.com/xms/v1/{YOUR_service_plan_id}/batches"

Base URL

The following URLs can be used by the REST API. By default, your account will be created in the US environment. If you want access to servers in other parts of the world, contact your Sinch account manager.

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 unless otherwise specified.

Requests with invalid JSON will be rejected.

Null values

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.

Phone numbers (MSISDN)

Only MSISDNs (phone numbers) in international format are accepted by the API.

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

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

Timestamps

Timestamps use 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 (which is precise, down to the millisecond).

Message limitations and capabilities

Information related to message criteria and limits can be found in the Message information section of the Resources tab.

Status Codes

A summary of status codes can be found on the HTTP status codes page.

New features

New features might result in additional request and response parameters. New request parameters will either have a default value or be considered optional. This is to retain backwards compatibility. Feel free to ignore any unexpected parameters when reading JSON in API responses and in callback handlers.