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.

Notes

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.

Making a request

Below are code samples that highlight how to make this API request in multiple languages. Click an appropriate tab to view your preferred language:

application/json

{"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

any (groupObject)

Sample response

After making this API call, you should receive a response that is similar to the example given below:

null

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

any (createGroupResponse)

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.

Making a request

Below are code samples that highlight how to make this API request in multiple languages. Click an appropriate tab to view your preferred language:

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

Sample response

After making this API call, you should receive a response that is similar to the example given below:

{"page": 50,
"page_size": 50,
"count": 1,
"groups": [{"name": "My First Group",
"members": ["+14155553421",
"+13435552671",
"+14325552677"
],
"auto_update": {"to": "+453234457784",
"add": {"first_word": "join",
"second_word": "add"
},
"remove": {"first_word": "leave",
"second_word": "remove"
}
}
}
]
}

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

any (GroupList)

Retrieve a group

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

Making a request

Below are code samples that highlight how to make this API request in multiple languages. Click an appropriate tab to view your preferred language:

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

Sample response

After making this API call, you should receive a response that is similar to the example given below:

null

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

any (createGroupResponse)

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.

Making a request

Below are code samples that highlight how to make this API request in multiple languages. Click an appropriate tab to view your preferred language:

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

Sample response

After making this API call, you should receive a response that is similar to the example given below:

["+453234457784"
]

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

any (recipients)

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.

Making a request

Below are code samples that highlight how to make this API request in multiple languages. Click an appropriate tab to view your preferred language:

application/json

{"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

any (UpdateGroup)

Sample response

After making this API call, you should receive a response that is similar to the example given below:

null

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

any (createGroupResponse)

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.

Making a request

Below are code samples that highlight how to make this API request in multiple languages. Click an appropriate tab to view your preferred language:

application/json

{"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

any (ReplacedGroup)

Sample response

After making this API call, you should receive a response that is similar to the example given below:

null

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

any (createGroupResponse)

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. Click an appropriate tab to view your preferred language:

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

Sample response

Response 200 if successful.