Microsoft Azure Communication Services Pre Connections API

openapi: 3.2.0
info:
  title: Azure Communication Service Call Automation Pre Connections…
  description: Azure Communication Service Call Automation APIs
  version: '2026-03-12'
servers:
- url: https://contoso.communication.azure.com
security:
- Authorization: []
tags:
- name: PreConnections
paths:
  /calling/callConnections:
    post:
      tags:
      - PreConnections
      summary: Create an outbound call
      description: Create an outbound call.
      operationId: CreateCall
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - in: header
        name: Repeatability-Request-ID
        description: If specified, the client directs that the request is repeatable; that is, that the client can make the request multiple times with the same Repeatability-Request-Id and get back an appropriate response without the server executing the request multiple times. The value of the Repeatability-Request-Id is an opaque string representing a client-generated unique identifier for the request. It is a version 4 (random) UUID.
        schema:
          type: string
          format: uuid
      - in: header
        name: Repeatability-First-Sent
        description: 'If Repeatability-Request-ID header is specified, then Repeatability-First-Sent header must also be specified. The value should be the date and time at which the request was first created, expressed using the IMF-fixdate form of HTTP-date. Example: Sun, 06 Nov 1994 08:49:37 GMT.'
        schema:
          type: string
          format: date-time-rfc1123
      responses:
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
        '201':
          description: Returns details of the call properties once the CreateCall request is received by service. You will receive CallConnected event at your specified callback URI, once the call is connected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallConnectionProperties'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCallRequest'
        description: The create call request.
        required: true
  /calling/callConnections:answer:
    post:
      tags:
      - PreConnections
      summary: Answer a Call
      description: Answer a call using the IncomingCallContext from Event Grid.
      operationId: AnswerCall
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - in: header
        name: Repeatability-Request-ID
        description: If specified, the client directs that the request is repeatable; that is, that the client can make the request multiple times with the same Repeatability-Request-Id and get back an appropriate response without the server executing the request multiple times. The value of the Repeatability-Request-Id is an opaque string representing a client-generated unique identifier for the request. It is a version 4 (random) UUID.
        schema:
          type: string
          format: uuid
      - in: header
        name: Repeatability-First-Sent
        description: 'If Repeatability-Request-ID header is specified, then Repeatability-First-Sent header must also be specified. The value should be the date and time at which the request was first created, expressed using the IMF-fixdate form of HTTP-date. Example: Sun, 06 Nov 1994 08:49:37 GMT.'
        schema:
          type: string
          format: date-time-rfc1123
      responses:
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
        '200':
          description: Returns details of the call properties once the AnswerCall request is received by service. You will receive CallConnected event at your specified callback URI, once the call is connected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallConnectionProperties'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnswerCallRequest'
        description: The answer call request.
        required: true
  /calling/callConnections:redirect:
    post:
      tags:
      - PreConnections
      summary: Redirect a call
      description: Redirect a call.
      operationId: RedirectCall
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - in: header
        name: Repeatability-Request-ID
        description: If specified, the client directs that the request is repeatable; that is, that the client can make the request multiple times with the same Repeatability-Request-Id and get back an appropriate response without the server executing the request multiple times. The value of the Repeatability-Request-Id is an opaque string representing a client-generated unique identifier for the request. It is a version 4 (random) UUID.
        schema:
          type: string
          format: uuid
      - in: header
        name: Repeatability-First-Sent
        description: 'If Repeatability-Request-ID header is specified, then Repeatability-First-Sent header must also be specified. The value should be the date and time at which the request was first created, expressed using the IMF-fixdate form of HTTP-date. Example: Sun, 06 Nov 1994 08:49:37 GMT.'
        schema:
          type: string
          format: date-time-rfc1123
      responses:
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
        '204':
          description: The service has redirected the call to specified endpoint.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedirectCallRequest'
        description: The redirect call request.
        required: true
  /calling/callConnections:reject:
    post:
      tags:
      - PreConnections
      summary: Reject the call
      description: Reject the call.
      operationId: RejectCall
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - in: header
        name: Repeatability-Request-ID
        description: If specified, the client directs that the request is repeatable; that is, that the client can make the request multiple times with the same Repeatability-Request-Id and get back an appropriate response without the server executing the request multiple times. The value of the Repeatability-Request-Id is an opaque string representing a client-generated unique identifier for the request. It is a version 4 (random) UUID.
        schema:
          type: string
          format: uuid
      - in: header
        name: Repeatability-First-Sent
        description: 'If Repeatability-Request-ID header is specified, then Repeatability-First-Sent header must also be specified. The value should be the date and time at which the request was first created, expressed using the IMF-fixdate form of HTTP-date. Example: Sun, 06 Nov 1994 08:49:37 GMT.'
        schema:
          type: string
          format: date-time-rfc1123
      responses:
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
        '204':
          description: The service has rejected the call.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RejectCallRequest'
        description: The reject call request.
        required: true
  /calling/callConnections:connect:
    post:
      tags:
      - PreConnections
      summary: Create a Connection to a CallLocator
      description: Create a connection to a CallLocator.
      operationId: Connect
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - in: header
        name: Repeatability-Request-ID
        description: If specified, the client directs that the request is repeatable; that is, that the client can make the request multiple times with the same Repeatability-Request-Id and get back an appropriate response without the server executing the request multiple times. The value of the Repeatability-Request-Id is an opaque string representing a client-generated unique identifier for the request. It is a version 4 (random) UUID.
        schema:
          type: string
          format: uuid
      - in: header
        name: Repeatability-First-Sent
        description: 'If Repeatability-Request-ID header is specified, then Repeatability-First-Sent header must also be specified. The value should be the date and time at which the request was first created, expressed using the IMF-fixdate form of HTTP-date. Example: Sun, 06 Nov 1994 08:49:37 GMT.'
        schema:
          type: string
          format: date-time-rfc1123
      responses:
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
        '200':
          description: Returns connection to a callLocator
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallConnectionProperties'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectRequest'
        description: The create connection request.
        required: true
