---
title: Declare a Transcript
slug: tutorials/declare-a-transcript
description: Learn how to declare an interaction for processing on the ElevateAI platform with this comprehensive document. Discover how successful POST requests result in an HTTP status and a JSON response, including the crucial interactionIdentifier. In case of erro
docTags:
createdAt: 2022-06-14T17:24:57.000Z
---
# // Overview
The first step in processing any transcription file 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`.
:::CodeblockTabs
Sample API Response
```json
{
"interactionIdentifier": "46985457-fa6b-4071-a3f6-5c4858160ec9"
}
```
:::
**It is important you store the **`interactionIdentifier` since it will serve as a required parameter for all other ElevateAI endpoints – and will enable 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 with troubleshooting](https://docs.elevateai.com/#Qofti).
:::hint{type="info"}
All interactions** successfully declared** will count towards your [monthly request quota](https://docs.elevateai.com/#iwwlY), regardless of the file upload status or processing outcome.
Only interactions **successfully processed** are eligible for billing.
**-->** Once declared, you can [check the processing status](docId\:dg0fHnxsBeEqTYD1ruQrQ) of your interaction, as well as the tracking impacts to both [usage](https://docs.elevateai.com/tutorials/elevateai-dashboards#h1qyd) and [spend](https://docs.elevateai.com/tutorials/elevateai-dashboards#jYsvI).
:::
***
# // Request Parameters & Code Examples
*Details on language support for CX AI features can be found on the *[CX AI Feature Overview](docId\:ZATcqMNsVApZs9WWKgeCn)* page. *
:::ApiMethodV2
```json
{
"tab": "examples",
"url": "https://api.elevateai.com/v1/interactions",
"name": "Declare an Interaction for Processing (Transcript)",
"method": "POST",
"request": {
"pathParameters": [],
"queryParameters": [],
"headerParameters": [
{
"kind": "required",
"name": "X-API-Token",
"type": "string",
"description": "Valid API key associated with your account for authentication and usage tracking"
},
{
"kind": "required",
"name": "Content-Type",
"type": "string",
"description": "Will be 'application/JSON'"
}
],
"bodyDataParameters": [
{
"kind": "required",
"name": "type",
"type": "string",
"description": "Type of interaction to be processed, will be \n\"transcript\""
},
{
"kind": "required",
"name": "languageTag",
"type": "string",
"description": "Primary language of transcript, will be \n\"en-us\" (for North American English), \n\"en\" (for International English), or\n\"es-419\" (for North American Spanish)"
},
{
"kind": "required",
"name": "vertical",
"type": "string",
"description": "Vertical associated with interaction, will be \n\"default\""
},
{
"kind": "required",
"name": "transcript",
"type": "Object",
"description": "transcript text to be analyzed (see below)"
}
],
"formDataParameters": []
},
"results": {
"languages": [
{
"id": "IkVdsxIFeIysauK1UAE-R",
"code": "{\n \"interactionIdentifier\": \"string\"\n} ",
"language": "201",
"customLabel": ""
},
{
"id": "ogn--fHK6DTgAEYiv7jAi",
"code": "{\n \"errorMessage\": \"string\"\n}",
"language": "400",
"customLabel": ""
},
{
"id": "x6cJ5u7giQEcVl-2Yh9jn",
"code": "{\r\n \"errorMessage\": \"string\"\r\n}",
"language": "401",
"customLabel": ""
},
{
"id": "OA5jretM7_0dBEf-uJ2UE",
"code": "{\r\n \"errorMessage\": \"string\"\r\n}",
"language": "429",
"customLabel": ""
}
],
"selectedLanguageId": "IkVdsxIFeIysauK1UAE-R"
},
"examples": {
"languages": [
{
"id": "BQMl6KSzeFMAiXJsINHI8",
"code": "curl --location --request POST 'https://api.elevateai.com/v1/interactions' \\\n--header 'Content-Type: application/json' \\\n--header 'X-API-Token: {Your API Token}' \\\n--data-raw '{\n \"type\": \"transcript\",\n \"languageTag\": \"en-us\",\n \"vertical\": \"default\",\n \"transcript\": {\n \"allParticipants\": {\n \"phrases\": [\n \"{word A}\",\n \"{word B}\"\n ],\n \"phraseSegments\": [\n {\n \"startTimeOffset\": {startA},\n \"endTimeOffset\": {endA},\n \"phraseIndex\": 0,\n \"score\": 1\n },\n {\n \"startTimeOffset\": {startB},\n \"endTimeOffset\": {endB},\n \"phraseIndex\": 1,\n \"score\": 1\n }\n ]\n },\n \"participantOne\": {\n \"phrases\": [\n \"{word A}\"\n ],\n \"phraseSegments\": [\n {\n \"startTimeOffset\": {startA},\n \"endTimeOffset\": {endA},\n \"phraseIndex\": 0,\n \"score\": 1\n }\n ]\n },\n \"participantTwo\": {\n \"phrases\": [\n \"{word B}\"\n ],\n \"phraseSegments\": [\n {\n \"startTimeOffset\": {startB},\n \"endTimeOffset\": {endB},\n \"phraseIndex\": 0,\n \"score\": 1\n }\n ]\n }\n }\n}'",
"language": "curl",
"customLabel": ""
},
{
"id": "x_eBrHmErTyeEP47YoBTG",
"code": "var request = require('request');\nvar options = {\n 'method': 'POST',\n 'url': 'https://api.elevateai.com/v1/interactions',\n 'headers': {\n 'Content-Type': 'application/json',\n 'X-API-Token': '{Your API Token}'\n },\n body: '{\\r\\n \"type\": \"transcript\",\\r\\n \"languageTag\": \"en-us\",\\r\\n \"vertical\": \"default\",\\r\\n \"transcript\": {\\r\\n \"allParticipants\": {\\r\\n \"phrases\": [\\r\\n \"{word A}\",\\r\\n \"{word B}\"\\r\\n ],\\r\\n \"phraseSegments\": [\\r\\n {\\r\\n \"startTimeOffset\": {start ms A},\\r\\n \"endTimeOffset\": {end ms A},\\r\\n \"phraseIndex\": 0,\\r\\n \"score\": 1\\r\\n },\\r\\n {\\r\\n \"startTimeOffset\": {start ms B},\\r\\n \"endTimeOffset\": {end ms B},\\r\\n \"phraseIndex\": 1,\\r\\n \"score\": 1\\r\\n }\\r\\n ]\\r\\n },\\r\\n \"participantOne\": {\\r\\n \"phrases\": [\\r\\n \"{word A}\"\\r\\n ],\\r\\n \"phraseSegments\": [\\r\\n {\\r\\n \"startTimeOffset\": {start ms A},\\r\\n \"endTimeOffset\": {end ms A},\\r\\n \"phraseIndex\": 0,\\r\\n \"score\": 1\\r\\n }\\r\\n ]\\r\\n },\\r\\n \"participantTwo\": {\\r\\n \"phrases\": [\\r\\n \"{word B}\"\\r\\n ],\\r\\n \"phraseSegments\": [\\r\\n {\\r\\n \"startTimeOffset\": {start ms B},\\r\\n \"endTimeOffset\": {end ms B},\\r\\n \"phraseIndex\": 0,\\r\\n \"score\": 1\\r\\n }\\r\\n ]\\r\\n }\\r\\n }\\r\\n}'\n\n};\nrequest(options, function (error, response) {\n if (error) throw new Error(error);\n console.log(response.body);\n});\n",
"language": "nodejs",
"customLabel": ""
},
{
"id": "tSr8UByzM5GiVtXZ3E4I2",
"code": "var myHeaders = new Headers();\nmyHeaders.append(\"Content-Type\", \"application/json\");\nmyHeaders.append(\"X-API-Token\", \"{Your API Token}\");\n\nvar raw = \"{\\r\\n \\\"type\\\": \\\"transcript\\\",\\r\\n \\\"languageTag\\\": \\\"en-us\\\",\\r\\n \\\"vertical\\\": \\\"default\\\",\\r\\n \\\"transcript\\\": {\\r\\n \\\"allParticipants\\\": {\\r\\n \\\"phrases\\\": [\\r\\n \\\"{word A}\\\",\\r\\n \\\"{wordB}\\\"\\r\\n ],\\r\\n \\\"phraseSegments\\\": [\\r\\n {\\r\\n \\\"startTimeOffset\\\": {startmsA},\\r\\n \\\"endTimeOffset\\\": {endmsA},\\r\\n \\\"phraseIndex\\\": 0,\\r\\n \\\"score\\\": 1\\r\\n },\\r\\n {\\r\\n \\\"startTimeOffset\\\": {start ms B\\r\\n },\\r\\n \\\"endTimeOffset\\\": {end ms B\\r\\n },\\r\\n \\\"phraseIndex\\\": 1,\\r\\n \\\"score\\\": 1\\r\\n }\\r\\n ]\\r\\n },\\r\\n \\\"participantOne\\\": {\\r\\n \\\"phrases\\\": [\\r\\n \\\"{word A}\\\"\\r\\n ],\\r\\n \\\"phraseSegments\\\": [\\r\\n {\\r\\n \\\"startTimeOffset\\\": {start ms A\\r\\n },\\r\\n \\\"endTimeOffset\\\": {end ms A\\r\\n },\\r\\n \\\"phraseIndex\\\": 0,\\r\\n \\\"score\\\": 1\\r\\n }\\r\\n ]\\r\\n },\\r\\n \\\"participantTwo\\\": {\\r\\n \\\"phrases\\\": [\\r\\n \\\"{word B}\\\"\\r\\n ],\\r\\n \\\"phraseSegments\\\": [\\r\\n {\\r\\n \\\"startTimeOffset\\\": {start ms B\\r\\n },\\r\\n \\\"endTimeOffset\\\": {end ms B\\r\\n },\\r\\n \\\"phraseIndex\\\": 0,\\r\\n \\\"score\\\": 1\\r\\n }\\r\\n ]\\r\\n }\\r\\n }\\r\\n}\";\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api.elevateai.com/v1/interactions\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));",
"language": "javascript",
"customLabel": ""
},
{
"id": "dzN83h91blzHvwK1lA46l",
"code": "import requests\nimport json\n\nurl = \"https://api.elevateai.com/v1/interactions\"\n\npayload = \"{\\r\\n \\\"type\\\": \\\"transcript\\\",\\r\\n \\\"languageTag\\\": \\\"en-us\\\",\\r\\n \\\"vertical\\\": \\\"default\\\",\\r\\n \\\"transcript\\\": {\\r\\n \\\"allParticipants\\\": {\\r\\n \\\"phrases\\\": [\\r\\n \\\"{word A}\\\",\\r\\n \\\"{wordB}\\\"\\r\\n ],\\r\\n \\\"phraseSegments\\\": [\\r\\n {\\r\\n \\\"startTimeOffset\\\": {startmsA},\\r\\n \\\"endTimeOffset\\\": {endmsA},\\r\\n \\\"phraseIndex\\\": 0,\\r\\n \\\"score\\\": 1\\r\\n },\\r\\n {\\r\\n \\\"startTimeOffset\\\": {start ms B\\r\\n },\\r\\n \\\"endTimeOffset\\\": {end ms B\\r\\n },\\r\\n \\\"phraseIndex\\\": 1,\\r\\n \\\"score\\\": 1\\r\\n }\\r\\n ]\\r\\n },\\r\\n \\\"participantOne\\\": {\\r\\n \\\"phrases\\\": [\\r\\n \\\"{word A}\\\"\\r\\n ],\\r\\n \\\"phraseSegments\\\": [\\r\\n {\\r\\n \\\"startTimeOffset\\\": {start ms A\\r\\n },\\r\\n \\\"endTimeOffset\\\": {end ms A\\r\\n },\\r\\n \\\"phraseIndex\\\": 0,\\r\\n \\\"score\\\": 1\\r\\n }\\r\\n ]\\r\\n },\\r\\n \\\"participantTwo\\\": {\\r\\n \\\"phrases\\\": [\\r\\n \\\"{word B}\\\"\\r\\n ],\\r\\n \\\"phraseSegments\\\": [\\r\\n {\\r\\n \\\"startTimeOffset\\\": {start ms B\\r\\n },\\r\\n \\\"endTimeOffset\\\": {end ms B\\r\\n },\\r\\n \\\"phraseIndex\\\": 0,\\r\\n \\\"score\\\": 1\\r\\n }\\r\\n ]\\r\\n }\\r\\n }\\r\\n}\"\nheaders = {\n 'Content-Type': 'application/json',\n 'X-API-Token': '{Your API Token}'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n",
"language": "python",
"customLabel": ""
}
],
"selectedLanguageId": "BQMl6KSzeFMAiXJsINHI8"
},
"description": "",
"currentNewParameter": {
"label": "Body Parameter",
"value": "bodyDataParameters"
},
"autoGeneratedAnchorSlug": "declare-an-interaction-for-processing-transcript",
"legacyHash": "YB2Z7GXmQnpKSqzssswV-"
}
```
:::
***
# // Formatting a Transcript for Processing
`Transcript` files will be formatted according to the schema below and should be included as a body parameter when declaring the transcript for processing.
:::hint{type="info"}
**NOTE: **`allParticpants` is a required object when providing a transcript for analysis.
While `participantOne` and `participantTwo` objects are not required, they are highly recommended.
:::
::::ExpandableHeading
## Sample Transcription Format
:::CodeblockTabs
Sample Transcription Format
```json
{
"allParticipants": {
"phrases": [
"I", "Hope", "This", "Documentation", "Was", "Useful", "Thank", "You",
...
]
"phraseSegments": [
{
"startTimeOffset": 870,
"endTimeOffset": 1330,
"phraseIndex" 0,
"score": 1
}
...
]
},
"participantOne": {
"phrases": [
"I","Hope","This","Documentation","Was","Useful",
...
]
...
},
...
}
```
:::
::::
:::ExpandableHeading
## Schema
| **Element** | **Type** | **Description** |
| -------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **\{participant}** | object | Top level for [speaker label](https://docs.elevateai.com/transcription-features#fDLGr) will be
`allParticipants` or
`participantOne` and
`participantTwo` |
| \{participant}/**phrases** | array of strings | Ordered list of each unique phase spoken by `{participant}` in the interaction |
| \{participant}/**phraseSegments** | array of objects | List of details associated with each phrase in transcript for the `{participant}` |
| \{participant}/phraseSegments/**startTimeOffset ** | number | Start time of phrase, in milliseconds |
| \{participant}/phraseSegments/**endTimeOffset** | number | End time of phrase, in milliseconds |
| \{participant}/phraseSegments/**phraseIndex** | number | Index of phrase in `{participant}`/phrases |
| \{participant}/phraseSegments/**score** | float | Confidence score, if not available should be 1 |
:::
**Need more help? **Contact the [ElevateAI Support team](mailto\:support@elevateai.com).