openapi: 3.1.0
info:
  title: MessageBird Balance Available Numbers Contacts 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: Contacts
  description: Operations for managing individual contacts.
paths:
  /contacts:
    get:
      operationId: listContacts
      summary: List contacts
      description: Retrieves a paginated list of all contacts in the address book.
      tags:
      - Contacts
      parameters:
      - $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
    post:
      operationId: createContact
      summary: Create a contact
      description: Creates a new contact in the address book with the specified phone number and optional details.
      tags:
      - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCreate'
      responses:
        '201':
          description: Contact created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '422':
          description: Unprocessable entity
  /contacts/{contactId}:
    get:
      operationId: viewContact
      summary: View a contact
      description: Retrieves the details of a specific contact by its unique identifier.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/contactIdParam'
      responses:
        '200':
          description: Contact details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          description: Unauthorized
        '404':
          description: Contact not found
    patch:
      operationId: updateContact
      summary: Update a contact
      description: Updates an existing contact with the provided fields.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/contactIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactUpdate'
      responses:
        '200':
          description: Contact updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Contact not found
    delete:
      operationId: deleteContact
      summary: Delete a contact
      description: Deletes a contact from the address book by its unique identifier.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/contactIdParam'
      responses:
        '204':
          description: Contact deleted
        '401':
          description: Unauthorized
        '404':
          description: Contact not found
  /contacts/{contactId}/messages:
    get:
      operationId: listContactMessages
      summary: List messages for a contact
      description: Retrieves all messages associated with a specific contact.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/contactIdParam'
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: A list of messages
          content:
            application/json:
              schema:
                type: object
                properties:
                  offset:
                    type: integer
                  limit:
                    type: integer
                  count:
                    type: integer
                  totalCount:
                    type: integer
                  items:
                    type: array
                    items:
                      type: object
        '401':
          description: Unauthorized
        '404':
          description: Contact 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
    offsetParam:
      name: offset
      in: query
      required: false
      description: The number of items to skip.
      schema:
        type: integer
        default: 0
  schemas:
    ContactCreate:
      type: object
      required:
      - msisdn
      properties:
        msisdn:
          type: string
          description: The phone number of the contact in international format.
        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.
    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.
    ContactUpdate:
      type: object
      properties:
        firstName:
          type: string
          description: The first name of the contact.
        lastName:
          type: string
          description: The last name of the contact.
        msisdn:
          type: string
          description: The phone number 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.
  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/