Table of Contents

API : PBX : Call audio quality : Summary

Introduction

Aggregates a window into groups, turning individual bad calls into “this customers Mitel in reception has been bad all week” - the form you actually want before phoning somebody.

Scope, verdicts, finding codes and thresholds are described on Call audio quality.

Request

URL https://api.telecomx.dk/pbx/quality/summary
Method GET
Access level ADMIN, or RESELLER_ADMIN with the TELE employee feature. TX staff only - see Call audio quality.
Query from Date Start of the window. Optional, defaults to 24 hours ago.
to Date End of the window. Optional, defaults to now.
customer Id Customer to report on. Optional - omit it to span every customer.
extension Id Only calls involving this extension. Optional.
employee Id Only calls involving this employees extensions. Optional.
pbx String Only calls handled by this PBX server, e.g. pbx12. Optional.
groupBy String CUSTOMER, PBX, PARTY or MODEL. Optional, default CUSTOMER.
minMeasured Number Drop groups with fewer measured calls or legs than this. Optional, default 1.
minDurationSeconds Number Ignore calls shorter than this. Optional, default 5.
limit Number Maximum number of groups to return (1-500). Optional, default 100.

The same window limits apply as for Calls: 31 days for a single customer, 7 days across customers. Responses are cached for 5 minutes.

Grouping

groupBy Counts Answers
CUSTOMER Calls Which customer is suffering.
PBX Calls Whether the trouble is confined to one PBX host - i.e. our problem rather than theirs.
PARTY Legs Which extension or number is the repeat offender. Keyed by customer and party identity.
MODEL Legs Whether a whole phone model is misbehaving, e.g. a firmware fault. Keyed by the SIP phone model id; model carries the readable name.

CUSTOMER and PBX count calls, collapsing each call to its worst leg. PARTY and MODEL count legs, because the question there is about one device rather than one conversation.

PARTY keys on the identity the CDR records - the extension when the party has one, otherwise the phone number - and on the customer, since an extension number means nothing across customers. It deliberately does not key on the device: a WebRTC softphone is recreated on every connect, so a device-keyed grouping would scatter one persons calls across many rows. Use MODEL when the question is about equipment rather than about a person.

Query examples

https://api.telecomx.dk/pbx/quality/summary?groupBy=CUSTOMER&minMeasured=20
https://api.telecomx.dk/pbx/quality/summary?customer=1234567890ABCDEF12345678&groupBy=PARTY
https://api.telecomx.dk/pbx/quality/summary?groupBy=MODEL&from=2026-08-17T00:00:00.000Z&to=2026-08-24T00:00:00.000Z

Response

JSON object
groupBy String The grouping that was applied.
from Date Start of the window that was actually used.
to Date End of the window that was actually used.
groups Array The groups, most affected first (see below).
groups[] object
key String The group key: a customer id, a PBX hostname, a phone model, or - for PARTY - an extension id or phone number.
customer Id Customer the group belongs to. Only set for PARTY.
customerName String Name of that customer. Set for CUSTOMER and PARTY.
name String Readable name of the party, when one could be resolved.
number String Extension number, when the party is an extension.
model String Phone model, when the party is a SIP phone.
kind String Party kind: SIP_PHONE, MOBILE, EXTERNAL, EXTENSION, SYSTEM or UNKNOWN.
measured Number Calls (or legs) in this group that could be judged at all.
degraded Number Of those, how many were DEGRADED.
bad Number Of those, how many were BAD.
noAudio Number Of those, how many had no inbound audio at all.
affected Number Degraded, bad and no-audio together.
affectedRatio Number affected divided by measured, rounded to three decimals.

Always read affectedRatio next to measured. Three bad calls out of four means nothing beside three out of nine hundred - raise minMeasured before acting on a percentage.

Example

{
  "groupBy": "MODEL",
  "from": "2026-08-17T00:00:00.000Z",
  "to": "2026-08-24T00:00:00.000Z",
  "groups": [
    {
      "key": "Yealink-T46S",
      "customer": null,
      "customerName": null,
      "name": null,
      "number": null,
      "model": "Yealink-T46S",
      "kind": "SIP_PHONE",
      "measured": 41,
      "degraded": 6,
      "bad": 35,
      "noAudio": 0,
      "affected": 41,
      "affectedRatio": 1
    },
    {
      "key": "Mitel-6867i",
      "measured": 862,
      "degraded": 9,
      "bad": 2,
      "noAudio": 0,
      "affected": 11,
      "affectedRatio": 0.013
    }
  ]
}

Errors

Error code Message Description
401 unauthorized Missing or invalid token
403 access_denied Not TX staff: below RESELLER_ADMIN, or RESELLER_ADMIN without the TELE employee feature
404 extension Extension not found
422 from Invalid date range, or window wider than the limit for this scope
500 internal_error <Unspecified>