Skip to content
SMS/REST API reference/
/
Get phone numbers for a g...

API Overview | Sinch (v1)

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

Download OpenAPI description
sms.json
sms.yaml
Overview
URL

https://www.sinch.com

Support

Support@sinch.com

License

MIT

Terms of Service

Languages
Servers
Global API

https://{region}.sms.api.sinch.com/

Delivery reports

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

OperationsWebhooks

Groups

A group is a set of phone numbers (or MSISDNs) that can be used as a target when sending an SMS. An phone number (MSISDN) can only occur once in a group and any attempts to add a duplicate are ignored but not rejected.

Operations

Retrieve a group

Request

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

Security
BearerAuth
Path
service_plan_idstringrequired

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll123ab4567cd89012ef3
group_idstringrequired

ID of a group that you are interested in getting.

curl -i -X GET \
  'https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/groups/{group_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

A successful response, or an Error.

Bodyapplication/json
idstringread-only

The ID used to reference this group.

Example: "01FC66621VHDBN119Z8PMV1QPQ"
namestring[ 1 .. 20 ] characters

Name of group if set.

Example: "My new customers"
sizeinteger(int32)read-only

The number of members currently in the group.

Example: 2
created_atstring(date-time)read-only

Timestamp for group creation. Format: YYYY-MM-DDThh:mm:ss.SSSZ

modified_atstring(date-time)read-only

Timestamp for when the group was last updated. Format: YYYY-MM-DDThh:mm:ss.SSSZ

child_groupsArray of strings(MtGroupId)[ 0 .. 10 ] itemsunique

Phone numbers MSIDNs of child group will be included in this group. If present then this group will be auto populated.

Constraints: Elements must be group IDs.

Example: ["01FC66621VHDBN119Z8PMV1AHY"]
auto_updateobject(ApiGroupAutoUpdate)
Response
application/json
{
  "id": "01FC66621VHDBN119Z8PMV1QPQ",
  "name": "My new customers",
  "size": 2,
  "created_at": "2019-08-24T14:15:22Z",
  "modified_at": "2019-08-24T14:15:22Z",
  "child_groups": [
    "01FC66621VHDBN119Z8PMV1AHY"
  ],
  "auto_update": {
    "to": "+15551231234",
    "add": { … },
    "remove": { … }
  }
}

Replace a group

Request

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

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

Security
BearerAuth
Path
service_plan_idstringrequired

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll123ab4567cd89012ef3
group_idstringrequired

ID of a group that you are interested in getting.

Bodyapplication/jsonrequired
namestring[ 1 .. 20 ] characters

Name of group if set.

Example: "My new customers"
child_groupsArray of strings(MtGroupId)[ 0 .. 10 ] itemsunique

Phone numbers MSIDNs of child group will be included in this group. If present then this group will be auto populated.

Constraints: Elements must be group IDs.

Example: ["01FC66621VHDBN119Z8PMV1AHY"]
auto_updateobject(ApiGroupAutoUpdate)
membersArray of strings(E.164)[ 0 .. 10000 ] itemsunique

Initial list of phone numbers in E.164 format MSISDNs for the group.

Example: ["+15551231234","+15551256344"]
curl -i -X PUT \
  'https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/groups/{group_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "members": [
      "123456789",
      "987654321"
    ],
    "name": "New Name of the Group"
  }'

Responses

A successful response, or an Error.

Bodyapplication/json
idstringread-only

The ID used to reference this group.

Example: "01FC66621VHDBN119Z8PMV1QPQ"
namestring[ 1 .. 20 ] characters

Name of group if set.

Example: "My new customers"
sizeinteger(int32)read-only

The number of members currently in the group.

Example: 2
created_atstring(date-time)read-only

Timestamp for group creation. Format: YYYY-MM-DDThh:mm:ss.SSSZ

modified_atstring(date-time)read-only

Timestamp for when the group was last updated. Format: YYYY-MM-DDThh:mm:ss.SSSZ

child_groupsArray of strings(MtGroupId)[ 0 .. 10 ] itemsunique

Phone numbers MSIDNs of child group will be included in this group. If present then this group will be auto populated.

Constraints: Elements must be group IDs.

