V-Spark Online Help

Values for the fields Parameter

When specifying output=summary in a /search request, use the fields parameter to define the data fields to be included with or excluded from search results. Multiple fields may be provided in a comma-separated list. To exclude a field from search results, add a hyphen - before the name of the field.

The following section lists all output field option parameters and describes the fields they return when specified:

voci

Fields that are specific to audio data that has been processed by V‑Spark. This is the default behavior if no value for the fields option is specified. voci fields include the following:

agent_clarity

How clear the agent channel/speech is, expressed as a value between 0 and 1, where 1 is highest.

agent_emotion

Overall agent emotional intelligence assessment derived from both acoustic and linguistic information. Has one of the following values: Positive, Worsening, Improving, or Negative.

agent_gender

Agent gender, either Male or Female.

agentid

Identifier for a specific agent.

client_clarity

How clear the client channel/speech is, expressed as a value between 0 and 1, where 1 is highest.

client_emotion

Overall agent emotional intelligence assessment derived from both acoustic and linguistic information. Has one of the following values: Positive, Worsening, Improving, or Negative.

client_gender

Client gender, either Male or Female.

datetime

Transcript date and time. Data for the datetime field is stored using the organization's time zone, which may vary by organization.

diarization

Only provided in two-speaker, one-channel calls; a value between 0 and 1 identifies how completely the call was divided into individual speakers. A value of 1 is the best possible value for speaker separation. A value of 2 means the call was not diarized.

duration

Call duration.

es_doc_id

Unique identifier for a transcript in Elasticsearch index. Not included when voci is specified as return field.

filename

Name of the uploaded audio or JSON file that contains matches for the search request.

folder

Name of the folder where the file was uploaded. Not included when voci is specified as return field.

last_modified

The date and time at which an update to the last_modified field was last triggered in the Elasticsearch record associated with a transcript. If the last_modified field is not present or has no date and time value, its return value is false. Data for the last_modified field is stored in Coordinated Universal Time (UTC).

The following events trigger an update to the last_modified field:

  • Creating a new transcript.

  • Updating transcript scores by reprocessing an application.

  • Deleting an application or application category associated with the transcript.

  • Unlinking an application from the transcript's folder, if that application has previously been used to score the transcript.

  • Updating transcript metadata using the API.

overall_emotion

Overall emotional intelligence assessment for an audio file, derived from both acoustic and linguistic information. Has one of the following values: Positive, Worsening, Improving, or Negative.

overtalk

Percentage of call when the agent talks over or interrupts the client. Equal to the number of turns where the agent initiated overtalk divided by the total number of agent turns.

preview

An excerpt of the transcribed call in which matched terms are highlighted.

requestid

Unique identifier for a transcription request. This value is assigned when an audio file is submitted for transcription.

score

Calculation of how well a transcript matches the terms specified in your search. This is represented as a value between 0 and 1, and can depend on the type of query that you submitted. For example, date range queries always provide a score value of 1 for any transcription that occurred in the specified date range.

silence

Percentage of call duration that is silence. Equal to all non-speech time, this value is calculated as call duration minus the sum of the duration of each word. If music and noise are not decoded to word-events, they are counted as silence.

tags

Tags added to files in the GUI. Not included when voci is specified as return field.

tid

Unique identifier for a transcript.

url

URL to visit the file details in the GUI. Not included when voci is specified as return field.

CLIENT-DATA

Custom metadata fields, specified by name, configured for the folder that processed the audio.

all

Combination of all voci and CLIENT-DATA fields.

apps

Scores for all applications. Note that requests may specify eitherapps or app.APPNAME, not both.

app.APPNAME

Scores for a specific application. Note that you may only specify eitherapps or app.APPNAME, not both.

app.APPNAME.TOP_CATEGORY

Scores for a specific category in an application. Note that the category's full name includes its parents' names, including any parent categories. For example, app.APPNAME.TOP_CATEGORY.LOWER_CATEGORY refers to an application category called LOWER_CATEGORY, which is a child of TOP_CATEGORY and APPNAME.

Using the fields Parameter

The following example GET request shows a /search call with multiple options specified for the fields parameter:

curl -s "http://example.company.com/search/ExampleCo/ExampleOrg/ExampleFolder?token=1234567890&daterange=20210701-20210702&format=csv&output=summary&fields=filename,duration"

In the preceding example, the output=summary&fields=filename,duration parameters include only the filename and duration fields in search results.

The following example GET request shows how to exclude fields:

curl -s "http://example.company.com/search/ExampleCo/ExampleOrg/ExampleFolder?token=1234567890&daterange=20210701-20210702&format=csv&output=summary&fields=all,-agentid"

In the preceding example, the output=summary&fields=all,-agentid parameters include all (both voci and CLIENT-DATA) fields except for agentid in search results.

When specifying values for the fields parameter using a POST request, the submitted JSON data must list fields as a JSON-formatted list, even if there is only one value, as in the following example POST request:

curl -H 'Content-type: application/json' -d '{"output":"summary","fields":["all","-datetime","-requestid","-diarization"]}' -X POST 'http://example.company.com/search/ExampleCo/ExampleOrg/ExampleFolder?token=1234567890'

In the preceding example, {"output":"summary","fields":["all","-datetime","-requestid","-diarization"]} is a JSON-formatted set of parameters that includes all fields, except for the excluded fields datetime, requestid, and diarization. These parameters may also be submitted in a JSON file, as in the following example:

curl -H 'Content-type: application/json' -d @params.json -X POST 'http://example.company.com/search/ExampleCo/ExampleOrg/ExampleFolder?token=1234567890'

In the preceding example, JSON-formatted parameters are replaced with a reference to the file containing them, which in this case is named params.json. Note that using a file with cURL requires inserting the @ symbol before the filename.

For additional examples of using the /search endpoint, refer to Using the /search API with cURL and Using the /search API with Python.