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﻿.
﻿
﻿//  Request Parameters & Code Examples
POST
Params
Header Parameters
X-API-Token
required
String
Valid API key associated with your account for authentication and usage tracking
Content-Type
required
String
Will be 'application/JSON'
Body Parameters
type
required
String
Type of interaction to be processed, will be
"audio"
languageTag
required
String
Primary language of the audio file, will be:
"en-us" (for North American English), 
"en" (for International English), or 
"es-419" (for North American Spanish)
"pt-br" for Brazillian Portuguese 
vertical
required
String
Vertical associated with interaction, will be
"default"
audioTranscriptionMode
required
String
Desired transcription prioritization, will be
"highSpeed" or 
"highAccuracy"
originalFileName
optional
String
The filename of the original file for this interaction
externalIdentifier
optional
String
Any external identifier that the user would like associated with this interaction
downloadUri
optional
String
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
includeAiResults
optional
Boolean
Include AI results, will be 
'true' or
'false' (default)
metadata
optional
String
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
|
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.elevateai.com/v1/interactions',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "type": "audio",
    "languageTag": "en-us",
    "vertical": "default",
    "audioTranscriptionMode": "highAccuracy",
    "audioTranscriptionMode": "highAccuracy",
    "includeAiResults": true,
    "metadata": "{Your JSON metada payload}"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'X-API-Token: {Your API Token}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.elevateai.com/v1/interactions',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "type": "audio",
    "languageTag": "en-us",
    "vertical": "default",
    "audioTranscriptionMode": "highAccuracy",
    "audioTranscriptionMode": "highAccuracy",
    "includeAiResults": true,
    "metadata": "{Your JSON metada payload}"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'X-API-Token: {Your API Token}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
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 URL
Providing access to audio files via the downloadUri parameter is highly recommended for fastest ﻿processing times﻿. 
We take ﻿data security﻿ seriously, and know you do to! If required, we are able to provide an IP address to support IP whitelisting or assist in setting up a private, secure SFTP to support transferring via SFTP with URL format. If you have any questions on how to transfer your audio, reach out at any time to ﻿support@elevateai.com﻿ - we're here to help
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.