openapi: 3.1.0
info:
  title: MessageBird Balance Available Numbers Calls 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: Calls
  description: Operations for creating, listing, and managing voice calls.
paths:
  /calls:
    get:
      operationId: listCalls
      summary: List all calls
      description: Retrieves a paginated list of all calls made or received on the account.
      tags:
      - Calls
      parameters:
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/perPageParam'
      responses:
        '200':
          description: A list of calls
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallList'
        '401':
          description: Unauthorized
    post:
      operationId: createCall
      summary: Create a call
      description: Creates a new outbound call. The call will be placed from the specified source to the destination number, and the call flow will be executed.
      tags:
      - Calls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallCreate'
      responses:
        '201':
          description: Call created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /calls/{callId}:
    get:
      operationId: viewCall
      summary: View a call
      description: Retrieves the details of an existing call by its unique identifier.
      tags:
      - Calls
      parameters:
      - $ref: '#/components/parameters/callIdParam'
      responses:
        '200':
          description: Call details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallResponse'
        '401':
          description: Unauthorized
        '404':
          description: Call not found
    delete:
      operationId: deleteCall
      summary: Delete a call
      description: Deletes an existing call by hanging up all active legs and removing the call resource.
      tags:
      - Calls
      parameters:
      - $ref: '#/components/parameters/callIdParam'
      responses:
        '204':
          description: Call deleted
        '401':
          description: Unauthorized
        '404':
          description: Call not found
components:
  schemas:
    CallCreate:
      type: object
      required:
      - source
      - destination
      - callFlow
      properties:
        source:
          type: string
          description: The caller ID to display, must be a purchased MessageBird number.
        destination:
          type: string
          description: The phone number or SIP URI to call.
        callFlow:
          $ref: '#/components/schemas/CallFlowCreate'
        webhook:
          $ref: '#/components/schemas/VoiceWebhookCreate'
    CallFlowStep:
      type: object
      required:
      - action
      properties:
        id:
          type: string
          description: The unique identifier of the step.
        action:
          type: string
          description: The action to perform in this step.
          enum:
          - say
          - play
          - pause
          - record
          - fetchCallFlow
          - hangup
          - transfer
        options:
          type: object
          description: Action-specific options for the step.
    Call:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the call.
        status:
          type: string
          description: The status of the call.
          enum:
          - queued
          - starting
          - ongoing
          - ended
        source:
          type: string
          description: The caller ID number.
        destination:
          type: string
          description: The destination number or SIP URI.
        createdAt:
          type: string
          format: date-time
          description: The date and time when the call was created.
        updatedAt:
          type: string
          format: date-time
          description: The date and time when the call was last updated.
        endedAt:
          type: string
          format: date-time
          description: The date and time when the call ended.
    CallFlowCreate:
      type: object
      required:
      - steps
      properties:
        title:
          type: string
          description: A human-readable title for the call flow.
        record:
          type: boolean
          description: Whether to record the entire call.
        steps:
          type: array
          description: A sequence of steps that define the call flow behavior.
          items:
            $ref: '#/components/schemas/CallFlowStep'
    VoiceWebhookCreate:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
          description: The URL to receive webhook callbacks.
        token:
          type: string
          description: A token for webhook signature validation.
    CallResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Call'
    Pagination:
      type: object
      properties:
        totalCount:
          type: integer
          description: The total number of items available.
        pageCount:
          type: integer
          description: The total number of pages.
        currentPage:
          type: integer
          description: The current page number.
        perPage:
          type: integer
          description: The number of items per page.
    CallList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Call'
        pagination:
          $ref: '#/components/schemas/Pagination'
  parameters:
    pageParam:
      name: page
      in: query
      required: false
      description: The page number for pagination.
      schema:
        type: integer
        default: 1
    perPageParam:
      name: perPage
      in: query
      required: false
      description: The number of items per page.
      schema:
        type: integer
        default: 10
    callIdParam:
      name: callId
      in: path
      required: true
      description: The unique identifier of the call.
      schema:
        type: string
  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/