Synopsis

GET /appstats/$co_short/$org_short/$app_name?token=$token&$options...
GET /appstats/$co_short/$org_short/$app_name/$folder?token=$token&$options...

$co_short

Company short name used to filter the request.

$org_short

Organization short name used to filter the request.

$app_name

Name of the application to be queried.

$folder

Folder used to filter the request.

$token

Authorization token with the required read or write permissions for the request.

$options

Optional parameters used to further refine the request and results.

Optional parameters

daterange=$start-$end

Filters the request by the dates specified in the range [$start, $end]. Values for $start and $end are optional, but the hyphen between them is required.

The range specified by $start and $end may be expressed using any combination of years, months, days, hours, minutes, and seconds, expressed as YYYYMMDD[HHmmss]. Date ranges are always assumed to be positive (where $start is less than $end).

daterange filters by values in the transcript record's datetime field. Data for the datetime field is stored using the organization's time zone, which may vary by organization.

No verification is done to ensure that daterange values are correct; invalid date ranges will simply return no values. If $start is not specified, a default value of 01 January, 1900 is used. If $end is not specified, the current date is used.

category=CATEGORY

Enables you to return Agent Stats for a particular category. To specify a lower-level category, specify CATEGORY as a string that contains the full "path" to the lower-level category, as a period-separated list. For example, if querying an app that uses the Agent Scorecard template, a valid category name would be Communication Skills.Client Informed . Querying a particular category will always also return scores for the category's upper levels.

depth=DEPTH

Enables you to specify how many lower level categories you would like to return in results:

0

Return only the level of the category specified. This is the default value if the category option is specified.

n

Where n is a positive non-zero integer, return the specified number of lower levels of the category

-1

Return all levels of category stats. This is the default value if no category option is specified.

agents=AGENTID

Enables you to specify the agent(s) for which to retrieve scores. If you want to retrieve scores for more than one agent, separate the AGENTIDs with commas. For example:

agents=348,227,042

zeros

Whether or not to include in the JSON that is returned categories for which the agent did not receive any score.

Note: This parameter refers to returning zero scores for CATEGORIES. If a date in the specified daterange does not contain any calls, no scores of any sort will be returned for that date.

true

Include categories in which the agent did not score, and report the score for that category as zero.

false

Exclude (from the JSON that is returned) categories in which the agent did not receive a score.

Example cURL requests

The following example retrieves scores from an application named Agent ScoreCard for records in the single-day daterange of 20210925 (September 25, 2021) in the Docs company and Docs-Testing organization.

curl -s 'http://example.company.com/appstats/Docs/Docs-Testing/Agent%20Scorecard?token=TOKEN&daterange=20210925'

The following example retrieves category scores for lower-level application categories. The request specifies a depth of 1, so it retrieves only the first level of category scores.

curl -s 'http://example.company.com/appstats/Docs/Docs-Testing/Agent%20Scorecard\
    ?token=TOKEN&daterange=20210925&category=Communication%20Skills.Client%20Informed&depth=1'

Python example

Use the api_get_test.py with these command-line arguments:

python api_get_stats.py $host $token /appstats/$co_short/$org_short/$app_name '&daterange=20211005&category=Politeness'

This call uses the daterange parameter to limit results to those from files processed on a single date (October 5, 2021), and includes only the Politeness category.

$host

Hostname or URL for the system running V‑Spark.

$token

Authorization token with the required read or write permissions for the request.

$co_short

Company short name used to filter the request.

$org_short

Organization short name used to filter the request.

$app_name

Name of the application to be queried.

Example JSON output

This example output shows application category scores for one call from an agent with identifier 001. Categories without a score are not included in JSON output.

[
  {
    "date": "20170925",
    "agents": 3,
    "001": {
       "calls": 1,
        "overall": {
          "ncalls": 1,
          "hitmiss": "1.0000",
          "coverage": "0.2890",
          "duration": "0:11:55",
          "silence": "0:03:13"
         },
         "Communication Skills": {
            "ncalls": 1,
            "hitmiss": "1.0000",
            "coverage": "0.5667",
            "duration": "0:11:55",
            "silence": "0:03:13"
          },
          "Effectiveness": {
            "ncalls": 1,
            "hitmiss": "1.0000",
            "coverage": "0.4000",
            "duration": "0:11:55",
            "silence": "0:03:13"
          },...
      },...
   }
]