/appmatches API Reference

V-Spark Online Help

/appmatches API Reference

The /appmatches endpoint retrieves phrase matches for applications associated with a transcript. /appmatches supports only the GET method.

Synopsis

GET /appmatches/CO_SHORT/ORG_SHORT/transcriptID?token=TOKEN

The preceding example shows the required components of an /appmatches request and uses the following variables:

CO_SHORT: The short name of the company with which the transcript is associated.
ORG_SHORT: The short name of the organization with which the transcript is associated. Note that a folder is not required because transcriptIDs are unique to organizations.
transcriptID: Unique identifier for the transcript to be queried.
TOKEN: An authorization token with read permissions for the queried transcript's organization.

Description

/appmatches returns a JSON object containing phrase match and score data for leaf categories defined in applications associated with a given transcript. By default, /appmatches returns match and score data for each leaf category and for every application associated with the specified transcript.

To limit results to a specific set of applications, categories, or subcategories, specify those entities in JSON data submitted with the request. Note that for applications with multiple categories, the API returns phrase match data for the categories specified in the request only, and returns scores without phrase match data for any other categories part of that application. A queried transcript with no application matches will return a JSON object with file information, but no scorecard object data.

Content Types

Application, category, and subcategory names for GET requests must be supplied as JSON-formatted data with the "application/json" MIME type.
GET requests return JSON-formatted data with the "application/json" MIME type.

Example /appmatches Requests

The following example /appmatches request specifies a transcriptID of 3 associated with the company Co-Short and the organization Org-Short. The example request does not include a JSON-formatted list of applications and categories, so all applications linked to the transcript's folder will be included in the request's JSON output.

curl 'http://example.com:3000/appmatches/Co-Short/Org-Short/3?token=123'

The output of the preceding example is a JSON object with matched phrases and score data for all applications associated with that transcript.

The following example queries /appmatches for a transcript with a transcriptID of 6 associated with the company Co-Short and the organization Org-Short. The example also includes JSON data for specific applications and categories:

curl 'http://example.com:3000/appmatches/Co-Short/Org-Short/6?token=123' --header 'Content-Type: application/json' --data-raw '{"Agent Scorecard":["Compliance.Recording"], "TopLevel":["NextLevel.LowestLevel"]}'

The output of the preceding example is a JSON object with matched phrases and score data for the following entities:

The Recording subcategory of the Compliance category of the Agent Scorecard application.
The LowestLevel subcategory of the NextLevel category in the TopLevel application.

To make the preceding example request with a file instead of in-line JSON data, include the filename and path of the file, as in the following example:

curl 'http://example.com:3000/appmatches/Co-Short/Org-Short/6?token=123' --header 'Content-Type: application/json' --data @phrase-request.json

The preceding example references the file phrase-request.json instead of in-line JSON data. This file must be saved locally on the system that originates the request.

Example /appmatches JSON input

The following example JSON specifies application, category, and category names to be submitted with a request to /appmatches:

{
  "APP1": [
    "Category1.Leaf1",
    "Category2.Leaf2"
  ],
  "APP2": [
    "Category3"
  ]
}

The preceding example specifies the following entities for phrase match data in request output:

Leaf1, a subcategory of Category1, which is a category in the application APP1.
Leaf2, a subcategory of Category2, which is a category in the application APP1.
All subcategories defined for Category3, which is a category of the application APP2.

Because only two subcategories are specified for APP1, phrase matches will be returned for only those two subcategories, including any subcategories below them. Phrase matches will be returned for all subcategories under APP2's Category3. The request returns only scores for other categories in APP1 and APP2.

Any category below the ones specified will be included with results. Subcategories are referenced using the dot operator (for example, the . in Category2.Leaf2), and this operator may be used to reference as many subcategories as the application contains. For example, the entry Category5.Subcategory5.Subcategory6.Subcategory7.LastLeaf could be used to specify the deeply nested LastLeaf without including phrase matches for its parent subcategories.

Example /appmatches JSON output

JSON data output from /appmatches includes the following information:

Top-level fields for the transcript's audio filename, transcriptID (abbreviated tId in JSON data), and organization.
The top-level scorecard object, which contains all application score, match, and phrase data.
Fields below scorecard for each included application category and subcategory.
A score field for each category's overall score.
A match_data object that includes all matches objects for that application, along with the query phrase in the application that triggered the match.
A matches object that includes the start and end times for the utterance containing the phrase match, along with the phrase's speaker (either agent or client).

Note

Applications may specify phrases to be excluded from scoring. These exclude phrases can be identified in the application by the - prefix.

As of V‑Spark 4.2.0, when an application with leaf-level exclude phrases is requested in /appmatches output, that output contains all exclude phrases and their matches, even if those matches do not impact category scores.

Exclude phrases only impact scoring when they are in the same speaker turn as include phrases, and speaker turns that contain only exclude phrases do not affect category scores. So, to identify exactly which exclude phrases affect scores in /appmatches output, look for speaker turns that contain both exclude and include phrases.

The following example JSON shows the data returned from an /appmatches request with relatively few matches. The basic structure for applications illustrated in the you section of the following example is repeated at the JSON object's lower subcategory levels in the subcategories section when applicable.

{
  "filename": "example.wav",
  "tId": 6,
  "organization": "Org-Short",
  "scorecard": { 
      "you": {
              "subcategories": {},
              "score": 3,
              "match_data": [
                  {
                      "matches": [
                          [
                              1249.24,
                              1252.18,
                              "agent",
                              "you have a lock on you when you have a wonderful day. Okay,"
                          ],
                          [
                              1248.13,
                              1249.88,
                              "client",
                              "Okay. Thank you. Pamela for your help."
                          ]
                      ],
                      "phrase": "all: you ~s>1240"
                  }
              ]
          }
      }
}

The following table describes the hierarchy and contents of /appmatches JSON output:

Table 1. Elements in /appmatches JSON output

Element				Type	Description
filename				string	The source audio's filename.
tId				value	The source transcript's transcriptID.
organization				string	The short name of the organization associated with the transcript.
scorecard				object	Stores one key-value pair for each application with score and match data. The key is the name of the application, and the value is a JSON object that contains the results from each matched application category.
	`APPLICATION-NAME`			object	Stores the phrase and match data for the named application.
		subcategories		object	Stores results from each matched application subcategory contained in its parent category object. Each subcategory with match data repeats the structure of the `APPLICATION-NAME` object at lower levels.
		score		value	The overall category score.
		match_data		array	Stores one object for each phrase in the application category.
			matches	array	The phrase match's start time, end time, speaker, and utterance.
			phrase	string	The application phrase that triggered the match.

In this section:

V-Spark Online Help

/appmatches API Reference

Example /appmatches Requests

Example /appmatches JSON input

Example /appmatches JSON output

Note

Search results