Sinch Applications API

openapi: 3.2.0
info:
  title: Sinch Voice Applications 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/
servers:
- url: https://calling.api.sinch.com
  description: Global Production Server
security:
- basicAuth: []
tags:
- name: Applications
  description: Manage Voice API applications including retrieving application configuration, updating settings, and managing assigned numbers.
paths:
  /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:
  schemas:
    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
    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
  parameters:
    ApplicationKey:
      name: application_key
      in: path
      required: true
      description: The application key
      schema:
        type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Application key and secret used for HTTP basic authentication. Application-signed requests are also supported.
externalDocs:
  description: Sinch Voice API Documentation
  url: https://developers.sinch.com/docs/voice