Speech-to-text API

The Speech-to-text API triggers audio-file processing in Medallia Speech for the purpose of translating speech to text.

Experience Cloud provides speech-to-text translation.

Note: To use this API, customers must have already transferred the call recording files to an intermediary storage system between their network and the Experience Cloud instance. Medallia recommends that you use a Medallia Media File Transfer storage bucket for this purpose.

Audio files must be uploaded before submitting jobs using of a list of file names and metadata.

Once you have submitted a job, use this API to list all jobs, get the details of a specific job, discard one or multiple jobs, get the configuration of one or more jobs.

Restrictions and limits

The API supports bulk uploads and can handle up to 1,000 records per request. Additionally, there is a limit to the number of API calls an app can make within a given time period:

Up to 13,000 requests per minute
Up to 325,000 requests per 24-hour period

Important: The timeout for a request is 180 seconds. The API Gateway discards any request that takes longer than that. However, the processing may take longer than 180 seconds: consider checking in reports if the files have been processed before sending another request.

Authentication and authorization

Authentication identifies who is making an API request, and authorization identifies what data the requester may access. OAuth is an industry standard for authorizing limited access to services and data. Applications must obtain a secure token that identifies the application that makes the request. The token is passed to the resource server (API server) with each API request. For more information, see Authenticate APIs with OAuth.

To use the Speech-to-text API:

The application must have an account.
The account's role must have permission to access the API.
API access is authenticated with OAuth. To use OAuth, the application must first obtain an OAuth access token, by requesting one for the application's client ID and secret. For detailed information, see Authenticating APIs with OAuth.

Request/response formats

Requests sent to Medallia Speech API are HTTP POST protocol. The information in the request includes:

A required Content-Type header field describing the content. The acceptable type is: application/json for JSON.

An optional Accept field tells the Speech API how to format the response. The acceptable type is: application/json for JSON.


Parameter	Description	Required	Values
Bearer	Access token	Required	See Authentication and authorization.
Content-Type	Format of request data	Required	application/json.
Accept	Format of response data	Optional	application/json.

No other header fields are expected.
The request URL:
- Always use the base instance for the company's Medallia installation.

Submit a job

Use this endpoint to submit a job to process audio file to translate speech to text.

Requests are HTTP POST protocol. The API accesses resources from a URL that follows this format to create a request to submit a speech-to-text job.

https://<api-host>/<service>/<api-version>/<endpoint>

Where:

api-host is the server for your company's Experience Cloud instance. For detailed information about identifying the host, see API hosts.
service is speech.
api-version is v1.
endpoint is speech-to-text-job.

POST body

This API is used to provide context for voice signals by sending metadata associated with the signals (audio files) in the body of the HTTP POST request.

Note: The following table lists the parameters that can be sent for each call record. Medallia recommends that you include these additional metadata values in your API request to ensure your audio is being transcribed more precisely to meet your business needs.

The request body should be encoded in a JSON array of objects, with each object containing keys and values that match the parameters shown in the following table:


Parameter		Description	Type	Requited
description		Places a new Speech file list for its processing into text.	File processing data object	Required
	call_identifier	A unique record identifier, encoded as a JSON string.	String	Required
	speech_file_name
	unit_identifier

Response

When the job is successfully created, the response returns a unique UUID value. Use it to get the results of the job at a later point when the job has transitioned to the COMPLETED state. The response is a JSON object that includes:


Element		Description	Type	Notes
job_id
status
details
	call_identifier
	speech_file_name
	status
	error_message

Sample request

POST https://instance.apis.medallia.com/speech/v1/speech-to-text-job
Content-Type: application/json

[
  {
    "call_identifier": "string",
    "speech_file_name": "string",
    "unit_identifier": "string",
    "call_date_and_time": "2025-04-10T00:05:00Z",
    "call_recording_url": "string",
    "vertical_model": "Call Center",
    "locale": "string",
    "agent_locale": "string",
    "apply_diarization": "Yes",
    "agent_channel": "0",
    "substitutions": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "apply_redaction": "Yes",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "phone_number": "string",
    "connection_id": "string",
    "engine": "Engine 1",
    "connector_id": "string",
    "historical": true,
    "lid": true,
    "language_options": [
      "string"
    ],
    "emotion": true,
    "scrub_config": "string",
    "e_program_id": "string",
    "speech_additional_info": {
      "additionalProp1": {},
      "additionalProp2": {},
      "additionalProp3": {}
    }
  }
]

