---
title: "Create a group"
method: POST
path: "/xms/v1/{service_plan_id}/groups"
tags: ["Groups"]
---

# Create a group

`POST /xms/v1/{service_plan_id}/groups`

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.

## Request body

- ApiGroupRequest
  - `id` string — The ID used to reference this group.
  - `name` string — Name of group if set.
  - `size` integer — 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` MtGroupId[] — Phone numbers [MSIDNs](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628) of child group will be included in this group. If present then this group will be auto populated. Constraints: Elements must be group IDs.
  - `auto_update` ApiGroupAutoUpdate
    - `to` string, E.164, required — Short code or long number addressed in [MO](https://community.sinch.com/t5/Glossary/MO-Mobile-Originated/ta-p/7618). Constraints: Must be valid phone number or short code which has been **provisioned by your account manager**.
    - `add` AddKeyword — Keyword to be sent in MO to add MSISDN to a group
      - `first_word` string, required — Opt-in keyword like "JOIN" if _auto_update.to_ is dedicated long/short number or unique brand keyword like "Sinch" if it is a shared short code.
      - `second_word` string — Opt-in keyword like "JOIN" if _auto_update.to_ is shared short code.
    - `remove` RemoveKeyword — Keyword to be sent in MO to remove MSISDN to a group
      - `first_word` string, required — Opt-out keyword like "LEAVE" if _auto_update.to_ is dedicated long/short number or unique brand keyword like "Sinch" if it is a shared short code.
      - `second_word` string — Opt-out keyword like "LEAVE" if _auto_update.to_ is shared short code.
  - `members` string[] — Initial list of phone numbers in [E.164 format](https://community.sinch.com/t5/Glossary/E-164/ta-p/7537) [MSISDNs](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628) for the group.

## Response `201`

Created, or an [Error](https://developers.sinch.com/docs/sms/api-reference/status-codes).

- ApiGroup
  - `id` string — The ID used to reference this group.
  - `name` string — Name of group if set.
  - `size` integer — 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` MtGroupId[] — Phone numbers [MSIDNs](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628) of child group will be included in this group. If present then this group will be auto populated. Constraints: Elements must be group IDs.
  - `auto_update` ApiGroupAutoUpdate
    - `to` string, E.164, required — Short code or long number addressed in [MO](https://community.sinch.com/t5/Glossary/MO-Mobile-Originated/ta-p/7618). Constraints: Must be valid phone number or short code which has been **provisioned by your account manager**.
    - `add` AddKeyword — Keyword to be sent in MO to add MSISDN to a group
      - `first_word` string, required — Opt-in keyword like "JOIN" if _auto_update.to_ is dedicated long/short number or unique brand keyword like "Sinch" if it is a shared short code.
      - `second_word` string — Opt-in keyword like "JOIN" if _auto_update.to_ is shared short code.
    - `remove` RemoveKeyword — Keyword to be sent in MO to remove MSISDN to a group
      - `first_word` string, required — Opt-out keyword like "LEAVE" if _auto_update.to_ is dedicated long/short number or unique brand keyword like "Sinch" if it is a shared short code.
      - `second_word` string — Opt-out keyword like "LEAVE" if _auto_update.to_ is shared short code.

## Other responses

- `400` — Bad request
- `403` — Forbidden

---

[API](https://skmtc.net/sinch/apis/api-overview-sinch.md) · [All operations](https://skmtc.net/sinch/apis/api-overview-sinch/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sinch/api-overview-sinch/revisions/67cb925f1c81/schema)