Sinch Groups API

openapi: 3.2.0
info:
  title: Sinch SMS Groups API
  description: The Sinch SMS API enables developers to send and receive SMS messages globally at scale. It supports batch messaging with scheduled delivery, message templates, delivery reports, and inbound message handling via webhooks. The API provides group management for organizing recipients, automatic message encoding optimization, and supports both transactional and marketing use cases across carriers worldwide.
  version: '1.0'
  contact:
    name: Sinch Support
    url: https://www.sinch.com/contact-us/
  termsOfService: https://www.sinch.com/terms-of-service/
servers:
- url: https://us.sms.api.sinch.com
  description: US Production Server
- url: https://eu.sms.api.sinch.com
  description: EU Production Server
- url: https://au.sms.api.sinch.com
  description: Australia Production Server
- url: https://br.sms.api.sinch.com
  description: Brazil Production Server
- url: https://ca.sms.api.sinch.com
  description: Canada Production Server
security:
- bearerAuth: []
tags:
- name: Groups
  description: Groups are sets of phone numbers (MSISDNs) that can be used as targets when sending SMS. A phone number can only occur once in a group.
paths:
  /xms/v1/{service_plan_id}/groups:
    post:
      operationId: createGroup
      summary: Create a Group
      description: Creates a new group of phone numbers that can be used as recipients when sending SMS batches.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/ServicePlanId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGroupRequest'
      responses:
        '201':
          description: Group created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
    get:
      operationId: listGroups
      summary: List Groups
      description: Returns a list of groups with pagination support.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/ServicePlanId'
      - name: page
        in: query
        description: The page number to retrieve
        schema:
          type: integer
          default: 0
      - name: page_size
        in: query
        description: The number of groups per page
        schema:
          type: integer
          default: 30
          maximum: 100
      responses:
        '200':
          description: List of groups
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupList'
        '401':
          description: Unauthorized
  /xms/v1/{service_plan_id}/groups/{group_id}:
    get:
      operationId: getGroup
      summary: Get a Group
      description: Returns the details of a specific group.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/ServicePlanId'
      - $ref: '#/components/parameters/GroupId'
      responses:
        '200':
          description: Group details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '401':
          description: Unauthorized
        '404':
          description: Group not found
    post:
      operationId: updateGroup
      summary: Update a Group
      description: Updates an existing group by adding or removing members or changing the group name.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/ServicePlanId'
      - $ref: '#/components/parameters/GroupId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGroupRequest'
      responses:
        '200':
          description: Group updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '401':
          description: Unauthorized
        '404':
          description: Group not found
    delete:
      operationId: deleteGroup
      summary: Delete a Group
      description: Deletes a group and all its members.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/ServicePlanId'
      - $ref: '#/components/parameters/GroupId'
      responses:
        '200':
          description: Group deleted
        '401':
          description: Unauthorized
        '404':
          description: Group not found
  /xms/v1/{service_plan_id}/groups/{group_id}/members:
    get:
      operationId: getGroupMembers
      summary: Get Group Members
      description: Returns the list of phone numbers that are members of the specified group.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/ServicePlanId'
      - $ref: '#/components/parameters/GroupId'
      responses:
        '200':
          description: List of group members
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          description: Unauthorized
        '404':
          description: Group not found
components:
  parameters:
    GroupId:
      name: group_id
      in: path
      required: true
      description: The unique identifier for the group
      schema:
        type: string
    ServicePlanId:
      name: service_plan_id
      in: path
      required: true
      description: The unique identifier for the service plan
      schema:
        type: string
  schemas:
    GroupList:
      type: object
      properties:
        count:
          type: integer
          description: Total number of groups
        page:
          type: integer
          description: Current page number
        page_size:
          type: integer
          description: Number of groups per page
        groups:
          type: array
          description: List of group objects
          items:
            $ref: '#/components/schemas/Group'
    UpdateGroupRequest:
      type: object
      properties:
        name:
          type: string
          description: Updated group name
        add:
          type: array
          description: Phone numbers to add to the group
          items:
            type: string
        remove:
          type: array
          description: Phone numbers to remove from the group
          items:
            type: string
        add_from_group:
          type: string
          description: Add all members from another group
        remove_from_group:
          type: string
          description: Remove all members that are in another group
    CreateGroupRequest:
      type: object
      properties:
        name:
          type: string
          description: The name of the group
        members:
          type: array
          description: List of phone numbers to add as members
          items:
            type: string
        child_groups:
          type: array
          description: List of child group IDs
          items:
            type: string
    Group:
      type: object
      properties:
        id:
          type: string
          description: The unique group identifier
        name:
          type: string
          description: The group name
        size:
          type: integer
          description: The number of members in the group
        created_at:
          type: string
          format: date-time
          description: When the group was created
        modified_at:
          type: string
          format: date-time
          description: When the group was last modified
        child_groups:
          type: array
          description: List of child group IDs
          items:
            type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API token sent in the Authorization header preceded by Bearer.
externalDocs:
  description: Sinch SMS API Documentation
  url: https://developers.sinch.com/docs/sms