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.

List Groups

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

Groups are returned in reverse chronological order.

SecurityBearerAuth
Request
path Parameters
service_plan_id
required
string

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

Example: jd63jf88477ll123ab4567cd89012ef3
query Parameters
page
integer >= 0
Default: 0

The page number starting from 0.

Example: page=50
page_size
integer [ 0 .. 100 ]
Default: 30

Determines the size of a page.

Example: page_size=50
Responses
200

A successful response, or an Error.

Response Schema: application/json
page
integer

The requested page.

page_size
integer

The number of groups returned in this request

count
integer

The total number of groups.

Array of objects (ApiGroup)
400

Bad request

get/xms/v1/{service_plan_id}/groups
Request samples 
Response samples 
application/json
{
  • "page": 50,
  • "page_size": 50,
  • "count": 1,
  • "groups": [
    • {
      }
    ]
}
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. (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.
    • 



SecurityBearerAuth 
Request 
path Parameters
service_plan_id
required
string
Your service plan ID. You can find this on your Dashboard.


 
 Example:  jd63jf88477ll123ab4567cd89012ef3
Request Body schema: application/json
required
name
string  [ 1 .. 20 ] characters 
Name of group if set.


 
object (ApiGroupAutoUpdate) 
 
child_groups
Array of strings (MtGroupId)   [ 0 .. 10 ] items  unique 
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.


 
members
Array of strings <E.164>   [ 0 .. 10000 ] items  unique 
Initial list of phone numbers in E.164 format MSISDNs for the group.


 
Responses 
201
Created, or an Error.


Response Schema: application/json
id
string
The ID used to reference this group.


 
name
string  [ 1 .. 20 ] characters 
Name of group if set.


 
size
integer <int32> 
The number of members currently in the group.


 
created_at
string <date-time> 
Timestamp for group creation. Format: YYYY-MM-DDThh:mm:ss.SSSZ


 
modified_at
string <date-time> 
Timestamp for when the group was last updated. Format: YYYY-MM-DDThh:mm:ss.SSSZ


 
object (ApiGroupAutoUpdate) 
 
child_groups
Array of strings (MtGroupId)   [ 0 .. 10 ] items  unique 
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.


 
400
Bad request


403
Forbidden


post/xms/v1/{service_plan_id}/groups
Request samples 
application/json
{
  • "members": [
    • "member_MSISDNs",
    • "as_strings_in_array",
    • "16051234567"
    ],
  • "name": "YOUR_group_name"
}
Response samples 
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"
    }
}
Retrieve a group
This operation retrieves a specific group with the provided group ID.


SecurityBearerAuth 
Request 
path Parameters
service_plan_id
required
string
Your service plan ID. You can find this on your Dashboard.


 
 Example:  jd63jf88477ll123ab4567cd89012ef3
group_id
required
string
ID of a group that you are interested in getting.


 
Responses 
200
A successful response, or an Error.


Response Schema: application/json
id
string
The ID used to reference this group.


 
name
string  [ 1 .. 20 ] characters 
Name of group if set.


 
size
integer <int32> 
The number of members currently in the group.


 
created_at
string <date-time> 
Timestamp for group creation. Format: YYYY-MM-DDThh:mm:ss.SSSZ


 
modified_at
string <date-time> 
Timestamp for when the group was last updated. Format: YYYY-MM-DDThh:mm:ss.SSSZ


 
object (ApiGroupAutoUpdate) 
 
child_groups
Array of strings (MtGroupId)   [ 0 .. 10 ] items  unique 
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.


 
get/xms/v1/{service_plan_id}/groups/{group_id}
Request samples 
Response samples 
application/json
{
  • "id": "01FC66621VHDBN119Z8PMV1QPQ",
  • "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": {
      },
    • "remove": {
      }
    },
  • "child_groups": [
    • "01FC66621VHDBN119Z8PMV1AHY"
    ]
}
Update a group
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. 

  2. By using the auto_update object, your customer can add or remove themselves from groups. 
    3. 

  3. You can also add or remove other groups into this group with add_from_group and remove_from_group.
    4. 



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.
    • 



SecurityBearerAuth 
Request 
path Parameters
service_plan_id
required
string
Your service plan ID. You can find this on your Dashboard.


 
 Example:  jd63jf88477ll123ab4567cd89012ef3
