Download OpenAPI specification:Download

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.

Request
Security:
BearerAuth
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 (groupObject)
get/xms/v1/{service_plan_id}/groups
Request samples
import fetch from 'node-fetch';

async function run() {
  const servicePlanId = 'YOUR_service_plan_id_PARAMETER';
  const region = 'us';
  const resp = await fetch(
    `https://${region}.sms.api.sinch.com/xms/v1/${servicePlanId}/groups`,
    {
      method: 'GET',
      headers: {
        Authorization: 'Bearer <YOUR_TOKEN_HERE>'
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
Response samples
application/json
{
  • "page": 50,
  • "page_size": 50,
  • "count": 0,
  • "groups": [
    • {
      }
    ]
}

Create a group

A group is a set of phone numbers (MSISDNs) that can be used as a target in the send_batch_msg operation. An MSISDN can only occur once in a group and any attempts to add a duplicate would be ignored but not rejected.

Request
Security:
BearerAuth
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
name
string <= 20 characters

Name of the group

members
Array of strings <e.164> (msisdn) <= 10000 items

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

child_groups
Array of strings <= 10 items

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

Constraints: Elements must be group IDs.

object
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

child_groups
Array of objects (MtGroupId) [ 0 .. 10 ] items unique

Phone numbers (MSISDNs) of child group will be included in this group. If present, this group will be auto populated. Constraints: Elements must be group IDs.

object (GroupAutoUpdate)
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": "01FC66621VHDBN119Z8PMV1QPU",
  • "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": "string",
    • "remove": "string"
    }
}

Retrieve a group

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

Request
Security:
BearerAuth
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

child_groups
Array of objects (MtGroupId) [ 0 .. 10 ] items unique

Phone numbers (MSISDNs) of child group will be included in this group. If present, this group will be auto populated. Constraints: Elements must be group IDs.

object (GroupAutoUpdate)
get/xms/v1/{service_plan_id}/groups/{group_id}
Request samples
import fetch from 'node-fetch';

async function run() {
  const servicePlanId = 'YOUR_service_plan_id_PARAMETER';
  const groupId = 'YOUR_group_id_PARAMETER';
  const region = 'us';
  const resp = await fetch(
    `https://${region}.sms.api.sinch.com/xms/v1/${servicePlanId}/groups/${groupId}`,
    {
      method: 'GET',
      headers: {
        Authorization: 'Bearer <YOUR_TOKEN_HERE>'
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
Response samples
application/json
{
  • "id": "01FC66621VHDBN119Z8PMV1QPU",
  • "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": "string",
    • "remove": "string"
    }
}

Update a group

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

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 in both lists, then it will not be apart of the resulting group.

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

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

Request
Security:
BearerAuth
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 <= 20 characters

Name of group.

object
add_from_group
string

Copy the members from the given group into this group.

Constraints: Must be valid group ID

remove_from_group
string

Remove members in the given group from group.

Constraints: Must be valid group ID

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

child_groups
Array of objects (MtGroupId) [ 0 .. 10 ] items unique

Phone numbers (MSISDNs) of child group will be included in this group. If present, this group will be auto populated. Constraints: Elements must be group IDs.

object (GroupAutoUpdate)
post/xms/v1/{service_plan_id}/groups/{group_id}
Request samples
application/json
{
  • "name": "Homeowners",
  • "auto_update": {
    • "to": "443456789012",
    • "add": {
      },
    • "remove": {
      }
    }
}
Response samples
application/json
{
  • "id": "01FC66621VHDBN119Z8PMV1QPU",
  • "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": "string",
    • "remove": "string"
    }
}

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.

Request
Security:
BearerAuth
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
members
required
Array of strings <e.164> (msisdn) <= 10000 items

The initial members of the group.

Constraints: Elements must be phone numbers in E.164 format MSISDNs.

name
string <= 20 items

Name of 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

child_groups
Array of objects (MtGroupId) [ 0 .. 10 ] items unique

Phone numbers (MSISDNs) of child group will be included in this group. If present, this group will be auto populated. Constraints: Elements must be group IDs.

object (GroupAutoUpdate)
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": "01FC66621VHDBN119Z8PMV1QPU",
  • "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": "string",
    • "remove": "string"
    }
}

Delete a group

This operation deletes the group with the provided group ID.

Request
Security:
BearerAuth
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
import fetch from 'node-fetch';

async function run() {
  const servicePlanId = 'YOUR_service_plan_id_PARAMETER';
  const groupId = 'YOUR_group_id_PARAMETER';
  const region = 'us';
  const resp = await fetch(
    `https://${region}.sms.api.sinch.com/xms/v1/${servicePlanId}/groups/${groupId}`,
    {
      method: 'DELETE',
      headers: {
        Authorization: 'Bearer <YOUR_TOKEN_HERE>'
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();

Get phone numbers for a group

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

Request
Security:
BearerAuth
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.

get/xms/v1/{service_plan_id}/groups/{group_id}/members
Request samples
import fetch from 'node-fetch';

async function run() {
  const servicePlanId = 'YOUR_service_plan_id_PARAMETER';
  const groupId = 'YOUR_group_id_PARAMETER';
  const region = 'us';
  const resp = await fetch(
    `https://${region}.sms.api.sinch.com/xms/v1/${servicePlanId}/groups/${groupId}/members`,
    {
      method: 'GET',
      headers: {
        Authorization: 'Bearer <YOUR_TOKEN_HERE>'
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
Response samples
application/json
[
  • "+453234457784"
]
SecurityPrivacyLegal & ComplianceCookie Statement
© 2022 Sinch. All rights reserved.