openapi: 3.1.0
info:
  title: MessageBird Balance Available Numbers Groups API
  description: The MessageBird Balance API provides developers with access to their account balance information. It returns the current payment type, available amount, and currency for the account associated with the API key. This API is useful for monitoring credit usage, building billing dashboards, and setting up automated alerts when account balances fall below a threshold.
  version: '1.0'
  contact:
    name: MessageBird Support
    url: https://support.messagebird.com
  termsOfService: https://www.messagebird.com/en/terms
servers:
- url: https://rest.messagebird.com
  description: Production Server
security:
- accessKey: []
tags:
- name: Groups
  description: Operations for managing contact groups.
paths:
  /contacts/{contactId}/groups:
    get:
      operationId: listContactGroups
      summary: List groups for a contact
      description: Retrieves all groups that a specific contact belongs to.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/contactIdParam'
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: A list of groups
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupList'
        '401':
          description: Unauthorized
        '404':
          description: Contact not found
  /groups:
    get:
      operationId: listGroups
      summary: List groups
      description: Retrieves a paginated list of all contact groups.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: A list of groups
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupList'
        '401':
          description: Unauthorized
    post:
      operationId: createGroup
      summary: Create a group
      description: Creates a new contact group with the specified name.
      tags:
      - Groups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupCreate'
      responses:
        '201':
          description: Group created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /groups/{groupId}:
    get:
      operationId: viewGroup
      summary: View a group
      description: Retrieves the details of a specific group by its unique identifier.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/groupIdParam'
      responses:
        '200':
          description: Group details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '401':
          description: Unauthorized
        '404':
          description: Group not found
    patch:
      operationId: updateGroup
      summary: Update a group
      description: Updates the name of an existing group.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/groupIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupCreate'
      responses:
        '200':
          description: Group updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Group not found
    delete:
      operationId: deleteGroup
      summary: Delete a group
      description: Deletes an existing group. This does not delete the contacts in the group.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/groupIdParam'
      responses:
        '204':
          description: Group deleted
        '401':
          description: Unauthorized
        '404':
          description: Group not found
  /groups/{groupId}/contacts:
    get:
      operationId: listGroupContacts
      summary: List contacts in a group
      description: Retrieves all contacts that belong to a specific group.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/groupIdParam'
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: A list of contacts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
        '401':
          description: Unauthorized
        '404':
          description: Group not found
    put:
      operationId: addContactsToGroup
      summary: Add contacts to a group
      description: Adds one or more contacts to a group by their contact identifiers.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/groupIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  description: The list of contact identifiers to add.
                  items:
                    type: string
      responses:
        '204':
          description: Contacts added to group
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Group not found
  /groups/{groupId}/contacts/{contactId}:
    delete:
      operationId: removeContactFromGroup
      summary: Remove a contact from a group
      description: Removes a specific contact from a group.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/groupIdParam'
      - $ref: '#/components/parameters/contactIdParam'
      responses:
        '204':
          description: Contact removed from group
        '401':
          description: Unauthorized
        '404':
          description: Resource not found
components:
  parameters:
    limitParam:
      name: limit
      in: query
      required: false
      description: The maximum number of items to return.
      schema:
        type: integer
        default: 20
    contactIdParam:
      name: contactId
      in: path
      required: true
      description: The unique identifier of the contact.
      schema:
        type: string
    groupIdParam:
      name: groupId
      in: path
      required: true
      description: The unique identifier of the group.
      schema:
        type: string
    offsetParam:
      name: offset
      in: query
      required: false
      description: The number of items to skip.
      schema:
        type: integer
        default: 0
  schemas:
    Group:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the group.
        href:
          type: string
          format: uri
          description: The URL of the group resource.
        name:
          type: string
          description: The name of the group.
        contacts:
          type: object
          description: Links to the contacts in the group.
          properties:
            href:
              type: string
              format: uri
            totalCount:
              type: integer
        createdDatetime:
          type: string
          format: date-time
          description: The date and time when the group was created.
        updatedDatetime:
          type: string
          format: date-time
          description: The date and time when the group was last updated.
    GroupCreate:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: The name of the group.
    ContactList:
      type: object
      properties:
        offset:
          type: integer
          description: The offset of the result set.
        limit:
          type: integer
          description: The limit applied to the result set.
        count:
          type: integer
          description: The number of items returned.
        totalCount:
          type: integer
          description: The total number of contacts.
        items:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
    Contact:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the contact.
        href:
          type: string
          format: uri
          description: The URL of the contact resource.
        msisdn:
          type: string
          description: The phone number of the contact.
        firstName:
          type: string
          description: The first name of the contact.
        lastName:
          type: string
          description: The last name of the contact.
        custom1:
          type: string
          description: Custom field 1.
        custom2:
          type: string
          description: Custom field 2.
        custom3:
          type: string
          description: Custom field 3.
        custom4:
          type: string
          description: Custom field 4.
        groups:
          type: object
          description: Links to the groups the contact belongs to.
          properties:
            href:
              type: string
              format: uri
            totalCount:
              type: integer
        messages:
          type: object
          description: Links to messages associated with the contact.
          properties:
            href:
              type: string
              format: uri
            totalCount:
              type: integer
        createdDatetime:
          type: string
          format: date-time
          description: The date and time when the contact was created.
        updatedDatetime:
          type: string
          format: date-time
          description: The date and time when the contact was last updated.
    GroupList:
      type: object
      properties:
        offset:
          type: integer
          description: The offset of the result set.
        limit:
          type: integer
          description: The limit applied to the result set.
        count:
          type: integer
          description: The number of items returned.
        totalCount:
          type: integer
          description: The total number of groups.
        items:
          type: array
          items:
            $ref: '#/components/schemas/Group'
  securitySchemes:
    accessKey:
      type: apiKey
      in: header
      name: Authorization
      description: Access key authentication in the form of 'AccessKey {accessKey}'.
externalDocs:
  description: Balance API Documentation
  url: https://developers.messagebird.com/api/balance/