Example requests and responses

Example request/response formats for the Speech API.

This guide contains example requests and responses for specific endpoints and methods in the Speech API.

For complete endpoint definitions, see the Supported file types section.

POST /v0/bulk-ingest

Process raw audio files

Example requests

Request with one record

[
   {
       "call_identifier": "0696e114-b819-11ea-b3de-0242ac130004",
       "speech_file_name": "T15584.wav",
       "unit_identifier": "wm_advisor_1",
       "call_date_and_time": "2020-06-24T13:02:00-03:00",
       "engine": "Engine1", 
       "call_recording_url": "https://storage.example.com/recordings/CALL-00123.mp3",
       "vertical_model": "Call Center",
       "locale": "en-US",
       "agent_locale": "en-US",
       "apply_diarization": "No",
       "agent_channel": "0",
       "substitutions": {"appeal box":"a PO box","triple A batteries":"AAA batteries"},
       "apply_redaction": "Yes",
       "first_name": "Janelle",
       "last_name": "Perry",
       "email": "janelle.perry@mail.com",
       "phone_number": "555-555-5555",
       "connector_id": "68478g15-be61-3512-ceg2-26de2b782gg1",
       "speech_additional_info": {"queue_name":"Bank","queue_id":"12","direction":"Inbound","skill":"Bank","agent_first_name":"Gordon","agent_last_name":"Gekko"}
   }
]

Request with multiple records

[
   {
       "call_identifier": "8a98e8f7-f815-4247-90da-57ec53da6c50",
       "speech_file_name": "T15987A.wav",
       "unit_identifier": "wm_advisor_1",
       "call_date_and_time": "2020-06-24T13:02:00-03:00",
       "engine": "Engine1",
       "call_recording_url": "https://storage.example.com/recordings/CALL-00124.mp3",
       "apply_redaction": "Yes",
       "substitutions": {"sub1":"subA"},
       "locale": "en-US",
       "agent_locale": "en-US"
   },
   {
       "call_identifier": "0e04a5a9-bab2-4644-9aab-04e887213e50",
       "speech_file_name": "T15987C.wav",
       "unit_identifier": "svc_tech_103",
       "call_date_and_time": "2020-06-24T13:02:00-03:00",
       "engine": "Engine1",
       "email": "janelle.perry@mail.com",
       "phone_number": "555-555-5555"
   },
   {
       "call_identifier": "75285c45-0675-4325-95a8-867a1575f074",
       "speech_file_name": "T15987F.wav",
       "unit_identifier": "svc_tech_103",
       "call_date_and_time": "2020-06-24T13:02:00-03:00",
       "engine": "Engine2",
       "call_recording_url": "https://storage.example.com/recordings/CALL-00125.mp3",
       "vertical_model": "Call Center",
       "apply_diarization": "No",
       "apply_redaction": "Yes",
       "email": "janelle.perry@mail.com"
   }      
]

Loaded via Auto Importer

[
   {
       "call_identifier": "cb80e932-9a86-45c5-af83-4a0441daca3b",
       "speech_file_name": "T15560A.wav",
       "unit_identifier": "wm_advisor_1",
       "call_date_and_time": "2020-06-24T13:02:00-03:00",
     "engine": "Engine2",           
     "agent_channel": "1",
    "apply_redaction": "Yes",
    "apply_diarization": "No",
    "locale": "en-US",
    "substitutions": 
     {"appeal box":"a PO box","triple A batteries":"AAA batteries"},
   },
]

Connection ID profiles in Setup (loaded via Auto Importer)

[
   {
       "call_identifier": "cb80e932-9a86-45c5-af83-4a0441daca3b",
       "speech_file_name": "T15560A.wav",
       "unit_identifier": "wm_advisor_1",
       "call_date_and_time": "2020-06-24T13:02:00-03:00",
     "engine": "Engine2",           
     "agent_channel": "1",
    "apply_redaction": "Yes",
    "apply_diarization": "No",
    "locale": "en-US",
    "substitutions": 
     {"appeal box":"a PO box","triple A batteries":"AAA batteries"},
     "connector_id" : "e8274f70-981c-11ed-938e-9f223223dd53",
   },
]

Payload for connectors + metadata

Metadata added to payload via speech_additional_info mapped to fields through connector data mappings:

