HCC Docs

Reports

Rep performance

GET /v1/reports/reps reports:read

Per rep: calls handled (inbound and outbound), talk time, average handle time, wrap-up, missed offers, occupancy and time per state.

Query

  • from string

    Start of the range (inclusive), ISO 8601. Default: 7 days before to. At most 92 days

  • to string

    End of the range (exclusive), ISO 8601. Default: now

  • repId string | string[]

    Only these reps (rep_…)

  • queue string | string[]

    Only these queues, by name

  • campaign string | string[]

    Only these campaigns, by name. Only the campaign report reads it

  • direction "inbound" | "outbound"

    Only inbound or outbound calls

  • format "json" | "csv"

    csv: answer with CSV, like Accept: text/csv

Responses

  • 200

    The report, or its rows as CSV

    Fields
    • data RepReportRow[] required
      Fields
      • repId string required
      • name string required
      • email string required
      • handled integer required

        Calls connected: inbound + outbound

      • inbound integer required

        Queue calls the rep answered

      • outbound integer required

        The rep's outbound calls the customer answered

      • talkSeconds number required

        Connect to hang-up, hold included

      • wrapUpSeconds number required

        Wrap-up after the handled calls

      • ahtSeconds number | null required

        Average handle time: (talk + wrap-up) ÷ handled

      • avgWrapUpSeconds number | null required
      • missedOffers integer required

        Offers the rep let expire

      • occupancy number | null required

        (on call + wrap-up) ÷ (available + on call + wrap-up) 0 to 1.

      • states RepStateSeconds required

        Seconds in each rep state within the range

    • totals object required
      Fields
      • handled integer required

        Calls connected: inbound + outbound

      • inbound integer required

        Queue calls the rep answered

      • outbound integer required

        The rep's outbound calls the customer answered

      • talkSeconds number required

        Connect to hang-up, hold included

      • wrapUpSeconds number required

        Wrap-up after the handled calls

      • ahtSeconds number | null required

        Average handle time: (talk + wrap-up) ÷ handled

      • avgWrapUpSeconds number | null required
      • missedOffers integer required

        Offers the rep let expire

      • occupancy number | null required

        (on call + wrap-up) ÷ (available + on call + wrap-up) 0 to 1.

      • states RepStateSeconds required

        Seconds in each rep state within the range

    • range ReportRange required
      Fields
      • from string required
      • to string required
      • timezone string required

        The workspace's time zone: buckets use it

      • environment "live" | "test" required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Queue performance

GET /v1/reports/queues reports:read

Per queue, from the visits that entered it: offered, answered, abandoned, overflowed, service level, average speed of answer and longest wait. repId does not apply.

Query

  • from string

    Start of the range (inclusive), ISO 8601. Default: 7 days before to. At most 92 days

  • to string

    End of the range (exclusive), ISO 8601. Default: now

  • repId string | string[]

    Only these reps (rep_…)

  • queue string | string[]

    Only these queues, by name

  • campaign string | string[]

    Only these campaigns, by name. Only the campaign report reads it

  • direction "inbound" | "outbound"

    Only inbound or outbound calls

  • format "json" | "csv"

    csv: answer with CSV, like Accept: text/csv

Responses

  • 200

    The report, or its rows as CSV

    Fields
    • data QueueReportRow[] required
      Fields
      • queue string required
      • offered integer required

        Visits that entered the queue, leaving out outsideHours

      • answered integer required
      • abandoned integer required

        The caller hung up while waiting

      • abandonmentRate number | null required

        abandoned ÷ offered 0 to 1.

      • overflowed integer required

        Left by overflow, or nobody was on

      • outsideHours integer required

        Turned away by the queue's business hours: in no other count

      • answeredWithin integer required

        Answered within the threshold

      • serviceLevel number | null required

        answeredWithin ÷ (answered + abandoned + overflowed) 0 to 1.

      • asaSeconds number | null required

        Average speed of answer

      • longestWaitSeconds number | null required
      • serviceLevelSeconds integer required

        The queue's threshold (serviceLevel.seconds, default 20)

      • serviceLevelTarget number required
    • totals object required
      Fields
      • offered integer required

        Visits that entered the queue, leaving out outsideHours

      • answered integer required
      • abandoned integer required

        The caller hung up while waiting

      • abandonmentRate number | null required

        abandoned ÷ offered 0 to 1.

      • overflowed integer required

        Left by overflow, or nobody was on

      • outsideHours integer required

        Turned away by the queue's business hours: in no other count

      • answeredWithin integer required

        Answered within the threshold

      • serviceLevel number | null required

        answeredWithin ÷ (answered + abandoned + overflowed) 0 to 1.

      • asaSeconds number | null required

        Average speed of answer

      • longestWaitSeconds number | null required
    • range ReportRange required
      Fields
      • from string required
      • to string required
      • timezone string required

        The workspace's time zone: buckets use it

      • environment "live" | "test" required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Outbound performance