group_id
required
string
ID of a group that you are interested in getting.


 
Request Body schema: application/json
required
add
Array 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.


 
remove
Array 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.


 
name
string  [ 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_group
string (addFromGroupId) 
Copy the members from the another group into this group.


Constraints:
Must be valid group ID


 
remove_from_group
string (removeFromGroupId) 
Remove the members in a specified group from this group.


Constraints:
Must be valid group ID


 
object (ApiGroupAutoUpdate) 
 
Responses 
200
A successful response, or an Error.


Response Schema: application/json
id
string
The ID used to reference this group.


 
name
string  [ 1 .. 20 ] characters 
Name of group if set.


 
size
integer <int32> 
The number of members currently in the group.


 
created_at
string <date-time> 
Timestamp for group creation. Format: YYYY-MM-DDThh:mm:ss.SSSZ


 
modified_at
string <date-time> 
Timestamp for when the group was last updated. Format: YYYY-MM-DDThh:mm:ss.SSSZ


 
object (ApiGroupAutoUpdate) 
 
child_groups
Array of strings (MtGroupId)   [ 0 .. 10 ] items  unique 
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.


 
400
Bad request


403
Forbidden


post/xms/v1/{service_plan_id}/groups/{group_id}
Request samples 
application/json
{
  • "add": [
    • "+14058961234",
    • "+447911123456",
    • "+55987654321"
    ],
  • "remove": [
    • "+4612345678",
    • "+15551235555"
    ]
}
Response samples 
application/json
{
  • "id": "01FC66621VHDBN119Z8PMV1QPQ",
  • "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": {
      },
    • "remove": {
      }
    },
  • "child_groups": [
    • "01FC66621VHDBN119Z8PMV1AHY"
    ]
}
Replace a group
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.


SecurityBearerAuth 
Request 
path Parameters
service_plan_id
required
string
Your service plan ID. You can find this on your Dashboard.


 
 Example:  jd63jf88477ll123ab4567cd89012ef3
group_id
required
string
ID of a group that you are interested in getting.


 
Request Body schema: application/json
name
string  [ 1 .. 20 ] characters 
Name of group if set.


 
object (ApiGroupAutoUpdate) 
 
child_groups
Array of strings (MtGroupId)   [ 0 .. 10 ] items  unique 
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.


 
members
Array of strings <E.164>   [ 0 .. 10000 ] items  unique 
Initial list of phone numbers in E.164 format MSISDNs for the group.


 
Responses 
200
A successful response, or an Error.


Response Schema: application/json
id
string
The ID used to reference this group.


 
name
string  [ 1 .. 20 ] characters 
Name of group if set.


 
size
integer <int32> 
The number of members currently in the group.


 
created_at
string <date-time> 
Timestamp for group creation. Format: YYYY-MM-DDThh:mm:ss.SSSZ


 
modified_at
string <date-time> 
Timestamp for when the group was last updated. Format: YYYY-MM-DDThh:mm:ss.SSSZ


 
object (ApiGroupAutoUpdate) 
 
child_groups
Array of strings (MtGroupId)   [ 0 .. 10 ] items  unique 
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.


 
400
Bad request


403
Forbidden


put/xms/v1/{service_plan_id}/groups/{group_id}
Request samples 
application/json
{
  • "members": [
    • "123456789",
    • "987654321"
    ],
  • "name": "New Name of the Group"
}
Response samples 
application/json
{
  • "id": "01FC66621VHDBN119Z8PMV1QPQ",
  • "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": {
      },
    • "remove": {
      }
    },
  • "child_groups": [
    • "01FC66621VHDBN119Z8PMV1AHY"
    ]
}
Delete a group
This operation deletes the group with the provided group ID.


SecurityBearerAuth 
Request 
path Parameters
service_plan_id
required
string
Your service plan ID. You can find this on your Dashboard.


 
 Example:  jd63jf88477ll123ab4567cd89012ef3
group_id
required
string
ID of a group that you are interested in getting.


 
Responses 
200
A successful response , or an Error.


delete/xms/v1/{service_plan_id}/groups/{group_id}
Request samples 
Get phone numbers for a group
This operation retrieves the members of the group with the provided group ID.


SecurityBearerAuth 
Request 
path Parameters
service_plan_id
required
string
Your service plan ID. You can find this on your Dashboard.


 
 Example:  jd63jf88477ll123ab4567cd89012ef3
group_id
required
string
ID of a group that you are interested in getting.


 
Responses 
200
A successful response, or an Error.


Response Schema: application/json
 Array 
string <E.164>  (msisdn) 
A phone number in E.164 format.


 
404
Not found. The group ID is unknown to the system.


get/xms/v1/{service_plan_id}/groups/{group_id}/members
Request samples 
Response samples 
application/json
[
  • "+453234457784"
]
SecurityPrivacyLegal & ComplianceCookie Statement
© 2025 Sinch. All rights reserved.