components:
  schemas:
    CommonMicrosoftTeamsAppIdentifierModel:
      description: A Microsoft Teams application.
      type: object
      required:
      - appId
      properties:
        appId:
          type: string
          description: The Id of the Microsoft Teams application.
        cloud:
          $ref: '#/components/schemas/CommunicationCloudEnvironmentModel'
          description: The cloud that the Microsoft Teams application belongs to. By default 'public' if missing.
    TranscriptionSubscriptionState:
      description: Current state of transcription session
      enum:
      - disabled
      - inactive
      - active
      type: string
      x-ms-enum:
        name: TranscriptionSubscriptionState
        modelAsString: true
    CommonCommunicationIdentifierModel:
      description: 'Identifies a participant in Azure Communication services. A participant is, for example, a phone number or an Azure communication user. This model is polymorphic: Apart from kind and rawId, at most one further property may be set which must match the kind enum value.'
      type: object
      properties:
        kind:
          $ref: '#/components/schemas/CommunicationIdentifierModelKind'
          description: The identifier kind. Only required in responses.
        rawId:
          type: string
          description: Raw Id of the identifier. Optional in requests, required in responses.
        communicationUser:
          $ref: '#/components/schemas/CommunicationUserIdentifierModel'
          description: The communication user.
        phoneNumber:
          $ref: '#/components/schemas/PhoneNumberIdentifierModel'
          description: The phone number.
        microsoftTeamsUser:
          $ref: '#/components/schemas/MicrosoftTeamsUserIdentifierModel'
          description: The Microsoft Teams user.
        microsoftTeamsApp:
          $ref: '#/components/schemas/MicrosoftTeamsAppIdentifierModel'
          description: The Microsoft Teams application.
        teamsExtensionUser:
          $ref: '#/components/schemas/TeamsExtensionUserIdentifierModel'
          description: The Microsoft Teams Extension user.
    TranscriptionOptions:
      description: Options for live transcription.
      required:
      - locale
      - transportType
      type: object
      properties:
        transportType:
          $ref: '#/components/schemas/StreamingTransportType'
        locale:
          description: Specifies the Locale used for transcription, e.g., en-CA or en-AU.
          type: string
      discriminator:
        propertyName: transportType
    CallConnectionStateModel:
      description: The states of a call connection.
      enum:
      - unknown
      - connecting
      - connected
      - transferring
      - transferAccepted
      - disconnecting
      - disconnected
      type: string
      x-ms-enum:
        name: CallConnectionStateModel
        modelAsString: true
    RedirectCallRequest:
      description: The request payload for redirecting the call.
      required:
      - incomingCallContext
      - target
      type: object
      properties:
        incomingCallContext:
          description: The context associated with the call.
          type: string
        target:
          $ref: '#/components/schemas/CommunicationIdentifierModel'
      additionalProperties: false
    CallRejectReason:
      description: Reason of rejecting a call
      enum:
      - none
      - busy
      - forbidden
      type: string
      x-ms-enum:
        name: CallRejectReason
        modelAsString: true
    CommonCommunicationErrorResponse:
      description: The Communication Services error.
      type: object
      required:
      - error
      properties:
        error:
          description: The Communication Services error.
          $ref: '#/components/schemas/CommunicationError'
    MediaStreamingAudioChannelType:
      description: The audio channel type to stream, e.g., unmixed audio, mixed audio.
      enum:
      - mixed
      - unmixed
      type: string
      x-ms-enum:
        name: MediaStreamingAudioChannelType
        modelAsString: true
    CallConnectionProperties:
      description: Properties of a call connection
      type: object
      properties:
        callConnectionId:
          description: The call connection id.
          type: string
        serverCallId:
          description: The server call id.
          type: string
        targets:
          description: The targets of the call.
          type: array
          items:
            $ref: '#/components/schemas/CommunicationIdentifierModel'
        callConnectionState:
          $ref: '#/components/schemas/CallConnectionStateModel'
        callbackUri:
          description: The callback URI.
          type: string
        sourceCallerIdNumber:
          $ref: '#/components/schemas/PhoneNumberIdentifierModel'
        sourceDisplayName:
          description: Display name of the call if dialing out to a pstn number.
          type: string
        source:
          $ref: '#/components/schemas/CommunicationIdentifierModel'
        correlationId:
          description: The correlation ID.
          type: string
        answeredBy:
          $ref: '#/components/schemas/CommunicationUserIdentifierModel'
        mediaStreamingSubscription:
          $ref: '#/components/schemas/MediaStreamingSubscription'
        transcriptionSubscription:
          $ref: '#/components/schemas/TranscriptionSubscription'
        answeredFor:
          $ref: '#/components/schemas/PhoneNumberIdentifierModel'
      additionalProperties: false
    CommunicationError:
      $ref: '#/components/schemas/CommonCommunicationError'
    CommonPhoneNumberIdentifierModel:
      description: A phone number.
      type: object
      required:
      - value
      properties:
        value:
          type: string
          description: The phone number, usually in E.164 format.
        isAnonymous:
          type: boolean
          description: True if the phone number is anonymous. By default false if missing. If the phone number is anonymous, the value will be the string 'anonymous'.
        assertedId:
          type: string
          description: The asserted Id of the phone number. An asserted Id gets generated when the same phone number joins the same call more than once.
    ConnectRequest:
      description: The request payload for creating a connection to a CallLocator.
      required:
      - callbackUri
      - callLocator
      type: object
      properties:
        callLocator:
          $ref: '#/components/schemas/CallLocator'
        callbackUri:
          description: The callback URI.
          type: string
        operationContext:
          description: Used by customers to correlate the request to the response event.
          type: string
        callIntelligenceOptions:
          $ref: '#/components/schemas/CallIntelligenceOptions'
        mediaStreamingOptions:
          $ref: '#/components/schemas/MediaStreamingOptions'
        transcriptionOptions:
          $ref: '#/components/schemas/TranscriptionOptions'
      additionalProperties: false
    CommonCommunicationError:
      description: The Communication Services error.
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: The error code.
        message:
          type: string
          description: The error message.
        target:
          type: string
          readOnly: true
          description: The error target.
        details:
          type: array
          items:
            $ref: '#/components/schemas/CommunicationError'
          readOnly: true
          description: Further details about specific errors that led to this error.
        innererror:
          x-ms-client-name: innerError
          readOnly: true
          $ref: '#/components/schemas/CommunicationError'
          description: The inner error if any.
    CommonCommunicationUserIdentifierModel:
      description: A user that got created with an Azure Communication Services resource.
      type: object
      required:
      - id
      properties:
        id:
          type: string
          description: The Id of the communication user.
    CallLocatorKind:
      description: The call locator kind
      enum:
      - groupCallLocator
      - serverCallLocator
      - roomCallLocator
      type: string
      x-ms-enum:
        name: CallLocatorKind
        modelAsString: true
    MediaStreamingContentType:
      description: Type of content in Media streaming.
      enum:
      - audio
      type: string
      x-ms-enum:
        name: MediaStreamingContentType
        modelAsString: true
    CallLocator:
      description: The locator used for joining or taking action on a call
      type: object
      properties:
        groupCallId:
          description: The group call id
          type: string
        serverCallId:
          description: The server call id.
          type: string
        roomId:
          description: The Acs room id. (Not supported for Start Recording)
          type: string
        kind:
          $ref: '#/components/schemas/CallLocatorKind'
      additionalProperties: false
    StreamingTransportType:
      description: Defines the transport type used for streaming. Note that future values may be introduced that are not currently documented.
      enum:
      - websocket
      type: string
      x-ms-enum:
        name: StreamingTransportType
        modelAsString: true
    CommonTeamsExtensionUserIdentifierModel:
      description: A Microsoft Teams Phone user who is using a Communication Services resource to extend their Teams Phone set up.
      type: object
      required:
      - userId
      - tenantId
      - resourceId
      properties:
        userId:
          type: string
          description: The Id of the Microsoft Teams Extension user, i.e. the Entra ID object Id of the user.
        tenantId:
          type: string
          description: The tenant Id of the Microsoft Teams Extension user.
        resourceId:
          type: string
          description: The Communication Services resource Id.
        cloud:
          $ref: '#/components/schemas/CommunicationCloudEnvironmentModel'
          description: The cloud that the Microsoft Teams Extension user belongs to. By default 'public' if missing.
    TeamsExtensionUserIdentifierModel:
      $ref: '#/components/schemas/CommonTeamsExtensionUserIdentifierModel'
    CommunicationIdentifierModel:
      $ref: '#/components/schemas/CommonCommunicationIdentifierModel'
    MediaStreamingSubscriptionState:
      description: Current state of media streaming session
      enum:
      - disabled
      - inactive
      - active
      type: string
      x-ms-enum:
        name: MediaStreamingSubscriptionState
        modelAsString: true
    CommunicationErrorResponse:
      $ref: '#/components/schemas/CommonCommunicationErrorResponse'
    MicrosoftTeamsUserIdentifierModel:
      $ref: '#/components/schemas/CommonMicrosoftTeamsUserIdentifierModel'
    MicrosoftTeamsAppIdentifierModel:
      $ref: '#/components/schemas/CommonMicrosoftTeamsAppIdentifierModel'
    CommonMicrosoftTeamsUserIdentifierModel:
      description: A Microsoft Teams user.
      type: object
      required:
      - userId
      properties:
        userId:
          type: string
          description: The Id of the Microsoft Teams user. If not anonymous, this is the Entra ID object Id of the user.
        isAnonymous:
          type: boolean
          description: True if the Microsoft Teams user is anonymous. By default false if missing.
        cloud:
          $ref: '#/components/schemas/CommunicationCloudEnvironmentModel'
          description: The cloud that the Microsoft Teams user belongs to. By default 'public' if missing.
    MediaStreamingSubscription:
      description: Media streaming Subscription Object.
      type: object
      properties:
        id:
          description: Subscription Id.
          type: string
        state:
          $ref: '#/components/schemas/MediaStreamingSubscriptionState'
        subscribedContentTypes:
          description: Subscribed media streaming content types.
          type: array
          items:
            $ref: '#/components/schemas/MediaStreamingContentType'
      additionalProperties: false
    AnswerCallRequest:
      description: The request payload for answering the call.
      required:
      - callbackUri
      - incomingCallContext
      type: object
      properties:
        incomingCallContext:
          description: The context associated with the call.
          type: string
        callbackUri:
          description: The callback uri.
          type: string
        operationContext:
          description: A customer set value used to track the answering of a call.
          type: string
        callIntelligenceOptions:
          $ref: '#/components/schemas/CallIntelligenceOptions'
        answeredBy:
          $ref: '#/components/schemas/CommunicationUserIdentifierModel'
        mediaStreamingOptions:
          $ref: '#/components/schemas/MediaStreamingOptions'
        transcriptionOptions:
          $ref: '#/components/schemas/TranscriptionOptions'
      additionalProperties: false
    TranscriptionResultType:
      description: Transcription result types
      enum:
      - final
      - intermediate
      type: string
      x-ms-enum:
        name: TranscriptionResultType
        modelAsString: true
    MediaStreamingOptions:
      description: Options for media streaming.
      required:
      - audioChannelType
      - transportType
      type: object
      properties:
        transportType:
          $ref: '#/components/schemas/StreamingTransportType'
        audioChannelType:
          $ref: '#/components/schemas/MediaStreamingAudioChannelType'
      discriminator:
        propertyName: transportType
    CallIntelligenceOptions:
      description: AI options for the call.
      type: object
      properties:
        cognitiveServicesEndpoint:
          description: The identifier of the Cognitive Service resource assigned to this call.
          type: string
      additionalProperties: false
    RejectCallRequest:
      description: The request payload for rejecting the call.
      required:
      - incomingCallContext
      type: object
      properties:
        incomingCallContext:
          description: The context associated with the call.
          type: string
        callRejectReason:
          $ref: '#/components/schemas/CallRejectReason'
      additionalProperties: false
    PhoneNumberIdentifierModel:
      $ref: '#/components/schemas/CommonPhoneNumberIdentifierModel'
    CreateCallRequest:
      description: The request payload for creating the call.
      required:
      - callbackUri
      - targets
      type: object
      properties:
        targets:
          description: The targets of the call.
          type: array
          items:
            $ref: '#/components/schemas/CommunicationIdentifierModel'
        sourceCallerIdNumber:
          $ref: '#/components/schemas/PhoneNumberIdentifierModel'
        sourceDisplayName:
          description: Display name of the call if dialing out to a pstn number
          type: string
        source:
          $ref: '#/components/schemas/CommunicationUserIdentifierModel'
        operationContext:
          description: A customer set value used to track the answering of a call.
          type: string
        callbackUri:
          description: The callback URI.
          type: string
        callIntelligenceOptions:
          $ref: '#/components/schemas/CallIntelligenceOptions'
        mediaStreamingOptions:
          $ref: '#/components/schemas/MediaStreamingOptions'
        transcriptionOptions:
          $ref: '#/components/schemas/TranscriptionOptions'
        teamsAppSource:
          $ref: '#/components/schemas/MicrosoftTeamsAppIdentifierModel'
      additionalProperties: false
    CommunicationUserIdentifierModel:
      $ref: '#/components/schemas/CommonCommunicationUserIdentifierModel'
    TranscriptionSubscription:
      description: Transcription Subscription Object.
      type: object
      properties:
        id:
          description: Subscription Id.
          type: string
        state:
          $ref: '#/components/schemas/TranscriptionSubscriptionState'
        subscribedResultTypes:
          description: Subscribed transcription result types.
          type: array
          items:
            $ref: '#/components/schemas/TranscriptionResultType'
        locale:
          description: Specifies the locale used for transcription, e.g., en-CA or en-AU.
          type: string
      additionalProperties: false
  parameters:
    ApiVersionParameter:
      in: query
      name: api-version
      description: Version of the API to invoke.
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
  securitySchemes:
    Authorization:
      type: apiKey
      name: Authorization
      in: header
      description: An Azure Communication Services user access token.
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'