---
title: "Start recording the call."
method: POST
path: "/calling/recordings"
tags: ["Recording"]
---

# Start recording the call.

`POST /calling/recordings`

## Request

- Base URL: `https://contoso.communication.azure.com`
- URL: `https://contoso.communication.azure.com/calling/recordings`
- Auth: API key in header `Authorization`

## Query parameters

- `api-version` string, required

## Headers

- `Repeatability-Request-ID` string, uuid
- `Repeatability-First-Sent` string, date-time-rfc1123

## Request body

- StartCallRecordingRequest: The request payload start for call recording operation with call locator.
  - `callLocator` CallLocator: The locator used for joining or taking action on a call
    - `groupCallId` string: The group call id
    - `serverCallId` string: The server call id.
    - `roomId` string: The Acs room id. (Not supported for Start Recording)
    - `kind` 'groupCallLocator' | 'serverCallLocator' | 'roomCallLocator': The call locator kind
  - `callConnectionId` string: The call connection Id. (Only one of callLocator or callConnectionId to be used)
  - `recordingStateCallbackUri` string: The uri to send notifications to.
  - `recordingContentType` 'audio' | 'audioVideo': The content type of call recording.
  - `recordingChannelType` 'mixed' | 'unmixed': Defines the channel type of call recording.
  - `recordingFormatType` 'wav' | 'mp3' | 'mp4': Defines the format type of call recording.
  - `audioChannelParticipantOrdering` CommunicationIdentifierModel[]: The sequential order in which audio channels are assigned to participants in the unmixed recording. When 'recordingChannelType' is set to 'unmixed' and `audioChannelParticipantOrdering is not specified, the audio channel to participant mapping will be automatically assigned based on the order in which participant first audio was detected. Channel to participant mapping details can be found in the metadata of the recording.
    - `kind` 'unknown' | 'communicationUser' | 'phoneNumber' | 'microsoftTeamsUser' | 'microsoftTeamsApp' | 'teamsExtensionUser': The identifier kind, for example 'communicationUser' or 'phoneNumber'.
    - `rawId` string: Raw Id of the identifier. Optional in requests, required in responses.
    - `communicationUser` CommunicationUserIdentifierModel2: A user that got created with an Azure Communication Services resource.
      - `id` string, required: The Id of the communication user.
    - `phoneNumber` PhoneNumberIdentifierModel2: A phone number.
      - `value` string, required: The phone number, usually in E.164 format.
      - `isAnonymous` boolean: 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` string: The asserted Id of the phone number. An asserted Id gets generated when the same phone number joins the same call more than once.
    - `microsoftTeamsUser` MicrosoftTeamsUserIdentifierModel2: A Microsoft Teams user.
      - `userId` string, required: The Id of the Microsoft Teams user. If not anonymous, this is the Entra ID object Id of the user.
      - `isAnonymous` boolean: True if the Microsoft Teams user is anonymous. By default false if missing.
      - `cloud` 'public' | 'dod' | 'gcch': The cloud that the identifier belongs to.
    - `microsoftTeamsApp` MicrosoftTeamsAppIdentifierModel2: A Microsoft Teams application.
      - `appId` string, required: The Id of the Microsoft Teams application.
      - `cloud` 'public' | 'dod' | 'gcch': The cloud that the identifier belongs to.
    - `teamsExtensionUser` TeamsExtensionUserIdentifierModel2: A Microsoft Teams Phone user who is using a Communication Services resource to extend their Teams Phone set up.
      - `userId` string, required: The Id of the Microsoft Teams Extension user, i.e. the Entra ID object Id of the user.
      - `tenantId` string, required: The tenant Id of the Microsoft Teams Extension user.
      - `resourceId` string, required: The Communication Services resource Id.
      - `cloud` 'public' | 'dod' | 'gcch': The cloud that the identifier belongs to.
  - `channelAffinity` ChannelAffinity[]: The channel affinity of call recording When 'recordingChannelType' is set to 'unmixed', if channelAffinity is not specified, 'channel' will be automatically assigned. Channel-Participant mapping details can be found in the metadata of the recording. ///
    - `channel` integer: Channel number to which bitstream from a particular participant will be written.
    - `participant` CommunicationIdentifierModel, required: 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.
      - `kind` 'unknown' | 'communicationUser' | 'phoneNumber' | 'microsoftTeamsUser' | 'microsoftTeamsApp' | 'teamsExtensionUser': The identifier kind, for example 'communicationUser' or 'phoneNumber'.
      - `rawId` string: Raw Id of the identifier. Optional in requests, required in responses.
      - `communicationUser` CommunicationUserIdentifierModel2: A user that got created with an Azure Communication Services resource.
        - `id` string, required: The Id of the communication user.
      - `phoneNumber` PhoneNumberIdentifierModel2: A phone number.
        - `value` string, required: The phone number, usually in E.164 format.
        - `isAnonymous` boolean: 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` string: The asserted Id of the phone number. An asserted Id gets generated when the same phone number joins the same call more than once.
      - `microsoftTeamsUser` MicrosoftTeamsUserIdentifierModel2: A Microsoft Teams user.
        - `userId` string, required: The Id of the Microsoft Teams user. If not anonymous, this is the Entra ID object Id of the user.
        - `isAnonymous` boolean: True if the Microsoft Teams user is anonymous. By default false if missing.
        - `cloud` 'public' | 'dod' | 'gcch': The cloud that the identifier belongs to.
      - `microsoftTeamsApp` MicrosoftTeamsAppIdentifierModel2: A Microsoft Teams application.
        - `appId` string, required: The Id of the Microsoft Teams application.
        - `cloud` 'public' | 'dod' | 'gcch': The cloud that the identifier belongs to.
      - `teamsExtensionUser` TeamsExtensionUserIdentifierModel2: A Microsoft Teams Phone user who is using a Communication Services resource to extend their Teams Phone set up.
        - `userId` string, required: The Id of the Microsoft Teams Extension user, i.e. the Entra ID object Id of the user.
        - `tenantId` string, required: The tenant Id of the Microsoft Teams Extension user.
        - `resourceId` string, required: The Communication Services resource Id.
        - `cloud` 'public' | 'dod' | 'gcch': The cloud that the identifier belongs to.
  - `pauseOnStart` boolean: When set to true will start recording in Pause mode, which can be resumed.
  - `externalStorage` ExternalStorage
    - `recordingStorageKind` 'azureCommunicationServices' | 'azureBlobStorage', required: Defines the kind of external storage
    - `recordingDestinationContainerUrl` string, uri: Uri of a container or a location within a container

## Response `200`

Returns the start call recording response.

- RecordingStateResponse
  - `recordingId` string
  - `recordingState` 'active' | 'inactive'
  - `recordingKind` 'azureCommunicationServices' | 'teams' | 'teamsCompliance'

## Other responses

- `202`: The service has accepted the StartCallRecording request and will begin processing it. You will receive either a StartRecordingFailed event or RecordingStateChanged event at your specified callback URI to update you on the status of the request.
- `default`: Error

## Changes

- **2026-07-13** (2022-04-07-preview) `3595afe2f41f`: 1 info
  - added the success response with the status `202`
- **2026-07-13** (2022-04-07-preview) `a735f0157334`: 1 info
  - added the success response with the status `202`
- **2026-07-13** (2022-04-07-preview) `716f7aaa6e55`: 1 breaking
  - removed the success response with the status `202`
- **2026-07-13** (2022-04-07-preview) `d4d02a642780`: 3 info
  - api operation id `Content_Recording` removed and replaced with `CallRecording_StartRecording`
  - api tag `Recording` added
  - api tag `Content_Recording` removed

[Operation history](https://skmtc.dev/azure/apis/communication-callautomation/changes/calling/recordings/post.md)

---

[API](https://skmtc.dev/azure/apis/communication-callautomation.md) - [All operations](https://skmtc.dev/azure/apis/communication-callautomation/llms.txt) - [OpenAPI document](https://skmtc.dev/azure/apis/communication-callautomation/revisions/956a07c67cf4?raw)