Sample response

{
  "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "ACCEPTED",
  "details": [
    {
      "call_identifier": "string",
      "speech_file_name": "string",
      "status": "ACCEPTED",
      "error_message": "string"
    }
  ]
}

List all jobs

Use this endpoint to return all available jobs in the system which are currently scheduled.

Requests are HTTP GET protocol. The API accesses resources from a URL that follows this format to create a request to list all speech-to-text jobs.

https://<api-host>/<service>/<api-version>/<endpoint>

Where:

api-host is the server for your company's Experience Cloud instance. For detailed information about identifying the host, see API hosts.
service is speech.
api-version is v1.
endpoint is speech-to-text-jobs.

Make query requests with the query parameters shown in the table below. The API supports additional parameters to filter the matching speech-to-text jobs. Each filter specified restricts the amount of data queried and returned (logical AND, not OR).


Parameter	Description	Type	Required	Notes
days	Number of days to filter jobs (e.g., 7 days).	Integer	Optional	The default value is 7.
survey_id	UUID if the survey.	String	Optional	—
call_id	A unique record identifier, encoded as a JSON string.	String	Optional	—
page	Page number.	Integer	Optional	The default value is 0.
size	Size of the return list.	String	Optional	The default value is 50.
connector_id	Unique identifier of a specific Speech Connector API as configured in Medallia Admin Suite.	String	Optional	—

Response

A valid success response will return the original query parameters and the status of the job.


Element
content
	content
		job_id
		survey_id
		call_id
		configuration_version
		status
		error_status
		error_message
		start_time
		completed_time
		engine
		locale
		historical
		connector_id
		retries
	pageable
		page
		size
	pagination_metadata
		total_elements
		total_pages

Sample request

GET https://instance.apis.medallia.com/speech/v1/speech-to-text-jobs
Content-Type: application/json

Sample response

{
  "content": [
    {
      "content": [
        {
          "job_id": "string",
          "survey_id": "string",
          "call_id": "string",
          "configuration_version": "string",
          "status": "string",
          "error_status": "string",
          "error_message": "string",
          "start_time": "string",
          "completed_time": "string",
          "engine": "string",
          "locale": "string",
          "historical": "string",
          "connector_id": "string",
          "retries": 0
        }
      ],
      "pageable": {
        "page": 0,
        "size": 0
      },
      "pagination_metadata": {
        "total_elements": 0,
        "total_pages": 0
      }
    }
  ]
}

Get job details

Use this endpoint to get details of a job in the system which is currently in the queue for processing.

Requests are HTTP GET protocol. The API accesses resources from a URL that follows this format to create a request to get the details of a speech-to-text job.

https://<api-host>/<service>/<api-version>/<endpoint>/<jobId>

Where:

api-host is the server for your company's Experience Cloud instance. For detailed information about identifying the host, see API hosts.
service is speech.
api-version is v1.
endpoint is speech-to-text-jobs.
jobId identifies the speech job whose status you are querying.

Response

A valid success response will return the original query parameters and the status of the job.


Element	Description	Type	Notes
job_id
survey_id
call_id	Unique record identifier. May be the Universal Call ID (UCID).
configuration_version
status
error_status
error_message
start_time
completed_time
engine
locale
historical
connector_id
retries

Sample request

GET https://instance.apis.medallia.com/speech/v1/speech-to-text-jobs/84c18904-b2a2-445b-88c2-efe8ccb0cab9
Content-Type: application/json

Sample response

{
  "job_id": "84c18904-b2a2-445b-88c2-efe8ccb0cab9",
  "survey_id": "string",
  "call_id": "string",
  "configuration_version": "string",
  "status": "string",
  "error_status": "string",
  "error_message": "string",
  "start_time": "string",
  "completed_time": "string",
  "engine": "string",
  "locale": "string",
  "historical": "string",
  "connector_id": "string",
  "retries": 0
}

Discard a job

Use this endpoint to remove a job from the queue for processing.

Requests are HTTP POST protocol. The API accesses resources from a URL that follows this format to create a request to discard a speech-to-text job.

