openapi: 3.1.0
info:
  title: Sinch Voice API
  description: >-
    The Sinch Voice API is a programmable voice platform that allows developers
    to make, receive, and manage voice calls over PSTN, SIP, and in-app
    channels. It supports text-to-speech in over 115 languages, interactive
    voice response (IVR) menus, call recording, transcription, number masking,
    and conferencing. The API enables outbound and inbound calling with
    real-time call control through callbacks and SVAML instructions.
  version: '1.0'
  contact:
    name: Sinch Support
    url: https://www.sinch.com/contact-us/
  termsOfService: https://www.sinch.com/terms-of-service/
externalDocs:
  description: Sinch Voice API Documentation
  url: https://developers.sinch.com/docs/voice
servers:
  - url: https://calling.api.sinch.com
    description: Global Production Server
tags:
  - name: Applications
    description: >-
      Manage Voice API applications including retrieving application
      configuration, updating settings, and managing assigned numbers.
  - 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.
  - name: Calls
    description: >-
      Manage ongoing calls or retrieve information about a call. Supports
      updating call properties and hanging up calls.
  - name: Conferences
    description: >-
      Manage ongoing conferences including retrieving conference info, muting
      or unmuting participants, and removing participants.
security:
  - basicAuth: []
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
  /calling/v1/calls/id/{call_id}:
    get:
      operationId: getCall
      summary: Get Call Information
      description: >-
        Returns information about a specific call identified by the call ID.
      tags:
        - Calls
      parameters:
        - $ref: '#/components/parameters/CallId'
      responses:
        '200':
          description: Call details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallInformation'
        '401':
          description: Unauthorized
        '404':
          description: Call not found
    patch:
      operationId: updateCall
      summary: Update a Call
      description: >-
        Updates an ongoing call with SVAML instructions. Can be used to play
        prompts, connect calls, or hang up.
      tags:
        - Calls
      parameters:
        - $ref: '#/components/parameters/CallId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SVAMLControl'
      responses:
        '200':
          description: Call updated
        '401':
          description: Unauthorized
        '404':
          description: Call not found
  /calling/v1/conferences/id/{conference_id}:
    get:
      operationId: getConference
      summary: Get Conference Information
      description: >-
        Returns information about an ongoing conference including a list of
        participants.
      tags:
        - Conferences
      parameters:
        - $ref: '#/components/parameters/ConferenceId'
      responses:
        '200':
          description: Conference details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConferenceInfo'
        '401':
          description: Unauthorized
        '404':
          description: Conference not found
    delete:
      operationId: kickAllFromConference
      summary: Kick All Participants from Conference
      description: >-
        Removes all participants from an ongoing conference, effectively
        ending the conference.
      tags:
        - Conferences
      parameters:
        - $ref: '#/components/parameters/ConferenceId'
      responses:
        '200':
          description: All participants removed
        '401':
          description: Unauthorized
        '404':
          description: Conference not found
  /calling/v1/conferences/id/{conference_id}/{call_id}:
    patch:
      operationId: manageConferenceParticipant
      summary: Manage Conference Participant
      description: >-
        Manages a specific participant in a conference. Can mute, unmute, or
        put a participant on hold.
      tags:
        - Conferences
      parameters:
        - $ref: '#/components/parameters/ConferenceId'
        - $ref: '#/components/parameters/CallId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManageParticipantRequest'
      responses:
        '200':
          description: Participant updated
        '401':
          description: Unauthorized
        '404':
          description: Conference or participant not found
    delete:
      operationId: kickParticipantFromConference
      summary: Kick Participant from Conference
      description: >-
        Removes a specific participant from an ongoing conference.
      tags:
        - Conferences
      parameters:
        - $ref: '#/components/parameters/ConferenceId'
        - $ref: '#/components/parameters/CallId'
      responses:
        '200':
          description: Participant removed
        '401':
          description: Unauthorized
        '404':
          description: Conference or participant not found
  /calling/v1/configuration/numbers:
    get:
      operationId: getNumbers
      summary: Get Numbers Assigned to Application
      description: >-
        Returns the list of phone numbers assigned to the Voice API application.
      tags:
        - Applications
      responses:
        '200':
          description: List of numbers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberList'
        '401':
          description: Unauthorized
  /calling/v1/configuration/callbacks/applications/{application_key}:
    get:
      operationId: getApplicationCallbacks
      summary: Get Application Callback Urls
      description: >-
        Returns the callback URLs configured for a specific application.
      tags:
        - Applications
      parameters:
        - $ref: '#/components/parameters/ApplicationKey'
      responses:
        '200':
          description: Application callback configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationCallbacks'
        '401':
          description: Unauthorized
        '404':
          description: Application not found
    post:
      operationId: updateApplicationCallbacks
      summary: Update Application Callback Urls
      description: >-
        Updates the callback URLs for a specific application.
      tags:
        - Applications
      parameters:
        - $ref: '#/components/parameters/ApplicationKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationCallbacks'
      responses:
        '200':
          description: Callbacks updated
        '401':
          description: Unauthorized
        '404':
          description: Application not found
  /calling/v1/configuration/numbers/{number}:
    get:
      operationId: getNumberConfiguration
      summary: Get Number Configuration
      description: >-
        Returns the configuration for a specific phone number.
      tags:
        - Applications
      parameters:
        - name: number
          in: path
          required: true
          description: The phone number in E.164 format
          schema:
            type: string
      responses:
        '200':
          description: Number configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberConfiguration'
        '401':
          description: Unauthorized
        '404':
          description: Number not found
    post:
      operationId: updateNumberConfiguration
      summary: Update Number Configuration
      description: >-
        Updates the configuration for a specific phone number including
        the application key assignment and capability.
      tags:
        - Applications
      parameters:
        - name: number
          in: path
          required: true
          description: The phone number in E.164 format
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NumberConfiguration'
      responses:
        '200':
          description: Number configuration updated
        '401':
          description: Unauthorized
        '404':
          description: Number not found
    delete:
      operationId: unassignNumber
      summary: Unassign a Number
      description: >-
        Unassigns a phone number from the application.
      tags:
        - Applications
      parameters:
        - name: number
          in: path
          required: true
          description: The phone number in E.164 format
          schema:
            type: string
      responses:
        '200':
          description: Number unassigned
        '401':
          description: Unauthorized
        '404':
          description: Number not found
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Application key and secret used for HTTP basic authentication.
        Application-signed requests are also supported.
  parameters:
    CallId:
      name: call_id
      in: path
      required: true
      description: The unique call identifier
      schema:
        type: string
    ConferenceId:
      name: conference_id
      in: path
      required: true
      description: The unique conference identifier
      schema:
        type: string
    ApplicationKey:
      name: application_key
      in: path
      required: true
      description: The application key
      schema:
        type: string
  schemas:
    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'
    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
    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
    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
    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
    CallInformation:
      type: object
      properties:
        from:
          type: string
          description: The caller number
        to:
          type: string
          description: The callee number
        domain:
          type: string
          description: The call domain
        callId:
          type: string
          description: The unique call identifier
        duration:
          type: integer
          description: The call duration in seconds
        status:
          type: string
          description: The current call status
        result:
          type: string
          description: The call result
        reason:
          type: string
          description: The reason for call disconnection
        timestamp:
          type: string
          format: date-time
          description: When the call was initiated
        userRate:
          $ref: '#/components/schemas/Price'
        debit:
          $ref: '#/components/schemas/Price'
    Price:
      type: object
      properties:
        currencyId:
          type: string
          description: The currency code
        amount:
          type: number
          description: The amount
    SVAMLControl:
      type: object
      properties:
        action:
          type: object
          description: The SVAML action to execute
          properties:
            name:
              type: string
              description: The action name
        instructions:
          type: array
          description: List of SVAML instructions
          items:
            type: object
            properties:
              name:
                type: string
                description: The instruction name
    ManageParticipantRequest:
      type: object
      properties:
        command:
          type: string
          enum:
            - mute
            - unmute
            - onhold
            - resume
          description: The command to execute on the participant
    ConferenceInfo:
      type: object
      properties:
        conferenceId:
          type: string
          description: The conference identifier
        participants:
          type: array
          description: List of participants in the conference
          items:
            $ref: '#/components/schemas/Participant'
    Participant:
      type: object
      properties:
        cli:
          type: string
          description: The participant caller ID
        callId:
          type: string
          description: The participant call ID
        duration:
          type: integer
          description: Duration in conference in seconds
        muted:
          type: boolean
          description: Whether the participant is muted
        onhold:
          type: boolean
          description: Whether the participant is on hold
    NumberList:
      type: object
      properties:
        numbers:
          type: array
          description: List of phone numbers
          items:
            $ref: '#/components/schemas/NumberConfiguration'
    NumberConfiguration:
      type: object
      properties:
        number:
          type: string
          description: The phone number in E.164 format
        applicationKey:
          type: string
          description: The application key the number is assigned to
        capability:
          type: string
          enum:
            - voice
            - sms
          description: The number capability
    ApplicationCallbacks:
      type: object
      properties:
        url:
          type: object
          description: Callback URL configuration
          properties:
            primary:
              type: string
              format: uri
              description: The primary callback URL
            fallback:
              type: string
              format: uri
              description: The fallback callback URL