Consents - Create

Service:: Azure AI Services

API Version:: 2026-01-01

Creates a new voice talent consent with the provided audio URL.

PUT {endpoint}/customvoice/consents/{id}?api-version=2026-01-01

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string (uri)	Supported Cognitive Services endpoints (protocol and hostname, for example: https://eastus.api.cognitive.microsoft.com).
id	path	True	string minLength: 3 maxLength: 64 pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$	Resource id
api-version	query	True	string minLength: 1	The API version to use for this operation.

Request Header

Name	Required	Type	Description
Operation-Id		string minLength: 3 maxLength: 64 pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$	ID of the status monitor for the operation. If the Operation-Id header matches an existing operation and the request is not identical to the prior request, it will fail with a 400 Bad Request.

Request Body

Name	Required	Type	Description
companyName	True	string minLength: 1	Company name. Must match the company name in the consent audio file.
locale	True	string	The locale of this consent. Locale code follows BCP-47. You can find the text to speech locale list here https://learn.microsoft.com/azure/ai-services/speech-service/language-support?tabs=tts.
projectId	True	string minLength: 3 maxLength: 64 pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$	Resource id
voiceTalentName	True	string minLength: 1	Voice talent name. Must match the voice talent name in the consent audio file.
audioUrl		string (uri)	The public accessible URL of the consent audio file. It's recommended to be an Azure blob URL with SAS. This property is only available in request.
description		string	Description of consent.
displayName		string minLength: 1	Name of consent.
properties		ConsentProperties	Consent properties
status		Status	Status of a resource.

Responses

Name	Type	Description
200 OK	Consent	The request has succeeded. Headers Operation-Location: string
201 Created	Consent	The request has succeeded and a new resource has been created as a result. Headers Operation-Location: string
Other Status Codes	Azure.Core.Foundations.ErrorResponse	An unexpected error response. Headers x-ms-error-code: string

Name

Type

Description

200 OK

Consent

The request has succeeded.

Headers

Operation-Location: string

201 Created

Consent

The request has succeeded and a new resource has been created as a result.

Headers

Operation-Location: string

Other Status Codes

Azure.Core.Foundations.ErrorResponse

An unexpected error response.

Headers

x-ms-error-code: string

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

OAuth2Auth

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
https://cognitiveservices.azure.com/.default

Examples

Sample request

HTTP

PUT {endpoint}/customvoice/consents/Jessica?api-version=2026-01-01


{
  "description": "Consent for Jessica voice",
  "audioUrl": "https://contoso.blob.core.windows.net/public/jessica-consent.wav?mySasToken",
  "companyName": "Contoso",
  "locale": "en-US",
  "projectId": "Jessica",
  "voiceTalentName": "Jessica Smith"
}

Sample response

Status code:: 200

Operation-Location: https://eastus.api.cognitive.microsoft.com/customvoice/operations/070f7986-ef17-41d0-ba2b-907f0f28e314?api-version=2026-01-01

{
  "description": "Consent for Jessica voice",
  "companyName": "Contoso",
  "createdDateTime": "2023-04-01T05:30:00.000Z",
  "id": "Jessica",
  "lastActionDateTime": "2023-04-02T10:15:30.000Z",
  "locale": "en-US",
  "projectId": "Jessica",
  "status": "NotStarted",
  "voiceTalentName": "Jessica Smith"
}

Status code:: 201

Operation-Location: https://eastus.api.cognitive.microsoft.com/customvoice/operations/070f7986-ef17-41d0-ba2b-907f0f28e314?api-version=2026-01-01

{
  "description": "Consent for Jessica voice",
  "companyName": "Contoso",
  "createdDateTime": "2023-04-01T05:30:00.000Z",
  "id": "Jessica",
  "lastActionDateTime": "2023-04-02T10:15:30.000Z",
  "locale": "en-US",
  "projectId": "Jessica",
  "status": "NotStarted",
  "voiceTalentName": "Jessica Smith"
}

Definitions

Name	Description
Azure.Core.Foundations.Error	The error object.
Azure.Core.Foundations.ErrorResponse	A response containing error details.
Azure.Core.Foundations.InnerError	An object containing more specific information about the error. As per Azure REST API guidelines - https://aka.ms/AzureRestApiGuidelines#handling-errors.
Consent	Consent object
ConsentFailureReason	Consent creation failure reason
ConsentProperties	Consent properties
Status	Status of a resource.

Azure.Core.Foundations.Error

Object

The error object.

Name	Type	Description
code	string	One of a server-defined set of error codes.
details	Azure.Core.Foundations.Error[]	An array of details about specific errors that led to this reported error.
innererror	Azure.Core.Foundations.InnerError	An object containing more specific information than the current object about the error.
message	string	A human-readable representation of the error.
target	string	The target of the error.

Azure.Core.Foundations.ErrorResponse

Object

A response containing error details.

Name	Type	Description
error	Azure.Core.Foundations.Error	The error object.

Azure.Core.Foundations.InnerError

Object

An object containing more specific information about the error. As per Azure REST API guidelines - https://aka.ms/AzureRestApiGuidelines#handling-errors.

Name	Type	Description
code	string	One of a server-defined set of error codes.
innererror	Azure.Core.Foundations.InnerError	Inner error.

Object

Consent object

Name	Type	Description
audioUrl	string (uri)	The public accessible URL of the consent audio file. It's recommended to be an Azure blob URL with SAS. This property is only available in request.
companyName	string minLength: 1	Company name. Must match the company name in the consent audio file.
createdDateTime	string (date-time)	The timestamp when the object was created. The timestamp is encoded as ISO 8601 date and time format ("YYYY-MM-DDThh:mm:ssZ", see https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations)
description	string	Description of consent.
displayName	string minLength: 1	Name of consent.
id	string minLength: 3 maxLength: 64 pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$	Resource id
lastActionDateTime	string (date-time)	The timestamp when the current status was entered. The timestamp is encoded as ISO 8601 date and time format ("YYYY-MM-DDThh:mm:ssZ", see https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations).
locale	string	The locale of this consent. Locale code follows BCP-47. You can find the text to speech locale list here https://learn.microsoft.com/azure/ai-services/speech-service/language-support?tabs=tts.
projectId	string minLength: 3 maxLength: 64 pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$	Resource id
properties	ConsentProperties	Consent properties
status	Status	Status of a resource.
voiceTalentName	string minLength: 1	Voice talent name. Must match the voice talent name in the consent audio file.

ConsentFailureReason

Enumeration

Consent creation failure reason

Value	Description
AudioAndScriptNotMatch	The consent audio mismatch with verbal statement. Please check verbal-statement.
Internal	Custom Voice Service error.

ConsentProperties

Object

Consent properties

Name	Type	Description
failureReason	ConsentFailureReason	Consent creation failure reason

Status

Enumeration

Status of a resource.

Value	Description
NotStarted	NotStarted
Running	Running
Succeeded	Succeeded
Failed	Failed
Disabling	Disabling
Disabled	Disabled

Consents - Create

URI Parameters

Request Header

Request Body

Responses

Security

Ocp-Apim-Subscription-Key

OAuth2Auth

Scopes

Examples

Create a consent

Sample request

Sample response

Definitions

Azure.Core.Foundations.Error

Azure.Core.Foundations.ErrorResponse

Azure.Core.Foundations.InnerError

Consent

ConsentFailureReason

ConsentProperties

Status