openapi: 3.1.0
info:
  title: Sinch Brands Access Control Lists Callouts API
  description: The Sinch Brands API allows developers to create, update, and manage customer brand profiles used across Sinch messaging products. Brands represent the business identity associated with messaging campaigns and sender registrations. The API provides endpoints for creating brand records, updating brand details, listing brands, and deleting brands, enabling programmatic management of the brand entities required for compliant business messaging.
  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://brands.api.sinch.com
  description: Global Production Server
security:
- bearerAuth: []
tags:
- name: Callouts
  description: Callouts are calls made to a phone number or app using the API. Supported types include conference callouts, text-to-speech callouts, and custom callouts.
paths:
  /calling/v1/callouts:
    post:
      operationId: createCallout
      summary: Make a Callout
      description: Makes a call to a phone number or app. The callout type determines the behavior of the call, including conference callouts, text-to-speech callouts, and custom callouts with SVAML control.
      tags:
      - Callouts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalloutRequest'
      responses:
        '200':
          description: Callout initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalloutResponse'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
components:
  schemas:
    ConferenceCallout:
      type: object
      required:
      - cli
      - destination
      - conferenceId
      properties:
        cli:
          type: string
          description: The caller ID to display
        destination:
          $ref: '#/components/schemas/Destination'
        conferenceId:
          type: string
          description: The conference identifier to connect to
        dtmf:
          type: string
          description: DTMF tones to play when the call is answered
        maxDuration:
          type: integer
          description: Maximum duration of the call in seconds
        enableAce:
          type: boolean
          description: Enable Answered Call Event callback
        enableDice:
          type: boolean
          description: Enable Disconnected Call Event callback
        enablePie:
          type: boolean
          description: Enable Prompt Input Event callback
        locale:
          type: string
          description: Locale for text-to-speech
        greeting:
          type: string
          description: Text-to-speech greeting when joining conference
        mohClass:
          type: string
          description: Music on hold class
    CustomCallout:
      type: object
      required:
      - cli
      - destination
      - ice
      properties:
        cli:
          type: string
          description: The caller ID to display
        destination:
          $ref: '#/components/schemas/Destination'
        ice:
          type: string
          description: SVAML ICE response in JSON format
        ace:
          type: string
          description: SVAML ACE response in JSON format
        pie:
          type: string
          description: SVAML PIE response in JSON format
    CalloutRequest:
      type: object
      required:
      - method
      properties:
        method:
          type: string
          enum:
          - conferenceCallout
          - ttsCallout
          - customCallout
          description: The callout method type
        conferenceCallout:
          $ref: '#/components/schemas/ConferenceCallout'
        ttsCallout:
          $ref: '#/components/schemas/TtsCallout'
        customCallout:
          $ref: '#/components/schemas/CustomCallout'
    Destination:
      type: object
      required:
      - type
      - endpoint
      properties:
        type:
          type: string
          enum:
          - number
          - username
          - sip
          - did
          description: The destination type
        endpoint:
          type: string
          description: The destination endpoint identifier
    CalloutResponse:
      type: object
      properties:
        callId:
          type: string
          description: The unique call identifier for the initiated call
    TtsCallout:
      type: object
      required:
      - cli
      - destination
      - text
      properties:
        cli:
          type: string
          description: The caller ID to display
        destination:
          $ref: '#/components/schemas/Destination'
        text:
          type: string
          description: The text to convert to speech
        locale:
          type: string
          description: The locale for text-to-speech
        enableAce:
          type: boolean
          description: Enable Answered Call Event callback
        enableDice:
          type: boolean
          description: Enable Disconnected Call Event callback
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication.
externalDocs:
  description: Sinch Brands API Documentation
  url: https://developers.sinch.com/docs/brands