# 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](../api-reference/) 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](../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: For the full schema of the response that corresponds to this API call, see the [corresponding entry](/docs/sms/api-reference/sms/groups/creategroup) in the API reference. Alternatively, expand the schema below: details summary See the schema For the full schema of the response that corresponds to this API call, see the [corresponding entry](/docs/sms/api-reference/sms/groups/creategroup) 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: For the full schema of this API call, see the [corresponding entry](/docs/sms/api-reference/sms/groups/listgroups) in the API reference. For the full schema of the response that corresponds to this API call, see the [corresponding entry](/docs/sms/api-reference/sms/groups/listgroups) 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: For the full schema of this API call, see the [corresponding entry](/docs/sms/api-reference/sms/groups/retrievegroup) in the API reference. For the full schema of the response that corresponds to this API call, see the [corresponding entry](/docs/sms/api-reference/sms/groups/retrievegroup) 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: For the full schema of this API call, see the [corresponding entry](/docs/sms/api-reference/sms/groups/getmembers) in the API reference. For the full schema of the response that corresponds to this API call, see the [corresponding entry](/docs/sms/api-reference/sms/groups/getmembers) 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: For the full schema of this API call, see the [corresponding entry](/docs/sms/api-reference/sms/groups/updategroup) in the API reference. Alternatively, expand the schema below: details summary See the schema For the full schema of the response that corresponds to this API call, see the [corresponding entry](/docs/sms/api-reference/sms/groups/updategroup) 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: For the full schema of the response that corresponds to this API call, see the [corresponding entry](/docs/sms/api-reference/sms/groups/replacegroup) in the API reference. Alternatively, expand the schema below: details summary See the schema For the full schema of the response that corresponds to this API call, see the [corresponding entry](/docs/sms/api-reference/sms/groups/replacegroup) 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: For the full schema of this API call, see the [corresponding entry](/docs/sms/api-reference/sms/groups/deletegroup) in the API reference. Response 200 if successful.