NUACOM API

Calls

Reports

Reports are the account's call history aggregated or filtered for one question: which callers still need a call back, who calls most, when the lines are busiest, how much each extension handles, and which queue calls an agent let ring. This group holds the missed-call report (a user view, an account-wide view and a CSV export of each), the top-callers report, the busy-hours reports by hour, day and month, the two extension-usage reports and the queue skipped-calls report. All but the last one are built from the same rows as Call Logs and take the same filters; the emailed summary of the missed-call report is configured in Reports / Missed Call Follow-up.

Workflow (what the portal does)

The call-log reports read their inputs from the query string (GET) or the request body (POST), as plain comma-separated strings. The period is from_date and to_date, see Period and filters; every other call-log filter (type, extensions, queues, number, search_for, …) applies too.

  1. Missed calls to follow up: GET /v2/missed-call-report lists inbound calls that were not answered. The portal sends type=missed,include_voicemail,include_playback,group_missed_calls (unanswered inbound calls, including those that ended in voicemail or an announcement, one row per caller who has not been called back) and empty=src_extension (callers from outside the account only), with from_date, to_date, sort_by (call_date, from, from_ext, to or to_ext; call_date by default), sort_dir (ASC by default), per_page (default 25, no maximum) and page (default 1). The answer is {"_embedded": [rows], "_links": {…}, "page_count": <current page>, "page_size", "total_items"}; _links holds next and last while there are more pages and prev and first after the first one, and a Link header repeats them. Each row carries id, call_date, direction, status and last_app (how and where the call ended), the caller as from / from_local / from_name, the number dialled as to / to_local / to_name, the extensions involved as from_ext / from_extension and to_ext / to_extension (number and name), the queue the call was waiting in as call_in_queue / call_in_queue_name, and original_sip_call_id.

  2. Account-wide view: GET /v2/admin-missed-call-report takes the same inputs and answers the same shape, but ignores the caller's call-log permissions: every missed call in the account.

  3. CSV export: POST /v2/missed-call-report-export and POST /v2/admin-missed-call-report-export take the same filters (the portal posts from_date, to_date, type and empty) and answer 204: the file is built in the background and emailed to the user behind the token, newest call first, with the columns Date, Call Type, From Name, From, To Name, To, To Ext, To Ext Name, Queue No and Queue Name. Dates in the file are Y-m-d H:i:s in the X-Timezone you send (an IANA name; anything else is replaced by Europe/Dublin), or in your profile timezone without it. The user export sees what the user sees; the admin export covers the whole account.

  4. Top callers: GET /v2/top-callers-report with from_date, to_date and type: incoming ranks the callers of answered inbound calls by their number, outgoing the numbers dialled on answered outbound calls; add missed or unanswered to count the unanswered ones as well (type=incoming,missed). The answer is {"_embedded": [{"group": "+353861234567 - Jane Doe", "calls_count": 12, "contacts": {…}}, …], "total_items": 20}: at most 20 rows, most calls first. group is the number alone when nothing names it, number - name when a phonebook or integration contact matches (contacts then carries that contact) or when the number is a system short code; withheld callers appear as … - Anonymous.

  5. Busy hours: POST /v2/hourly-busy-hours-report, POST /v2/daily-busy-hours-report and POST /v2/monthly-busy-hours-report count answered and missed calls per hour, day or month of the period. The portal sends from_date, to_date, type (incoming,missed,include_voicemail,include_playback by default, that is every inbound call) and optionally number to look at one of the account's numbers. The answer is an array with one entry per bucket of the whole period, zero-filled: [{"period": "2026-05-04 09:00", "answered_value": 14, "missed_value": 3}, …]; period is Y-m-d H:00, Y-m-d or Y-m. answered_value counts calls with status ANSWERED, missed_value every other status (NO ANSWER, BUSY, FAILED).

  6. Extension usage: POST /v2/extension-call-direction-report counts calls per extension and POST /v2/extension-call-duration-report sums their duration in seconds. Inputs are from_date, to_date, extensions (comma-separated extension numbers; empty for all of them) and type (the portal sends outgoing,unanswered,incoming,missed,include_voicemail,include_playback,include_internal when nothing is ticked). Only calls with an extension on at least one side are counted. The answer is an array with one object per extension, ordered by extension number; the duration report names its columns Voicemail_duration … Total_duration:

    [{"Extension": "Jane Doe - 101", "Voicemail": 0, "Playback": 1, "Internal": 3, "Incoming": 12, "Missed": 2, "Outgoing": 8, "Unanswered": 1, "Total": 27}]

    Extension is name - number, or the bare number for an extension without a name. A call counts once for the extension that made it and once for the one that received it, so an internal call appears in two rows. Durations are the connected time of answered calls and the ring time of the others.

  7. Queue skipped calls: GET /v2/reports/queue-skipped-calls with queue (queue number), from and to (both required, to after from) and optionally agent (extension number) returns the queue events of every call in that queue that an agent (that agent, when given) let ring without answering. The answer is a plain array ordered by call, then by time, one entry per event: {"call_id": "1651753116.134", "queue": "100", "agent": "10", "caller_id": "0861234567", "status": "RINGNOANSWER", "event_date": "May 4 2026 09:12:30"}. The portal opens it from the Queue Reports page as the call flow of a queue or of an agent; see Queues for queue numbers and Reading the queue events for status.