Example: ["01FC66621VHDBN119Z8PMV1AHY"]
auto_updateobject(ApiGroupAutoUpdate)
Response
application/json
{
  "id": "01FC66621VHDBN119Z8PMV1QPQ",
  "name": "My new customers",
  "size": 2,
  "created_at": "2019-08-24T14:15:22Z",
  "modified_at": "2019-08-24T14:15:22Z",
  "child_groups": [
    "01FC66621VHDBN119Z8PMV1AHY"
  ],
  "auto_update": {
    "to": "+15551231234",
    "add": { … },
    "remove": { … }
  }
}

Update a group

Request

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

This method encompasses a few ways to update a group:

  1. By using add and remove arrays containing phone numbers, you control the group movements. Any list of valid numbers in E.164 format can be added.
  2. By using the auto_update object, your customer can add or remove themselves from groups.
  3. You can also add or remove other groups into this group with add_from_group and remove_from_group.

Other group update info

  • The request will not be rejected for duplicate adds or unknown removes.
  • The additions will be done before the deletions. If an phone number is on both lists, it will not be apart of the resulting group.
  • Updating a group targeted by a batch message scheduled in the future is allowed. Changes will be reflected when the batch is sent.
Security
BearerAuth
Path
service_plan_idstringrequired

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll123ab4567cd89012ef3
group_idstringrequired

ID of a group that you are interested in getting.

Bodyapplication/jsonrequired
addArray of strings(E.164)[ 0 .. 10000 ] items

Add a list of phone numbers (MSISDNs) to this group. The phone numbers are a strings within an array and must be in E.164 format.

removeArray of strings(E.164)[ 0 .. 10000 ] items

Remove a list of phone numbers (MSISDNs) to this group.The phone numbers are a strings within an array and must be in E.164 format.

namestring[ 1 .. 20 ] characters

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

add_from_groupstring(addFromGroupId)

Copy the members from the another group into this group.

Constraints: Must be valid group ID

remove_from_groupstring(removeFromGroupId)

Remove the members in a specified group from this group.

Constraints: Must be valid group ID

auto_updateobject(ApiGroupAutoUpdate)
curl -i -X POST \
  'https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/groups/{group_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "add": [
      "+14058961234",
      "+447911123456",
      "+55987654321"
    ],
    "remove": [
      "+4612345678",
      "+15551235555"
    ]
  }'

Responses

A successful response, or an Error.

Bodyapplication/json
idstringread-only

The ID used to reference this group.

Example: "01FC66621VHDBN119Z8PMV1QPQ"
namestring[ 1 .. 20 ] characters

Name of group if set.

Example: "My new customers"
sizeinteger(int32)read-only

The number of members currently in the group.

Example: 2
created_atstring(date-time)read-only

Timestamp for group creation. Format: YYYY-MM-DDThh:mm:ss.SSSZ

modified_atstring(date-time)read-only

Timestamp for when the group was last updated. Format: YYYY-MM-DDThh:mm:ss.SSSZ

child_groupsArray of strings(MtGroupId)[ 0 .. 10 ] itemsunique

Phone numbers MSIDNs of child group will be included in this group. If present then this group will be auto populated.

Constraints: Elements must be group IDs.

Example: ["01FC66621VHDBN119Z8PMV1AHY"]
auto_updateobject(ApiGroupAutoUpdate)
Response
application/json
{
  "id": "01FC66621VHDBN119Z8PMV1QPQ",
  "name": "My new customers",
  "size": 2,
  "created_at": "2019-08-24T14:15:22Z",
  "modified_at": "2019-08-24T14:15:22Z",
  "child_groups": [
    "01FC66621VHDBN119Z8PMV1AHY"
  ],
  "auto_update": {
    "to": "+15551231234",
    "add": { … },
    "remove": { … }
  }
}

Delete a group

Request

This operation deletes the group with the provided group ID.

Security
BearerAuth
Path
service_plan_idstringrequired

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll123ab4567cd89012ef3
group_idstringrequired

ID of a group that you are interested in getting.

curl -i -X DELETE \
  'https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/groups/{group_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

A successful response , or an Error.

List Groups

Request

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

Groups are returned in reverse chronological order.

