Skip to content
SMS/
/
Managing groups of recipi...
Last updated

Managing groups of recipients

This article details commonly used API operations. Each section corresponds to an operation and includes a brief overview, a sample request and response payload, and schema information pulled directly from the API reference. Additionally, each section will include links to the corresponding API reference entry and any tutorials (if available).

Note:

For information on how complete the configuration steps required for this API, along with language-specific guides that illustrate the API's functionality with pre-populated examples, see the Getting started guides that correspond to this API.

A group is a set of phone numbers (or MSISDNs) that can be used as a target when sending an SMS. This can be useful when creating targetted SMS marketing campaigns. For example, a pet store could market products to its customers in a "Pet Store" group. A phone number (MSISDN) can only occur once in a group and any attempts to add a duplicate are ignored but not rejected.

Create a group

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. The add and remove fields are objects containing the keywords that customers need to text to join or leave a group.
Note:
  • child_groups will be phased out in future versions of the SMS API
  • To use auto_update, you must have a provisioned number in the to field. You can provision your Sinch account number by contacting your account manager.

Create group request and response

Below are code samples that highlight how to make this API request in multiple languages. A sample response is also provided. Select your preferred coding language from the language drop-down list:

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"
  }'

For the full schema of the response that corresponds to this API call, see the corresponding entry in the API reference. Alternatively, expand the schema below:

See the schema
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)
membersArray of strings(E.164)[ 0 .. 10000 ] itemsunique
Example: ["+15551231234","+15551256344"]

For the full schema of the response that corresponds to this API call, see the corresponding entry in the API reference.

List Groups

The list operation lists all groups that you have created. Results are returned in reverse chronological order meaning users will see the most recently created groups near the top of the list. If there is a high volume of groups, results can be paginated. Pagination is flexible, with the page and page_size query parameters enabling users to set the number of pages and the number of results per page.

List groups request and response

Below are code samples that highlight how to make this API request in multiple languages. A sample response is also provided. Select your preferred coding language from the language drop-down list:

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>'

For the full schema of this API call, see the corresponding entry in the API reference.

For the full schema of the response that corresponds to this API call, see the corresponding entry in the API reference.

Retrieve a group

This operation retrieves a specific group with the group_id provided in the path parameters.

Retrieve a group request and response

Below are code samples that highlight how to make this API request in multiple languages. A sample response is also provided. Select your preferred coding language from the language drop-down list:

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

For the full schema of this API call, see the corresponding entry in the API reference.

For the full schema of the response that corresponds to this API call, see the corresponding entry in the API reference.

Get phone numbers for a group

This operation retrieves the members of the group with the group_id provided in the path parameters. This enables users to review the recipients in a group, for better group management and campaign targetting.

Get phone numbers request and response

Below are code samples that highlight how to make this API request in multiple languages. A sample response is also provided. Select your preferred coding language from the language drop-down list:

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

For the full schema of this API call, see the corresponding entry in the API reference.

For the full schema of the response that corresponds to this API call, see the corresponding entry in the API reference.

Update a group

This endpoint enables users to add and remove recipients in a group. This is useful for modifying the recipient list for an SMS campaign. In addition, the update operation gives customers the ability to auto-subscribe through the auto_update parameter. This contains three fields. The to field contains the group creator's number. The add and remove fields are objects containing the keywords that customers need to text to join or leave a group.

Note:

To use auto_update, you must have a provisioned number in the to field. You can provision your Sinch account number by contacting your account manager.

Update a group request and resopnse

Below are code samples that highlight how to make this API request in multiple languages. A sample response is also provided. Select your preferred coding language from the language drop-down list:

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"
    ]
  }'

For the full schema of this API call, see the corresponding entry in the API reference. Alternatively, expand the schema below:

See the schema
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)

One time copy of all members from the group referenced by the group ID into this group.

Example: "01FC66621VHDBN119Z8PMV1QPU"
remove_from_groupstring(removeFromGroupId)

Remove all members from this group that are currently in the group referenced by the group ID.

Example: "01FC66621VHDBN119Z8PMV1AHY"
auto_updateobject(ApiGroupAutoUpdate)

For the full schema of the response that corresponds to this API call, see the corresponding entry in the API reference.

Replace a group

This operation allows users to replace a group. The replace operation replaces all parameters, including members, of an existing group with new values. This is useful for cases where simply modifying an existing group isn't enough.

Note:

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

Replace a group request and response

Below are code samples that highlight how to make this API request in multiple languages. A sample response is also provided. Select your preferred coding language from the language drop-down list:

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"
  }'

For the full schema of the response that corresponds to this API call, see the corresponding entry in the API reference. Alternatively, expand the schema below:

See the schema
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)
membersArray of strings(E.164)[ 0 .. 10000 ] itemsunique
Example: ["+15551231234","+15551256344"]

For the full schema of the response that corresponds to this API call, see the corresponding entry in the API reference.

Delete a group

This endpoint allows users to delete groups by group_id provided in the path parameters. This can be useful if a group no longer serves your organisational requirements.

Making a request

Below are code samples that highlight how to make this API request in multiple languages. A sample response is also provided. Select your preferred coding language from the language drop-down list:

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

For the full schema of this API call, see the corresponding entry in the API reference.

Response 200 if successful.

Previous page
Next page