# Callers of May 2026 still waiting for a call back, Dublin time, 25 per page
curl 'https://api.api-nuacom.com/v2/missed-call-report?from_date=2026-05-01%2000:00:00&to_date=2026-05-31%2023:59:59&type=missed,include_voicemail,include_playback,group_missed_calls&empty=src_extension&per_page=25&page=1' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'X-Timezone: Europe/Dublin'

Period and filters

  • from_date and to_date take Y-m-d (expanded to 00:00:00 and 23:59:59) or Y-m-d H:i:s. They are wall-clock values read in the X-Timezone header (or timezone parameter) if you send one, otherwise in the profile timezone of the user behind the token, otherwise Europe/Dublin; see Dates and timezones.
  • Send both. With only one, or none, the report covers the last month: every call since one month before now. There is no maximum range in the API; the portal limits its own date pickers (31 days on the missed-call report).
  • Output: call_date and the busy-hours period are wall-clock Y-m-d H:i:s in your profile timezone on the legacy contract. With the ISO dates option, call_date becomes ISO 8601 in the X-Timezone offset (UTC by default) and period is labelled in the timezone your dates were read in. The CSV exports keep Y-m-d H:i:s.
  • type is a comma-separated list. Naming a direction excludes the calls that ended in voicemail or in an announcement unless you add the include_* values; omitted altogether, every call counts.
type value Selects
incoming inbound calls that were answered
missed inbound calls that were not answered
outgoing outbound calls that were answered
unanswered outbound calls that were not answered
include_internal calls between two extensions
include_voicemail, include_playback keep the calls that ended in voicemail or in an announcement
group_missed_calls one row per caller, keeping only callers who were not called back, and did not call again and get through, within the period
  • extensions (as source or destination extension), queues, number (as caller or as number dialled; one or two values match as substrings, three or more exactly), incoming_number, outgoing_number and search_for narrow the calls as on the call log; empty=src_extension keeps calls from outside the account.

Reading the queue events

Every event of a skipped call is listed, not only the skip. status is one of:

status Meaning
RINGNOANSWER the agent was rung and declined, or the ring timed out
COMPLETEAGENT, COMPLETECALLER the call was answered by an agent and then ended, hung up by the agent or by the caller
ABANDON the caller hung up while waiting
EXITWITHTIMEOUT the call timed out in the queue and moved to another step or hung up
TRANSFER the call was transferred to another agent or number

The other values (inQue, CONNECT, EXITWITHKEY, EXITEMPTY) are the queue events they name. call_id is shared by every event of the same call; queue and agent are the queue number and the extension number; caller_id is the caller's number as the queue saw it, empty on some events; event_date is M j Y H:i:s in the caller's profile timezone.

Roles and access

  • Every endpoint is open to any authenticated user, except POST /v2/admin-missed-call-report-export, which needs an account admin and answers 403 with the body "Forbidden" otherwise.
  • The user reports (missed calls and its export, top callers, busy hours, extension usage) follow the call-log visibility rules: an admin, or a user whose call-log permission is "all", sees the whole account; everyone else only the calls on their own extension and on the numbers, extensions and queues granted to them, and with no grants the answer is empty, not 403.
  • The account-wide missed-call list and export, and the queue skipped-calls report, cover the whole account regardless of grants.
  • The ISO dates option (per account) changes the date formats as described above; the skipped-calls event_date is always M j Y H:i:s in the caller's profile timezone and ignores X-Timezone.

Pitfalls

  • The generated reference shows no parameters for the call-log reports: they read the raw request. Use the inputs above, as comma-separated strings (extensions=101,102, not extensions[]).
  • The missed-call endpoints do not add the missed filter themselves. Without type=missed they list every call of the period; without group_missed_calls every unanswered leg of a call is a row, called back or not.
  • An unparsable date silently becomes 1970-01-01, and a value carrying a UTC offset is shifted again by the input timezone. Send wall-clock values and set X-Timezone.
  • page_count is the current page, not the number of pages; paginate on total_items and page_size. _links is [] on a single page and an object otherwise.
  • Missed-call rows whose caller is not a dialable number (withheld numbers, park and speed-dial codes) are dropped after pagination: a page can hold fewer rows than page_size, and total_items is only corrected when everything fits on one page.
  • Missed-call rows carry no call_id or call_unique_id; to reach the recording or notes of a call, find it on GET /v2/call-log by date and number.
  • Exports are asynchronous and arrive by email; the request returns no job id and answers 204 even when nothing matches. They ignore sort_by and, unlike the call-log export, have no row limit.
  • Top callers always answers total_items: 20, whatever the number of rows. incoming and outgoing count answered calls only, and numbers shorter than six characters (extensions, short codes) are dropped. Without type the report groups every call, internal ones included, by the number dialled.
  • Busy hours counts whatever type selects: omit it and outbound and internal calls are counted too.
  • On the extension-usage reports extensions=all answers an empty array; omit the parameter, or send it empty, to get every extension. The duration report fails with 500 when extensions is missing altogether: always send it, empty if need be.
  • Queue skipped calls: from and to are compared with the stored event time as given, X-Timezone is ignored, and a date-only to ends at midnight, so send to=2026-05-31 23:59:59. agent picks which calls are included, not which rows: the events of the other agents on those calls are listed too. Validation errors answer 422 with errors alone, no message.