Submit an Interaction
Declare an Audio Interaction

﻿//  Overview 
The first step in processing any interaction is to declare the interaction.
When the POST request successfully executes, an HTTP status is returned to indicate the request was successful, along with a JSON response containing the interactionIdentifier. 
Sample API Response
{
    "interactionIdentifier":  "2ebaffd6-7a4b-4bcf-a169-678af0705779"
} 
{
    "interactionIdentifier":  "2ebaffd6-7a4b-4bcf-a169-678af0705779"
} 
﻿
It is important you store the interactionIdentifier as it will serve as a required parameter for all other ElevateAI endpoints, enabling you to POST, GET, and/or DELETE information associated with this interaction.
If an error occurs when requesting to declare the interaction, a standard HTTP response code is retuned to indicate the request was unsuccessful, along with a JSON response containing additional details to assist in ﻿troubleshooting﻿. 
﻿
All interactions successfully declared will count towards your monthly ﻿request quota﻿, irrespective of file upload status or processing outcome. 
Only interactions successfully processed are eligible for billing. Once declared, you can confirm the ﻿processing status﻿ of the interaction as well as track impacts to ﻿usage﻿ and ﻿spend﻿.
﻿Echo﻿
Introducing Echo, our most accurate transcription model ever!  
Echo delivers a significant leap in accuracy, outperforming our previous CX-focused model by 40%, ensuring superior transcription quality across every use case.
To take advantage of the Echo model, add the body parameter "model" to your POST declare and set the value to "echo".  
NOTE: Currently the Echo model does not diarize between speakers, perform redaction or process for CX-AI.  Future releases will move Echo towards feature parity with the CX model.
﻿
﻿//  Request Parameters & Code Examples
POST
Request
Header Parameters
X-API-Token
String
required
Valid API key associated with your account for authentication and usage tracking
Content-Type
String
required
Will be 'application/JSON'
Body Parameters
type
String
required
Type of interaction to be processed, will be
"audio"
languageTag
String
optional
Specifies the language to use when processing the audio.  NOTE: For the Echo model, use "auto" to automatically determine the language (over 50 supported). For the CX model, the options are:
"en-us" (for North American English), 
"en" (for International English),  
"es-419" (for North American Spanish),
"pt-br" for Brazilian Portuguese or
"ja" for Japanese.
Omitting this parameter will default to "auto" for model echo and "en-us" for model cx.
vertical
String
optional
Vertical associated with interaction, will be
"default"
model
String
optional
Defines the transcription model to be used.  Available options are "cx" and "echo".  Default is "cx".
audioTranscriptionMode
String
optional
NOTE: Effective v1.11 on February 29, 2024 all declared interactions will be processed with "highAccuracy".  

This previously required parameter has been depricated and is no longer required and any value will be ignored.
originalFileName
String
optional
The filename of the original file for this interaction
externalIdentifier
String
optional
Any external identifier that the user would like associated with this interaction
downloadUri
String
optional
The URL of your audio file
Important: Do not include the downloadUri parameter if you wish to upload a local audio file; an empty string will cause the download to fail
downloadAuth
Object
optional
This optional body parameter can be used when the downloadUri is specified and the download source requires authentication.  NOTE: If an expiring token is used for authentication, make sure it has a reasonable amount of time left prior to expiration.
includeAiResults
Boolean
optional
NOTE: Effective v1.11 on February 29, 2024 all declared interactions will be processed with includeAiResults set to 'true'.
metadata
String
optional
JSON payload containing the metadata for this audio file.  Must only be used if the account has Explore enabled.  If not, specifying this element will cause a response of 400 Bad Request.
Curl
Node.js
JS
Python
Ruby
C#
PHP
curl --location --request POST 'https://api.elevateai.com/v1/interactions' \
--header 'Content-Type: application/json' \
--header 'X-API-Token: {Your API Token}' \
--data-raw '{
    "type": "audio",
    "languageTag": "auto",
    "vertical": "default",
    "model": "echo",
    "audioTranscriptionMode": "highAccuracy",
    "originalFileName": "ABC00012.wav",
    "includeAiResults": true,
    "metadata": "{Your JSON metada payload}"
}'
curl --location --request POST 'https://api.elevateai.com/v1/interactions' \
--header 'Content-Type: application/json' \
--header 'X-API-Token: {Your API Token}' \
--data-raw '{
    "type": "audio",
    "languageTag": "auto",
    "vertical": "default",
    "model": "echo",
    "audioTranscriptionMode": "highAccuracy",
    "originalFileName": "ABC00012.wav",
    "includeAiResults": true,
    "metadata": "{Your JSON metada payload}"
}'
Responses
201
400
401
429
{
  "string"
}
{
  "string"
}
﻿
Details on transcription and CX AI features supported by language can be found on the ﻿overview page﻿.
﻿
﻿//  Submitting an Audio File for Processing
Download URI
Providing access to audio files via the downloadUri parameter is highly recommended for fastest ﻿processing times﻿. 
When using the Download URI option, authentication parameters can be included in the Declare for source systems which require it.  See Body Parameters above.
Local File
If the downloadUri parameter is not included when declaring the interaction, the audio should be ﻿uploaded to the API directly﻿ for processing. 
﻿//  Submitting metadata
Metadata must only be submitted with an API-Token for an account which has Explore enabled.  Use under other circumstances will cause the Declare to fail, and a response of 400 Bad Request.
For details on the types and formatting of metadata, please see Metadata.
ElevateAI Postman Collection
Metadata
Declare an Audio Interaction

﻿// Overview

﻿Echo﻿

﻿// Request Parameters & Code Examples

﻿// Submitting an Audio File for Processing

Download URI

Local File

﻿// Submitting metadata

// Overview

Echo

// Request Parameters & Code Examples

// Submitting an Audio File for Processing

// Submitting metadata