GET /v1/reports/outbound reports:read

From the dial attempts of reps, campaigns and the API: dials, connects, connect rate, talk, Do Not Call blocks and dispositions, per rep, with calls the API placed with no rep in a row of their own (noRep). queue and direction do not apply.

Query

  • from string

    Start of the range (inclusive), ISO 8601. Default: 7 days before to. At most 92 days

  • to string

    End of the range (exclusive), ISO 8601. Default: now

  • repId string | string[]

    Only these reps (rep_…)

  • queue string | string[]

    Only these queues, by name

  • campaign string | string[]

    Only these campaigns, by name. Only the campaign report reads it

  • direction "inbound" | "outbound"

    Only inbound or outbound calls

  • format "json" | "csv"

    csv: answer with CSV, like Accept: text/csv

Responses

  • 200

    The report, or its rows as CSV

    Fields
    • data OutboundReportRow[] required
      Fields
      • repId string | null required
      • name string | null required
      • noRep boolean required

        The row of calls placed through the API with no rep. Another row with a null repId is dials whose rep is gone, or a campaign's that no rep ended up on.

      • dials integer required

        Dial attempts placed

      • connects integer required

        Placed calls the customer answered

      • connectRate number | null required

        connects ÷ dials 0 to 1.

      • avgTalkSeconds number | null required
      • blockedDnc integer required

        Refused: on the Do Not Call list

      • refused integer required

        All refused dials

      • dispositions object required
    • totals object required
      Fields
      • dials integer required

        Dial attempts placed

      • connects integer required

        Placed calls the customer answered

      • connectRate number | null required

        connects ÷ dials 0 to 1.

      • avgTalkSeconds number | null required
      • blockedDnc integer required

        Refused: on the Do Not Call list

      • refused integer required

        All refused dials

      • dispositions object required
    • range ReportRange required
      Fields
      • from string required
      • to string required
      • timezone string required

        The workspace's time zone: buckets use it

      • environment "live" | "test" required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Campaign performance

GET /v1/reports/campaigns reports:read

Per campaign: dials, connects, right-party conversations, machines, no answers, talk and dispositions, from the dials placed in the range; and the leads that left in the range, why, and the goal rate. Only campaign filters it: repId, queue and direction do not apply.

Query

  • from string

    Start of the range (inclusive), ISO 8601. Default: 7 days before to. At most 92 days

  • to string

    End of the range (exclusive), ISO 8601. Default: now

  • repId string | string[]

    Only these reps (rep_…)

  • queue string | string[]

    Only these queues, by name

  • campaign string | string[]

    Only these campaigns, by name. Only the campaign report reads it

  • direction "inbound" | "outbound"

    Only inbound or outbound calls

  • format "json" | "csv"

    csv: answer with CSV, like Accept: text/csv

Responses

  • 200

    The report, or its rows as CSV

    Fields
    • data CampaignReportRow[] required
      Fields
      • campaign string required
      • dials integer required

        Dial attempts placed in the range

      • connects integer required

        Dialed calls answered, and not by a machine

      • connectRate number | null required

        connects ÷ dials 0 to 1.

      • rightPartyConversations integer required

        Connects that were a real conversation: not ones that found no rep. A machine nobody asked the carrier about counts, so a flow with no onVoicemail can overstate this

      • machine integer required

        Dialed calls a machine answered

      • voicemailsLeft integer required

        The machines onVoicemail left a message on: part of machine

      • noAnswer integer required

        Dialed calls nobody answered

      • avgTalkSeconds number | null required

        Connect to the call's end, per connect

      • dispositions object required

        The dispositions of the range's dialed calls

      • leadsLeft integer required

        Leads that left in the range

      • exitReasons object required

        Leads that left in the range, per reason

      • conversions integer required

        Leads that left with reason goal

      • goalRate number | null required

        conversions ÷ leadsLeft 0 to 1.

    • totals object required
      Fields
      • dials integer required

        Dial attempts placed in the range

      • connects integer required

        Dialed calls answered, and not by a machine

      • connectRate number | null required

        connects ÷ dials 0 to 1.

      • rightPartyConversations integer required

        Connects that were a real conversation: not ones that found no rep. A machine nobody asked the carrier about counts, so a flow with no onVoicemail can overstate this

      • machine integer required

        Dialed calls a machine answered

      • voicemailsLeft integer required

        The machines onVoicemail left a message on: part of machine

      • noAnswer integer required

        Dialed calls nobody answered

      • avgTalkSeconds number | null required

        Connect to the call's end, per connect

      • dispositions object required

        The dispositions of the range's dialed calls

      • leadsLeft integer required

        Leads that left in the range

      • exitReasons object required

        Leads that left in the range, per reason

      • conversions integer required

        Leads that left with reason goal

      • goalRate number | null required

        conversions ÷ leadsLeft 0 to 1.

    • range ReportRange required
      Fields
      • from string required
      • to string required
      • timezone string required

        The workspace's time zone: buckets use it

      • environment "live" | "test" required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Dispositions per rep and queue

