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

Endpoint: POST /xms/v1/{service_plan_id}/groups
Version: v1
Security: BearerAuth

## Path parameters:

  - `service_plan_id` (string, required)
    Your service plan ID. You can find this on your Dashboard.
    Example: "jd63jf88477ll123ab4567cd89012ef3"

## Request fields (application/json):

  - `name` (string)
    Name of group if set.
    Example: "My new customers"

  - `child_groups` (array)
    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.
    Example: ["01FC66621VHDBN119Z8PMV1AHY"]

  - `auto_update` (object)

  - `auto_update.to` (string, 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.
    Example: "+15551231234"

  - `auto_update.add` (object)
    Keyword to be sent in MO to add MSISDN to a group

  - `auto_update.add.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.
    Example: "Sinch"

  - `auto_update.add.second_word` (string)
    Opt-in keyword like "JOIN" if _auto_update.to_ is shared short code.
    Example: "JOIN"

  - `auto_update.remove` (object)
    Keyword to be sent in MO to remove MSISDN to a group

  - `auto_update.remove.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.
    Example: "LEAVE"

  - `auto_update.remove.second_word` (string)
    Opt-out keyword like "LEAVE" if _auto_update.to_ is shared short code.

  - `members` (array)
    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.
    Example: ["+15551231234","+15551256344"]

## Response 201 fields (application/json):

  - `id` (string)
    The ID used to reference this group.
    Example: "01FC66621VHDBN119Z8PMV1QPQ"

  - `name` (string)
    Name of group if set.
    Example: "My new customers"

  - `size` (integer)
    The number of members currently in the group.
    Example: 2

  - `created_at` (string)
    Timestamp for group creation. Format: YYYY-MM-DDThh:mm:ss.SSSZ

  - `modified_at` (string)
    Timestamp for when the group was last updated. Format: YYYY-MM-DDThh:mm:ss.SSSZ

  - `child_groups` (array)
    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.
    Example: ["01FC66621VHDBN119Z8PMV1AHY"]

  - `auto_update` (object)

  - `auto_update.to` (string, 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.
    Example: "+15551231234"

  - `auto_update.add` (object)
    Keyword to be sent in MO to add MSISDN to a group

  - `auto_update.add.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.
    Example: "Sinch"

  - `auto_update.add.second_word` (string)
    Opt-in keyword like "JOIN" if _auto_update.to_ is shared short code.
    Example: "JOIN"

  - `auto_update.remove` (object)
    Keyword to be sent in MO to remove MSISDN to a group

  - `auto_update.remove.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.
    Example: "LEAVE"

  - `auto_update.remove.second_word` (string)
    Opt-out keyword like "LEAVE" if _auto_update.to_ is shared short code.

## Response 400 fields (application/json):

  - `code` (string)
    The error code. See [error codes](https://developers.sinch.com/docs/sms/api-reference/status-codes/).

  - `text` (string)
    The human readable description of the error.

## Response 403 fields (application/json):

  - `code` (string)
    The error code. See [error codes](https://developers.sinch.com/docs/sms/api-reference/status-codes/).

  - `text` (string)
    The human readable description of the error.