Quality Management and Speech Analytics API
8x8 Quality Management and Speech Analytics API for evaluations, scorecards, transcripts and speech analytics over recorded contact center interactions.
OpenAPI Specification
{
"openapi": "3.0.0",
"info": {
"version": "1.0.21",
"title": "Quality Management and Speech Analytics API",
"contact": { "name": "QM/SA Team", "email": "qm-team@8x8.com" },
"termsOfService": "https://www.8x8.com/terms-and-conditions",
"description": "The Quality Management and Speech Analytics (QMSA) API enables you to access raw resources such as interaction metadata, evaluation results, and users.\n## **Authentication**\nYou can try out this API through request authentication using your client credentials. Refer to [Client Credentials](/analytics/docs/how-to-get-api-keys) on the [Getting Started](/tech-partner/docs/getting-started) page for more information.\nAll requests must be made over HTTPS - calls made over HTTP will fail.\n## **Regions**\nThe API resources are available distinctly for each geographical region in which the customer is located or provisioned. The base URLs for regions are as follows:\n<table> <tr> <td><b>URL</b></td> <td><b>Region</b></td> </tr> <tr> <td><b><a href='https://api.8x8.com/qm/us-west/v1'>https://api.8x8.com/qm/us-west/v1</a></b></td><td>Western US</td></tr><tr> <td><b><a href='https://api.8x8.com/qm/us-east/v1'>https://api.8x8.com/qm/us-east/v1</a></b></td><td>Eastern US</td></tr><tr> <td><b><a href='https://api.8x8.com/qm/uk/v1'>https://api.8x8.com/qm/uk/v1</a></b></td><td>United Kingdom</td></tr><tr> <td><b><a href='https://api.8x8.com/qm/ap/v1'>https://api.8x8.com/qm/ap/v1</a></b></td><td>Australia</td> </tr> <tr> <td><b><a href='https://api.8x8.com/qm/ca/v1'>https://api.8x8.com/qm/ca/v1</a></b></td><td>Canada</td> </tr> </table>\n\n## **Headers**\nWith every API call, the header should contain the **`pbx`** name from which the data is to be derived.\nThe header key is **`pbx`**.\n## **Resource IDs**\nThe QMSA API uses short non-sequential unique **`ids`**. Every resource **`id`** **must** consist of URL friendly characters such as:\n* Uppercase or lowercase letters of the alphabet (**`A-Z`** or **`a-z`**)\n* Numbers (**`0-9`**)\n* Underscores (**`_`**) or hyphens (**`-`**)\nThe QMSA API uses the following resoruce **`ids`**:\n* **`userReference`** (e.g., `283`) - The unique identifier of the system registered user.\n\n* **`interactionGuid`** (e.g.,`int-15bd0b19d21-KKx2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample`) - The interaction object's globally unique identifier for a single interaction.\n* **`customField`** (e.g., `customField1`) - One of 25 custom field identifiers.\n* **`evaluationId`** (e.g., `45`) - The unique identifier for a system evaluation.\n## **Representation of Date and Time**\nAll exchange of date and time-related data **must** be completed according to the ISO 8601 standard and stored in UTC. When returning date and time-related data **`YYYY-MM-DDThh:mm:ss`** format **must** be used.\n\n## **Payload Media Type**\nWhere applicable the QMSA API requires the use pf the JSON media-type. Requests that contain a message-body use plain JSON to set or update resource states. `Content-type: application/json` and `Accept: application/json` headers **must** be set on all requests if not stated otherwise.\n\n## **Ordering**\nBy default, all resources returned in collections are ordered by their creation time in ascending order.\n## **Pagination**\nThe QMSA API uses URI query pagination to retrieve resource collections. When a resource collection is obtained, the method used to obtain the total count of the type resourced is also returned. The pages **must** be zero (0) based, and the page size **must** be a value between 1 and 100. The default value is 100. The answer can contain links to the either the **`nextPage`** or **`previousPage`**.\n## **HATEOAS**\nThe QMSA API uses the Spring HATEOAS model for retrieving links to related resources within responses.\n## **Filtering**\nThe QMSA API is designed with limited filtering capiblities. The filtering that is available in each method is possible only for important key/value pairs. More information on what is avaiable for filtering can be found with each method description.\n## **Error response**\nThe QMSA API returns both machine-readable error codes and human-readable error messages in the response body when an error occurs.\n## **Versioning**\nThis API uses URI versioning. Subsequent versions may introduce breaking changes.\n## **Example**\nSecond version of method: `https://api.8x8.com/qm/us-west/V2/method`"
},
"servers": [
{
"url": "https://api.8x8.com/qm/{region}/{apiversion}",
"description": "The QM/SA API Gateway Endpoint",
"variables": {
"region": {
"enum": ["us-west", "us-east", "uk", "ap", "ca"],
"default": "us-west"
},
"apiversion": {
"default": "v1"
}
}
}
],
"tags": [
{ "name": "Users" },
{ "name": "Interactions" },
{ "name": "Evaluations" },
{ "name": "Speech Analytics" }
],
"security": [{ "bearerAuth": [] }],
"paths": {
"/interactions/count": {
"get": {
"tags": ["Interactions"],
"summary": "Interaction count.",
"description": "This method retrieves the interactions count for the specified interaction type. Unless the interaction type is specified, all the interaction types are retrieved.",
"operationId": "interactions count",
"parameters": [
{
"name": "interactionType",
"in": "query",
"description": "Interaction type.",
"required": false,
"style": "form",
"explode": true,
"schema": { "$ref": "#/components/schemas/interactionType" }
},
{
"name": "Content-Type",
"in": "header",
"required": true,
"style": "simple",
"explode": false,
"schema": { "type": "string", "example": "application/json" }
},
{
"name": "startTS",
"in": "query",
"description": "The UTC time to begin the query with.",
"required": false,
"style": "form",
"explode": true,
"schema": { "type": "string", "example": "2018-03-02 06:14:53" }
},
{
"name": "endTS",
"in": "query",
"description": "The UTC time to end the query with.",
"required": false,
"style": "form",
"explode": true,
"schema": { "type": "string", "example": "2018-03-02 06:14:53" }
},
{
"name": "userReference",
"in": "query",
"description": "The user's unique identification for interactions counts.",
"required": false,
"style": "form",
"explode": true,
"schema": { "type": "number", "format": "double", "example": 283 }
},
{
"name": "customField",
"in": "query",
"required": false,
"style": "form",
"explode": true,
"schema": { "type": "array", "items": { "type": "string" } }
},
{
"name": "customFieldValue",
"in": "query",
"required": false,
"style": "form",
"explode": true,
"schema": { "type": "string", "example": "data" }
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": { "type": "string", "example": 34 }
}
}
},
"default": { "description": "Unexpected error" }
},
"deprecated": false
}
},
"/interactions": {
"get": {
"tags": ["Interactions"],
"summary": "The Interaction collection",
"description": "This method retrieves interaction collections.",
"operationId": "interactions",
"parameters": [
{
"name": "Content-Type",
"in": "header",
"required": true,
"style": "simple",
"explode": false,
"schema": { "type": "string", "example": "application/json" }
},
{
"name": "startTS",
"in": "query",
"description": "The UTC time to begin the query with.",
"required": false,
"style": "form",
"explode": true,
"schema": { "type": "string", "example": "2018-03-02 06:14:53" }
},
{
"name": "endTS",
"in": "query",
"description": "The UTC time to end the query with.",
"required": false,
"style": "form",
"explode": true,
"schema": { "type": "string", "example": "2018-03-02 09:14:53" }
},
{
"name": "page",
"in": "query",
"description": "The page to start the query with.",
"required": false,
"style": "form",
"explode": true,
"schema": { "type": "number", "format": "double", "example": 1 }
},
{
"name": "size",
"in": "query",
"description": "The page size to begin query with.",
"required": false,
"style": "form",
"explode": true,
"schema": { "type": "number", "format": "double", "example": 30 }
},
{
"name": "interactionGuid",
"in": "query",
"description": "The unique identifier of the interaction object which uniquely identifies a record. Separate up to **10** **`guids`** using a comma.",
"required": false,
"style": "form",
"explode": true,
"schema": { "type": "array", "items": { "type": "string" } }
},
{
"name": "userReference",
"in": "query",
"description": "The unique identifier for the requested user interactions.",
"required": false,
"style": "form",
"explode": true,
"schema": { "type": "number", "format": "double", "example": 283 }
},
{
"name": "customField",
"in": "query",
"required": false,
"style": "form",
"explode": true,
"schema": { "type": "array", "items": { "type": "string" } }
},
{
"name": "customFieldValue",
"in": "query",
"required": false,
"style": "form",
"explode": true,
"schema": { "type": "string", "example": "data" }
},
{
"name": "interactionType",
"in": "query",
"description": "The interaction type.",
"required": false,
"style": "form",
"explode": true,
"schema": { "$ref": "#/components/schemas/interactionType" }
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/interactionDetailsResponse"
},
"example": {
"pageNumber": 1,
"pageSize": 100,
"pageResultSize": 1,
"content": [
{
"createdAt": "2018-03-02T07:14:53",
"interactionGuid": "int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample",
"agent": {
"userReference": 283,
"agentId": "agent123",
"name": "John Doe",
"mainGroup": "Agent",
"supervisorName": "David Smith",
"trainerName": "Ian Smith"
},
"telephony": {
"direction": "inbound",
"callerPhoneNumber": 4085551212,
"callerName": "Joe Customer",
"dialedPhoneNumber": 1541549643,
"vccTransactionId": 12345,
"transferredFrom": "ag32049403",
"transferredTo": "ag52049403",
"holdDuration": 34,
"status": "completed"
},
"media": {
"interactionType": "voiceInteraction",
"interactionDuration": 435,
"videoSize": 4566,
"audioSize": 523
},
"customFields": {
"customField": {
"value": "field value",
"displayName": "field custom name"
},
"customField1": {
"value": "field value",
"displayName": "field custom name"
},
"customField2": {
"value": "field value",
"displayName": "field custom name"
},
"customField3": {
"value": "field value",
"displayName": "field custom name"
},
"customField4": {
"value": "field value",
"displayName": "field custom name"
},
"customField5": {
"value": "field value",
"displayName": "field custom name"
},
"customField6": {
"value": "field value",
"displayName": "field custom name"
},
"customField7": {
"value": "field value",
"displayName": "field custom name"
},
"customField8": {
"value": "field value",
"displayName": "field custom name"
},
"customField9": {
"value": "field value",
"displayName": "field custom name"
},
"customField10": {
"value": "field value",
"displayName": "field custom name"
},
"customField11": {
"value": "field value",
"displayName": "field custom name"
},
"customField12": {
"value": "field value",
"displayName": "field custom name"
},
"customField13": {
"value": "field value",
"displayName": "field custom name"
},
"customField14": {
"value": "field value",
"displayName": "field custom name"
},
"customField15": {
"value": "field value",
"displayName": "field custom name"
},
"customField16": {
"value": "field value",
"displayName": "field custom name"
},
"customField17": {
"value": "field value",
"displayName": "field custom name"
},
"customField18": {
"value": "field value",
"displayName": "field custom name"
},
"customField19": {
"value": "field value",
"displayName": "field custom name"
},
"customField20": {
"value": "field value",
"displayName": "field custom name"
},
"customField21": {
"value": "field value",
"displayName": "field custom name"
},
"customField22": {
"value": "field value",
"displayName": "field custom name"
},
"customField23": {
"value": "field value",
"displayName": "field custom name"
},
"customField24": {
"value": "field value",
"displayName": "field custom name"
},
"customField25": {
"value": "field value",
"displayName": "field custom name"
}
},
"speechAnalysis": {
"overallEmotion": "Positive",
"overtalk": 7.5,
"clarity": 90
},
"links": [
{
"rel": "notes",
"href": "https://api.8x8.com/qm/us-west/v1/interactions/int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample/notes",
"type": "GET"
},
{
"rel": "labels",
"href": "https://api.8x8.com/qm/us-west/v1/interactions/int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample/labels",
"type": "GET"
},
{
"rel": "transcriptions",
"href": "https://api.8x8.com/qm/us-west/v1/interactions/int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample/transcriptions",
"type": "GET"
},
{
"rel": "media",
"href": "https://api.8x8.com/qm/us-west/v1/interactions/int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample/media",
"type": "GET"
}
]
}
],
"links": [
{
"rel": "nextUrl",
"href": "https://api.8x8.com/qm/us-west/v1/interactions?page=2&size=100",
"type": "GET"
},
{
"rel": "prevUrl",
"href": "https://api.8x8.com/qm/us-west/v1/interactions?page=1&size=100",
"type": "GET"
}
]
}
}
}
},
"default": { "description": "Unexpected error" }
},
"deprecated": false
}
},
"/interactions/{interactionGuid}": {
"delete": {
"tags": ["Interactions"],
"summary": "Deletes a single interaction.",
"description": "Removes the interaction and all associated metadata. This action cannot be undone.",
"operationId": "delete interaction",
"parameters": [
{
"name": "interactionGuid",
"in": "path",
"description": "The interaction unique identifier.",
"required": true,
"style": "simple",
"explode": false,
"schema": {
"type": "string",
"example": "int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample"
}
}
],
"responses": {
"200": { "description": "OK" },
"default": { "description": "Unexpected error" }
},
"deprecated": false
}
},
"/interactions/{interactionGuid}/purge": {
"delete": {
"tags": ["Interactions"],
"summary": "This method purges a single interaction.",
"description": "Removes the interaction and all associated metadata. **This action cannot be undone.**\n",
"operationId": "purge interaction",
"parameters": [
{
"name": "interactionGuid",
"in": "path",
"description": "The interaction unique identifier.",
"required": true,
"style": "simple",
"explode": false,
"schema": {
"type": "string",
"example": "int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample"
}
}
],
"responses": {
"200": { "description": "OK" },
"default": { "description": "Unexpected error" }
},
"deprecated": false
}
},
"/interactions/{interactionGuid}/{customFieldNo}": {
"put": {
"tags": ["Interactions"],
"summary": "This method updates custom fields.",
"description": "This method either updates or removes the custom field contained data for user customizable fields. Only custom fields **1** to **15** can be edited.",
"operationId": "update custom field",
"parameters": [
{
"name": "interactionGuid",
"in": "path",
"description": "The interaction unique identifier",
"required": true,
"style": "simple",
"explode": false,
"schema": {
"type": "string",
"example": "int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample"
}
},
{
"name": "customFieldNo",
"in": "path",
"description": "The custom field identifier",
"required": true,
"style": "simple",
"explode": false,
"schema": { "$ref": "#/components/schemas/customFieldNo" }
},
{
"name": "Content-Type",
"in": "header",
"required": true,
"style": "simple",
"explode": false,
"schema": { "type": "string", "example": "application/json" }
}
],
"requestBody": {
"content": {
"text/plain": {
"schema": { "type": "string", "example": "custom field text" },
"example": "custom field text"
}
},
"required": true
},
"responses": {
"200": { "description": "OK" },
"default": { "description": "Unexpected error" }
},
"deprecated": false
},
"delete": {
"tags": ["Interactions"],
"summary": "Deletes custom field data",
"description": "Updates or removes the custom field contained data for user customizable fields. Only the custom fields **1** to **15** are editable.",
"operationId": "deletes the custom field",
"parameters": [
{
"name": "interactionGuid",
"in": "path",
"description": "The interaction unique identifier",
"required": true,
"style": "simple",
"explode": false,
"schema": {
"type": "string",
"example": "int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample"
}
},
{
"name": "customFieldNo",
"in": "path",
"description": "The custom field identifier",
"required": true,
"style": "simple",
"explode": false,
"schema": { "$ref": "#/components/schemas/customFieldNo" }
},
{
"name": "Content-Type",
"in": "header",
"required": true,
"style": "simple",
"explode": false,
"schema": { "type": "string", "example": "application/json" }
}
],
"responses": {
"200": { "description": "OK" },
"default": { "description": "Unexpected error" }
},
"deprecated": false
}
},
"/interactions/{interactionGuid}/transcriptions": {
"get": {
"tags": ["Interactions"],
"summary": "This method queries a single interaction transcription record.",
"description": "Retrieves available transcriptions for the selected interaction",
"operationId": "interaction transcription",
"parameters": [
{
"name": "interactionGuid",
"in": "path",
"description": "The interaction unique identifier",
"required": true,
"style": "simple",
"explode": false,
"schema": {
"type": "string",
"example": "int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample"
}
},
{
"name": "Content-Type",
"in": "header",
"required": true,
"style": "simple",
"explode": false,
"schema": { "type": "string", "example": "application/json" }
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"description": "Transcription value respone",
"items": {
"$ref": "#/components/schemas/transcriptionValueResponse"
}
},
"example": [
{
"text": "Good morning.",
"confidence": 100,
"channel": 1,
"emotion": "Positive",
"gender": "male",
"timestampStart": 10,
"timestampEnd": 11
}
]
}
}
},
"default": { "description": "Unexpected error" }
},
"deprecated": false
}
},
"/interactions/{interactionGuid}/topics": {
"get": {
"tags": ["Interactions"],
"summary": "Queries a single interaction for matched topics",
"description": "Retrieves the list of detected topics within the transcriptions",
"operationId": "topics",
"parameters": [
{
"name": "interactionGuid",
"in": "path",
"description": "The interaction unique identifier",
"required": true,
"style": "simple",
"explode": false,
"schema": {
"type": "string",
"example": "int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample"
}
},
{
"name": "Content-Type",
"in": "header",
"required": true,
"style": "simple",
"explode": false,
"schema": { "type": "string", "example": "application/json" }
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": { "$ref": "#/components/schemas/topic" }
},
"example": [
{
"channel": 0,
"topic": "Agent Sales Enablers",
"category": "Sales"
}
]
}
}
},
"default": { "description": "Unexpected error" }
},
"deprecated": false
}
},
"/interactions/{interactionGuid}/labels": {
"get": {
"tags": ["Interactions"],
"summary": "Query a single interaction attached label",
"description": "Retrieves the collection of labels attached to the interaction",
"operationId": "labels",
"parameters": [
{
"name": "interactionGuid",
"in": "path",
"description": "The interaction unique identifier",
"required": true,
"style": "simple",
"explode": false,
"schema": {
"type": "string",
"example": "int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample"
}
},
{
"name": "Content-Type",
"in": "header",
"required": true,
"style": "simple",
"explode": false,
"schema": { "type": "string", "example": "application/json" }
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": { "$ref": "#/components/schemas/labelValue" }
},
"example": [
{
"text": "read this",
"createdAt": "2018-03-02T06:14:53",
"updatedAt `2018-03-02T06:14:53`": "",
"links": [
{
"rel": "creator",
"href": "https://api.8x8.com/qm/us-west/v1/users/854",
"type": "GET"
},
{
"rel": "updater",
"href": "https://api.8x8.com/qm/us-west/v1/users/854",
"type": "GET"
}
]
}
]
}
}
},
"default": { "description": "Unexpected error" }
},
"deprecated": false
}
},
"/interactions/{interactionGuid}/notes": {
"get": {
"tags": ["Interactions"],
"summary": "Query the attached notes for a single interaction",
"description": "Retrieve the notes attached to an interaction",
"operationId": "notes",
"parameters": [
{
"name": "interactionGuid",
"in": "path",
"description": "The interaction unique identifier",
"required": true,
"style": "simple",
"explode": false,
"schema": {
"type": "string",
"example": "int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample"
}
},
{
"name": "Content-Type",
"in": "header",
"required": true,
"style": "simple",
"explode": false,
"schema": { "type": "string", "example": "application/json" }
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": { "$ref": "#/components/schemas/noteValue" }
},
"example": [
{
"text": "read this",
"interactionTimestamp": 10,
"createdAt": "2018-03-02T06:14:53",
"updatedAt `2018-03-02T06:14:53`": "",
"links": [
{
"rel": "creator",
"href": "https://api.8x8.com/qm/us-west/v1/users/854",
"type": "GET"
}
]
}
]
}
}
},
"default": { "description": "Unexpected error" }
},
"deprecated": false
}
},
"/interactions/{interactionGuid}/media": {
"get": {
"tags": ["Interactions"],
"summary": "The requested interaction media file download",
"description": "Retrieves audio, video, mixed audio (MP3), and video (MP4)\nTranscoding (bit rate, sam
# --- truncated at 32 KB (103 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/8x8/refs/heads/main/openapi/8x8-analytics-quality-management-and-speech-analytics-api.json