https://<api-host>/<service>/<api-version>/<endpoint>/<jobId>/discard-job

Where:

api-host is the server for your company's Experience Cloud instance. For detailed information about identifying the host, see API hosts.
service is speech.
api-version is v1.
endpoint is speech-to-text-jobs.
jobId identifies the speech job you need to discard.

Response

A valid success response will have a HTTP 200 code, which means the job was successfully discarded.

An error response will have a HTTP 404 code, which means the job could not be found.

Sample request

GET https://instance.apis.medallia.com/speech/v1/speech-to-text-jobs/84c18904-b2a2-445b-88c2-efe8ccb0cab9/discard-job
Content-Type: application/json

Get job configuration

Use this endpoint to get the configuration of a job in the system which is currently in the queue for processing.

Requests are HTTP GET protocol. The API accesses resources from a URL that follows this format to create a request to get the details of a speech-to-text job.

https://<api-host>/<service>/<api-version>/<endpoint>/<versionId>

Where:

api-host is the server for your company's Experience Cloud instance. For detailed information about identifying the host, see API hosts.
service is speech.
api-version is v1.
endpoint is speech-to-text-jobs-configurations.
versionId identifies the speech job whose configuration you are querying.

Response

A valid success response will return the configuration of the job.


Element		Description	Type	Notes
pii_enabled
substitutions
channel_configs
	default
	overrides
diarization_enabled
vertical
custom_vocab
created_at
last_used_at

Sample request

GET https://instance.apis.medallia.com/speech/v1/speech-to-text-jobs-configurations/84c18904-b2a2-445b-88c2-efe8ccb0cab9
Content-Type: application/json

Sample response

{
  "pii_enabled": true,
  "substitutions": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "channel_configs": {
    "default": "string",
    "overrides": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  },
  "diarization_enabled": true,
  "vertical": "string",
  "custom_vocab": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  },
  "created_at": "string",
  "last_used_at": "string"
}

List all job configurations

Use this endpoint to get the configuration of all jobs in the system which are currently in the queue for processing.

Requests are HTTP GET protocol. The API accesses resources from a URL that follows this format to create a request to get the details of a speech-to-text job.

https://<api-host>/<service>/<api-version>/<endpoint>/

Where:

api-host is the server for your company's Experience Cloud instance. For detailed information about identifying the host, see API hosts.
service is speech.
api-version is v1.
endpoint is speech-to-text-jobs-configurations.

Response

A valid success response will return the configuration of the jobs.


Element		Description	Type	Notes
pii_enabled
substitutions
channel_configs
	default
	overrides
diarization_enabled
vertical
custom_vocab
created_at
last_used_at

Sample request

GET https://instance.apis.medallia.com/speech/v1/speech-to-text-jobs-configurations/
Content-Type: application/json

Sample response

{
  "pii_enabled": true,
  "substitutions": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "channel_configs": {
    "default": "string",
    "overrides": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  },
  "diarization_enabled": true,
  "vertical": "string",
  "custom_vocab": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  },
  "created_at": "string",
  "last_used_at": "string"
}

Discard multiple jobs

Use this endpoint to remove multiple jobs from the queue based on the call identifier.

Requests are HTTP POST protocol. The API accesses resources from a URL that follows this format to create a request to discard multiple speech-to-text jobs.

https://<api-host>/<service>/<api-version>/<endpoint>/discard-jobs

Where:

api-host is the server for your company's Experience Cloud instance. For detailed information about identifying the host, see API hosts.
service is speech.
api-version is v1.
endpoint is speech-to-text-jobs.

POST body


Parameter	Description	Type	Required	Notes
call-ids	An array of call identifiers associated with the jobs to mark as discarded.	Job discarding data object	Required	—

Response

A valid success response will have a HTTP 200 code, which means the jobs were successfully discarded.

An error response will have a HTTP 404 code, which means the jobs could not be found.

Sample request

POST https://instance.apis.medallia.com/speech/v1/speech-to-text-jobs/discard-jobs
Content-Type: application/json

[
  "e7cd7a2b-fd51-4028-99db-4bc13aa85ffd",
  "75285c45-0675-4325-95a8-867a1575f074",
  "504b4661-30f5-46f3-b833-c008d5c9b8c6"
]