Security
BearerAuth
Path
service_plan_idstringrequired

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll123ab4567cd89012ef3
Query
pageinteger>= 0

The page number starting from 0.

Default 0
Example: page=4
page_sizeinteger[ 0 .. 100 ]

Determines the size of a page.

Default 30
Example: page_size=50
curl -i -X GET \
  'https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/groups?page=4&page_size=50' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

A successful response, or an Error.

Bodyapplication/json
countinteger

The total number of groups.

Example: 2
pageinteger(int32)

The requested page.

Example: 0
groupsArray of objects(ApiGroup)
page_sizeinteger(int32)

The number of groups returned in this request

Example: 2
Response
application/json
{
  "page": 50,
  "page_size": 50,
  "count": 1,
  "groups": [
    { … }
  ]
}

Create a group

Request

This endpoint allows you to create a group of recipients. A new group must be created with a group name. This is represented by the name field which can be up to 20 charecters. In addition, there are a number of optional fields:

  • members field enables groups to be created with an initial list of contacts
  • auto_update allows customers to auto subscribe to a new group. This contains three fields. The to field contains the group creator's number. (This number must be provisioned by contacting your account manager.) The add and remove fields are objects containing the keywords that customers need to text to join or leave a group.
Security
BearerAuth
Path
service_plan_idstringrequired

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll123ab4567cd89012ef3
Bodyapplication/jsonrequired
namestring[ 1 .. 20 ] characters

Name of group if set.

Example: "My new customers"
child_groupsArray of strings(MtGroupId)[ 0 .. 10 ] itemsunique

Phone numbers MSIDNs of child group will be included in this group. If present then this group will be auto populated.

Constraints: Elements must be group IDs.

Example: ["01FC66621VHDBN119Z8PMV1AHY"]
auto_updateobject(ApiGroupAutoUpdate)
membersArray of strings(E.164)[ 0 .. 10000 ] itemsunique

Initial list of phone numbers in E.164 format MSISDNs for the group.

Example: ["+15551231234","+15551256344"]
curl -i -X POST \
  https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/groups \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "members": [
      "member_MSISDNs",
      "as_strings_in_array",
      "16051234567"
    ],
    "name": "YOUR_group_name"
  }'

Responses

Created, or an Error.

Bodyapplication/json
idstringread-only

The ID used to reference this group.

Example: "01FC66621VHDBN119Z8PMV1QPQ"
namestring[ 1 .. 20 ] characters

Name of group if set.

Example: "My new customers"
sizeinteger(int32)read-only

The number of members currently in the group.

Example: 2
created_atstring(date-time)read-only

Timestamp for group creation. Format: YYYY-MM-DDThh:mm:ss.SSSZ

modified_atstring(date-time)read-only

Timestamp for when the group was last updated. Format: YYYY-MM-DDThh:mm:ss.SSSZ

child_groupsArray of strings(MtGroupId)[ 0 .. 10 ] itemsunique

Phone numbers MSIDNs of child group will be included in this group. If present then this group will be auto populated.

Constraints: Elements must be group IDs.

Example: ["01FC66621VHDBN119Z8PMV1AHY"]
auto_updateobject(ApiGroupAutoUpdate)
Response
application/json
{
  "id": "01FC66621XXXXX119Z8PMV1QPU",
  "name": "My new customers",
  "size": 2,
  "created_at": "2019-08-24T14:15:22Z",
  "modified_at": "2019-08-24T14:15:22Z",
  "auto_update": {
    "to": 15551231234,
    "add": "join",
    "remove": "leave"
  }
}

Get phone numbers for a group

Request

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

Security
BearerAuth
Path
service_plan_idstringrequired

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll123ab4567cd89012ef3
group_idstringrequired

ID of a group that you are interested in getting.

curl -i -X GET \
  'https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/groups/{group_id}/members' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

A successful response, or an Error.

Bodyapplication/jsonArray [
string(E.164)(msisdn)

A phone number in E.164 format.

]
Response
application/json
[
  "+453234457784"
]

Batches

Batches are sets of SMS messages. You can send a single message or many. Batches are queued and sent at the rate limit in first-in-first-out order.

Operations

Inbounds

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

OperationsWebhooks

Webhooks

Webhooks