[
   {
       "call_identifier": "cb80e932-9a86-45c5-af83-4a0441daca3b",
       "speech_file_name": "T15560A.wav",
       "unit_identifier": "wm_advisor_1",
       "call_date_and_time": "2020-06-24T13:02:00-03:00",
     "engine": "Engine2",           
     "agent_channel": "1",
    "apply_redaction": "Yes",
    "apply_diarization": "No",
    "locale": "en-US",
    "substitutions": 
     {"appeal box":"a PO box","triple A batteries":"AAA batteries"},
     "connector_id" : "e8274f70-981c-11ed-938e-9f223223dd53",
"speech_additional_info": 
{        "RECORDINGID": "62d53717-5a2e-d006-8e18-32e92cef00",
        "RECORDINGDATE": "2023-01-19T21:26:44Z",
        "LINENAME": "SMP_LEGACY_MN_1",
        "CALLID": "2003735217",
        "CALLTYPE": "External",
        "CALLDIRECTION": "Inbound",
        "STATIONID": "MN0136",
        "LOCALNAME": "Dacy Hanson",
        "ASSIGNEDWORKGROUP": 
        "STARTTIME": "2023-01-06T21:26:44Z",
        "REMOTENAME": "GEORGE TWIGG",
        "ENDTIME": "2023-01-06T21:28:59.23Z",
        "CALLDURATIONSECONDS": "180",
        "DNIS": "2172389143",
        "SKILLSET": "CS_RES_NNE_FIBER",
        "DISCOTYPE": "Remote Disconnect",
   },
]

Tip: While engine, vertical model, locales, diarization, redactions, substitutions and other values can be defined using Connector settings, currently, there's no merge mechanism between the Speech API payload and connector settings, so Experience Cloud will use the the values defined in the Speech API payload if present.

Example responses

200 OK — Job Accepted

{
   "job_id": "713c865e-0d1f-43a0-9998-5fada657850b",
   "status": "ACCEPTED"
}

200 OK — Partially Accepted

When one or more tasks in the batch were rejected, the details array contains per-task results.

{
   "job_id": "377533aa-d342-4a6a-8af3-724a91587bb1",
   "status": "PARTIALLY_ACCEPTED",
   "details": [
       {
           "call_identifier": "cb80e932-9a86-45c5-af83-4a0441daca3b",
           "speech_file_name": "T15560A.wav",
           "status": "ACCEPTED"
       },
       {
           "call_identifier": "1a87c03c-d148-4b70-b745-eeca94b1cc0b",
           "speech_file_name": "T15560E.wav",
           "status": "REJECTED",
           "error_message": "File T15560E.wav does not exist"
       }
   ]
}

200 OK — All Rejected

{
   "job_id": "68a49d2d-71ba-4dda-a27b-85d17039d2cc",
   "status": "REJECTED",
   "details": [
       {
           "call_identifier": "ab8c2994-9359-4269-ba4f-cd4c0d53635e",
           "speech_file_name": "T15525.wav",
           "status": "REJECTED",
           "error_message": "File T15525.wav does not exist"
       }
   ]
}

Note: The service does not validate if duplicate parameters are sent in the body of the request, or across several requests. If the same request is sent more than once, all will be accepted.

400 Bad Request — Validation Error

This specific example demonstrates a validation error due to a missing connector_id.

{
   "job_id": "7b721583-cb4f-48bb-8861-426ed0cf8719",
   "status": "REJECTED",
   "details": [
       {
           "call_identifier": ""12042024-454004002450966-record-cv20240413001",
           "speech_file_name": "Audio/454004002450966.wav",
           "status": "REJECTED",
           "error_message": "Send failed; nested exception is org.apache.kafka.common.errors.SaslAuthenticationException: {\"status\":\"invalid_token\"}"
       }
   ]
}

POST /v1/bulk-ingest-transcription

Upload complete transcripts

Example request

curl --location 'https://<instance>.medallia.com/speech/v1/bulk-ingest-transcription' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data '[
  {
    "call_identifier": "CALL-00123",
    "call_date_and_time": "2024-03-15T09:30:00-05:00",
    "speech_transcription_file_name": "transcripts/2024/03/CALL-00123.json",
    "speech_transcription_asr_vendor": "deepgram",
    "speech_file_name": "audio/2024/03/CALL-00123.mp3",
    "unit_identifier": "support-team-west",
    "call_recording_url": "https://storage.example.com/recordings/CALL-00123.mp3",
    "locale": "en-GB",
    "agent_locale": "en-GB"
  }
]'

Example responses

200 OK — Job Accepted

{
  "job_id": "550z0400-e29b-79d4-a716-446655440200",
  "status": "ACCEPTED"
}

200 OK — Partially Accepted

When one or more tasks in the batch were rejected, the details array contains per-task results.

{
  "job_id": "550e9000-e29b-41s4-a716-446655440000",
  "status": "PARTIALLY_ACCEPTED",
  "details": [
    {
      "call_identifier": "CALL-00123",
      "status": "ACCEPTED"
    },
    {
      "call_identifier": "CALL-00124",
      "status": "REJECTED",
      "error_message": "File not found: transcripts/CALL-00124.json"
    }
  ]
}

200 OK — All Rejected

{
  "job_id": "550e0900-e29b-41d4-c916-446655440000",
  "status": "REJECTED",
  "details": [
    {
      "call_identifier": "CALL-00123",
      "status": "REJECTED",
      "error_message": "File not found: transcripts/CALL-00123.json"
    }
  ]
}

400 Bad Request — Validation Error

{
  "error_type": "invalid_input",
  "message": "Field 'speech_transcription_file_name' is mandatory, task position: 0"
}

{
  "error_type": "invalid_input",
  "message": "Field 'connector_id' is not allowed for this API. Please remove it from the request and resend, task position: 0"
}

{
  "error_type": "invalid_input",
  "message": "feature flag not enabled for Bulk Transcription - for tenant acme-corp"
}