Skip to content
FlySIPFlySIP Docs

Get the DID summary report

getDidSummaryReport adds up the calls that arrived on your DIDs over a period: one row per DID, per account or sub-customer the DID is assigned to, per charging group, per country of the caller or per call result, with revenue, cost and profit in one currency. It returns the same figures as the DID Summary Reports screen.

Any customer with the DID Pool right may call it, the root customer included. The report covers the DID calls of your own accounts and of your direct sub-customers, the same calls the DIDs Call Records screen shows you. The method supports trusted mode with i_customer and reads from the database replica, so the newest calls can be missing for a few seconds.

Parameters

Section titled “Parameters”
Name Type Required Description
start_date string no Start of the period, UTC, for example 2026-09-01 00:00:00. The formats of the summary reports are also accepted. Default: today 00:00 UTC
end_date string no End of the period, UTC, included. Default: now
group_by string no What one row stands for, see the values of group_by. Default: did
scope string no all (default), accounts for the DIDs of your own accounts only, customers for the DIDs of your sub-customers only
i_account int no Report only this account of yours. Sets scope to accounts
i_sub_customer int no Report only this sub-customer. Sets scope to customers. Do not send it together with i_account
i_did int no Report only this DID
did string no Report only DIDs that match this pattern. With did_clause 0 and 1 use % for any characters and _ for one; separate several patterns with commas or spaces, up to 50
did_clause int no How did is applied: 0 matches (default), 1 does not match, 2 matches the regular expression (SQL SIMILAR TO), 3 does not match it
result string no Which calls count, see the values of result. Default: all
cdr_currency string no ISO 4217 code of the currency of all amounts. Amounts are converted with your current exchange rates. Default: your base currency
sort_by string no name (the grouping columns), number_of_calls, connected_calls, duration, billed_duration, revenue, cost or profit. Default: duration
sort_dir string no asc or desc (default)
limit int no Return at most this many rows. Default: 0, all rows
offset int no Skip this many rows. Default: 0

Values of group_by

Section titled “Values of group_by”

The numbers 0 to 6 are accepted instead of the names, in this order.

Value One row per Fields added to the row
did DID i_did, did
did_owner DID and the account or sub-customer that received the call i_did, did, owner_type (account or customer), i_owner, owner_name
owner Account or sub-customer owner_type, i_owner, owner_name
charging_group Charging group i_dids_charging_group (0 for none), charging_group (its name)
cli_country Country of the caller’s number country_iso, country
cli_country_description Destination of the caller’s number prefix, country_iso, country, description
result Call result result, result_text

The charging group is the one attached to the DID now, not at the time of the call; when the DID was delegated to you, the group of the delegation wins over the group of the pool entry. The caller’s country is found by the longest destination prefix that matches the CLI.

Values of result

Section titled “Values of result”

The classic codes in the second column are accepted as well.

Value Code Counts
all 1 Every call, failed ones included (default)
incomplete 2 Calls that were not answered, without the internal errors
non_zero_and_errors 3 Calls with a duration above zero and calls that failed with an internal error
non_zero 4 Calls with a duration above zero
complete 5 Answered calls
errors 6 Calls that failed with an internal error

Returns

Section titled “Returns”
Name Type Description
result string OK
report_data array The rows, see below
total_rows int Number of rows of the whole report, regardless of limit and offset
totals struct number_of_calls, connected_calls, duration, billed_duration, revenue, cost and profit of the whole report, regardless of limit and offset
currency string Currency of all amounts
start_date, end_date string The period used, UTC, YYYY-MM-DD HH:MM:SS
group_by, scope, sort_by, sort_dir string The values used, as names
rights struct is_root and did_pool, booleans: whether you are the root customer and have the DID pool

Each row of report_data has the fields of its group_by and these figures:

Name Type Description
number_of_calls int Number of calls
connected_calls int Calls with a duration above zero
duration double Total duration, seconds
billed_duration double Total billed duration, seconds
revenue double What you charged your account or sub-customer for the calls
cost double What the same calls cost you: the DID vendor’s charge for the root customer, your wholesaler’s charge for a reseller
profit double revenue minus cost

result_text is OK for an answered call, SIP error 486 and the like for a SIP failure, Timeout for a call that got no final answer, and the description of the error for an internal error.

Example

Section titled “Example”
request
call("getDidSummaryReport", {
    "start_date": "2026-09-01 00:00:00",
    "end_date": "2026-09-10 23:59:59",
    "group_by": "did_owner",
    "result": "non_zero",
    "limit": 50,
})
response
{
    "result": "OK",
    "report_data": [
        {
            "i_did": 512,
            "did": "380441234567",
            "owner_type": "account",
            "i_owner": 3092,
            "owner_name": "1001",
            "number_of_calls": 92,
            "connected_calls": 92,
            "duration": 3120.0,
            "billed_duration": 3300.0,
            "revenue": 12.4,
            "cost": 4.1,
            "profit": 8.3,
        },
        # … up to 50 rows
    ],
    "total_rows": 17,
    "totals": {
        "number_of_calls": 340,
        "connected_calls": 340,
        "duration": 12034.0,
        "billed_duration": 12600.0,
        "revenue": 51.2,
        "cost": 17.9,
        "profit": 33.3,
    },
    "currency": "USD",
    "start_date": "2026-09-01 00:00:00",
    "end_date": "2026-09-10 23:59:59",
    "group_by": "did_owner",
    "scope": "all",
    "sort_by": "duration",
    "sort_dir": "desc",
    "rights": {"is_root": False, "did_pool": True},
}

Errors

Section titled “Errors”
faultCode faultString Cause
401 You do not have permissions to use this API call. The DID pool is not enabled for your customer
402 Unknown group_by: city, Unknown scope: all_dids, Unknown result filter: ok, Unknown sort_by: margin A value outside the lists above
402 i_account and i_sub_customer are mutually exclusive. Both were sent
402 start_date must not be later than end_date. The period is reversed
402 Unrecognized date format in start_date. start_date or end_date is in none of the accepted formats
402 Parameter limit must be an integer., Parameter i_did is out of range. A numeric parameter is not a number, or is negative or zero where an ID is expected
402 Unknown clause: 4, Too many patterns (max 50)., Unbalanced ")" in the pattern. did_clause is not 0 to 3, or the did pattern is not valid
404 Customer not found. The customer named by i_customer in trusted mode does not exist
Section titled “Related”