GET /v1/reports/dispositions reports:read

Calls with a disposition, counted per disposition, rep and queue.

Query

  • from string

    Start of the range (inclusive), ISO 8601. Default: 7 days before to. At most 92 days

  • to string

    End of the range (exclusive), ISO 8601. Default: now

  • repId string | string[]

    Only these reps (rep_…)

  • queue string | string[]

    Only these queues, by name

  • campaign string | string[]

    Only these campaigns, by name. Only the campaign report reads it

  • direction "inbound" | "outbound"

    Only inbound or outbound calls

  • format "json" | "csv"

    csv: answer with CSV, like Accept: text/csv

Responses

  • 200

    The report, or its rows as CSV

    Fields
    • data DispositionReportRow[] required
      Fields
      • disposition string required
      • repId string | null required

        Who recorded it, or the call’s rep

      • name string | null required
      • queue string | null required

        The call's last queue

      • count integer required
    • totals object required
      Fields
      • count integer required
      • byDisposition object required
    • range ReportRange required
      Fields
      • from string required
      • to string required
      • timezone string required

        The workspace's time zone: buckets use it

      • environment "live" | "test" required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

A metric over time

GET /v1/reports/timeseries reports:read

Hourly or daily buckets in the workspace's time zone; every bucket of the range is present. Hourly series cover at most 31 days.

Query

  • from string

    Start of the range (inclusive), ISO 8601. Default: 7 days before to. At most 92 days

  • to string

    End of the range (exclusive), ISO 8601. Default: now

  • repId string | string[]

    Only these reps (rep_…)

  • queue string | string[]

    Only these queues, by name

  • campaign string | string[]

    Only these campaigns, by name. Only the campaign report reads it

  • direction "inbound" | "outbound"

    Only inbound or outbound calls

  • metric "calls" | "service_level" | "wait_time" | "handled" | "dials" | "states" required
  • interval "hour" | "day"

Responses

  • 200

    The series

    Fields
    • data TimeseriesPoint[] required
      Fields
      • bucket string required

        The bucket's start

    • metric "calls" | "service_level" | "wait_time" | "handled" | "dials" | "states" required
    • interval "hour" | "day" required
    • target number

      service_level: the queues’ (lowest) target

    • range ReportRange required
      Fields
      • from string required
      • to string required
      • timezone string required

        The workspace's time zone: buckets use it

      • environment "live" | "test" required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Headline numbers, against the previous period

GET /v1/reports/summary reports:read

Calls, service level, abandonment rate, average speed of answer, average handle time and connect rate for the range, and for the range of the same length right before it.

Query

  • from string

    Start of the range (inclusive), ISO 8601. Default: 7 days before to. At most 92 days

  • to string

    End of the range (exclusive), ISO 8601. Default: now

  • repId string | string[]

    Only these reps (rep_…)

  • queue string | string[]

    Only these queues, by name

  • campaign string | string[]

    Only these campaigns, by name. Only the campaign report reads it

  • direction "inbound" | "outbound"

    Only inbound or outbound calls

Responses

  • 200

    The KPIs

    Fields
    • data object required
      Fields
      • current ReportKpis required
      • previous ReportKpis required
      • previousRange object required
    • range ReportRange required
      Fields
      • from string required
      • to string required
      • timezone string required

        The workspace's time zone: buckets use it

      • environment "live" | "test" required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code