Overview

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

Message type support

The Sinch SMS REST API allows you to both send and receive SMS messages. If you are in the US region, you are also able to send and receive MMS messages. To enable MMS functionality, contact your account manager.

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. Customer Data will be stored in the corresponding locations listed below.

Please note that:

• Sinch uses systems, customer service teams, development teams and service providers located within production server locations and overseas, whom may have access to and process Customer Data.
• Personal Data will be processed in accordance with the Data Protection Agreement and include the use of sub-processors for the services as described on the Sub-Processors page .

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.