API Version: Development

Reference

/

REST API

/

Call-data

/

Call Reports

   
  • Call Reports
  • Permissions
  • command 'incalls'
  • Example
  • command 'outcalls'
  • Example
  • command 'outsummary'
  • Example
  • command 'allcalls'
  • Example
  • extra data option
  • Example

    • Call Reports

    Inbound and outbound call reports in various formats. Note that these call reports may take several seconds to run on a busy system, and due to high resource demands from these reports, a lock is held while the report is generated.

    Permissions

    Requires System-Admin or Billing Call-Summary permissions. A user with Billing / Call Reporting permission may also read this data for companies they have permission to.
    IMPORTANT: the billing engine is single-threaded, and will lock while in use. This may result in the following response:
    {
	"result": "retry",
	"message": "Another user has billing locked. Please try again in a moment."
}

    command 'incalls'

    Path: /rest/call/incalls
    CDR records from the database are processed into details of inbound calls that have been received. Note that an internal call is both inbound and outbound. This process takes significant CPU and memory resources, so should not be called repeatedly or regularly, and if 2+ users try to use it simultaneously, only the first request will succeed.
    {
	"type": "cdr",
	"scope": {
		"company": "company", (optional, default to 'default')
		"day": day-number-to-report (optional),
		"month": month-number-to-report,
		"year": year-number-to-report,
		"days": days to include in day report (optional, default = 1),
		"extensions": [	(optional list of extensions to report on)
			"ext-num",
			...
		]
	}
}
    Return value:
    {
    "result": "success",
    "values": {
        extension-number: {
            "name": "Extension-name",
            "calls": [
                {
                    "acctid": accounting-id,
                    "calldate": epoch-seconds,
                    "caller": "callers-id",
                    "type": "Internal|External",
                    "ringtime": seconds,
                    "billsecs": seconds,
                    "detail": "Call-disposition",
                    "qtime": "seconds or empty",
                    "qstatus": "Queued-call-disposition or empty"
                },
                ...
                (more-calls)
            ],
        }
        ...
        (more-extensions)
    }
}

    Example

    {
    "type": "cdr",
    "scope": {
        "company": [
            "test"
        ],
        "month": 2,
        "year": 2017
    }
}
    {
    "result": "success",
    "values": {
        "200": {
            "name": "200snom320",
            "calls": [
                {
                    "acctid": 27739,
                    "calldate": 1487850941,
                    "caller": "203",
                    "type": "Internal",
                    "ringtime": 14,
                    "billsecs": 0,
                    "detail": "Not answered",
                    "qtime": "",
                    "qstatus": ""
                }
            ]
        }
    }
}

    command 'outcalls'

    Path: /rest/call/outcalls
    CDR records from the database are processed into details of outbound calls that have been made. Note that an internal call is both inbound and outbound. This process takes significant CPU and memory resources, so should not be called repeatedly or regularly, and if 2+ users try to use it simultaneously, only the first request will succeed.
    {
	"type": "cdr",
	"scope": {
		"company": "company", (optional, default to 'default')
		"day": day-number-to-report (optional),
		"month": month-number-to-report,
		"year": year-number-to-report,
		"days": days to include in day report (optional, default = 1),
		"deviceids": [	(optional list of device-ids to report on)
			"device-id is mac + port",
			...
		],
		"keeviomerge": "bool to merge keevio calls with handset calls",
		"recalc": "bool to force recalculate of costs" (VERY high CPU load)
	}
}
    Return value:
    {
    "result": "success",
    "values": {
        "device-id": {
            "name": "Device-owner",
            "device": "SIP-name",
            "calls": [
                {
                    "acctid": accounting-id,
                    "calldate": epoch-seconds,
                    "type": "Numberr-type",
                    "called_info": "Extra-human-readable-call-info",
                    "called": "called-number-short-form",
                    "dialled": "number-as-dialled",
                    "billsecs": seconds,
                    "ringtime": seconds,
                    "cost": cost-in-configured-units,
                    "trunk": "trunk-id or blank",
                    "cid": "caller-id sent"
                },
                ...
                (more-calls)
            ],
        },
        ...
        (more-devices)
    }
}

    Example

    {
    "type": "cdr",
    "scope": {
        "company": [
            "test"
        ],
        "month": 2,
        "year": 2017
    }
}
    {
    "result": "success",
    "values": {
        "0500000004000": {
            "name": "YealinkRnD T46",
            "device": "rndT46",
            "calls": [
                {
                    "acctid": 26123,
                    "calldate": 1487847464,
                    "type": "Test Number",
                    "called_info": "",
                    "called": "*600",
                    "dialled": "*600",
                    "billsecs": 61,
                    "ringtime": 0,
                    "cost": 0,
                    "trunk": "",
                    "cid": "301"
                }
            ]
        }
    }
}

    command 'outsummary'

    Path: /rest/call/outsummary
    CDR records from the database are processed into a per-company summary. This process takes significant CPU and memory resources, so should not be called repeatedly or regularly, and if 2+ users try to use it simultaneously, only the first request will succeed.
    {
	"type": "cdr",
	"scope": {
		"company": "company", (optional, default to show-all)
		"month": month-number-to-report,
		"year": year-number-to-report,
		"keeviomerge": "bool to merge keevio calls with handset calls",
		"detail": "bool to display per-device details",
		"recalc": "bool to force recalculate of costs" (VERY high CPU load)
	}
}
    Return value:
    {
    "result": "success",
    "values": {
        "company-id": {
            "name": "Company Name",
            "cost": cost,
            "unknown": count calls where cost unknown,
            "handset-id": {
                "name": "handset-owner",
                "device": "device name",
                "cost": cost,
                "seconds": billable-seconds,
                "unknown": count calls where cost unknown
            },
            ...
            (more handsets)
        },
        ...
        (each company)
    }
}

    Example

    In this example scope.detail is null (so false) so only per-company details are shown.
    {
    "type": "cdr",
    "scope": {
        "month": 2,
        "year": 2017
    }
}
    {
    "result": "success",
    "values": {
        "default": {
            "name": "Default Company",
            "cost": 1.23,
            "seconds": 217,
            "unknown": 1
        }
    }
}
    In this example scope.detail is true.
    {
    "type": "cdr",
    "scope": {
        "month": 2,
        "year": 2017,
        "detail": true
    }
}
    {
    "result": "success",
    "values": {
        "default": {
            "name": "Default Company",
            "cost": 1.23,
            "seconds": 217,
            "unknown": 1,
            "0200000000001": {
                "name": "A User",
                "device": "softphone",
                "cost": 1.23,
                "seconds": 217,
                "unknown": 1
            }
        }
    }
}

    command 'allcalls'

    Path: /rest/call/allcalls 6.2.16+
    CDR records from the database are processed into details of both inbound and outbound calls that have been made, combining the two reports above. This report also produces data for all companies on the PABX. This process takes significant CPU and memory resources, so should not be called repeatedly or regularly, and if 2+ users try to use it simultaneously, only the first request will succeed.
    The simpler query format allows much less filtering as the report is designed to return all data for the specified period.
    IMPORTANT: This report generates a HUGE amount of data - It is intended to be run for smaller date ranges which can be re-assembled by the client. Typically restrict this query to a 7 day period or less for memory CPU and performance reasons.
    {
	"type": "cdr",
	"scope": {
		"day": day-number-to-report (optional),
		"month": month-number-to-report,
		"year": year-number-to-report,
		"days": days to include in day report (optional, default = 1),
		"keeviomerge": "bool to merge keevio calls with handset calls",
		"recalc": "bool to force recalculate of costs" (VERY high CPU load)
	}
}
    The returned values are a combination of the inbound and outbound call data documented above, cost data is also excluded from this report:
    {
    "result": "success",
    "values": {
        "company": {
            "name": "Company name",
            "out": {
                "device-id": {
                    "name": "Device-owner",
                    "device": "SIP-name",
                    "calls": [ ... ]
                },
                ...
                (more devices)
            },
            "in": {
                extension-number: {
                    "name": "Extension-name",
                    "calls": [ ... ]
                },
                ...
                (more extensions)
            }
        },
        ...
        (more companies)
    }
}

    Example

    {
    "type": "cdr",
    "scope": {
        "year": 2017,
        "month": 5,
        "day": 5,
        "days": 7
    }
}
    {
    "result": "success",
    "values": {
        "acompany": {
            "name": "A Company",
            "in": {
                "446": {
                    "name": "Meeting Room",
                    "calls": [
                         {
                            "acctid": 2012560,
                            "calldate": 1493899151,
                            "caller": "203",
                            "type": "Internal",
                            "ringtime": 2,
                            "billsecs": 0,
                            "detail": "Not answered",
                            "qtime": "",
                            "qstatus": "",
                            "ddi": ""
                        }
                    ]
                }
            },
            "out": {
                "0500000004000": {
                    "name": "YealinkRnD T46",
                    "device": "rndT46",
                    "calls": [
                        {
                            "acctid": 26123,
                            "calldate": 1493895749,
                            "type": "Test Number",
                            "called_info": "",
                            "called": "*600",
                            "dialled": "*600",
                            "billsecs": 61,
                            "ringtime": 0,
                            "cost": 0,
                            "trunk": "",
                            "cid": "301"
                        }
                    ]
                }
            }
        }
    }
}

    extra data option

    6.3.1+ In the above in/out/all reports, it is possible to request additional data. WARNING: This extra data will significantly increase the size of the report and the processing needed to generate it. The extra data is requested by adding an extra: true attribute to the scope of the existing request.
    The resultant data is included within each call's output as extra child object(s). Possible additional data is as follows. Most fields are optional depending on call type and direction:
    "extra": {
	"frch": "source-channel",
	"toch": "target-channel",
	"xfch": "transferrer-channel",
	"crhint": "hint for call recording filename",
	"toint": bool - true for call targeted to PABX device,
	"frint": bool - true for call originated from PABX device,
	"frid": unique contact-id of caller,
	"frname": "Caller-name",
	"toid": unique contact-id of callee,
	"toname": "Callee-name"
	"xfid": unique contact-id of transferrer,
	"xfname": "Transferrer-name"
	"disposition": "FAILED|BUSY|ANSWERED|NO ANSWER|VOICEMAIL",
	"frchname": "Calling device name",
	"tochname": "Called device name",
	"frhdext": "extension number if hotdesked"
},
"xfer": [
	{
		"acctid": acctid of next call leg,
		"att": bool - attended=true / blind = false,
		"xferdate": transfer time in epoch-seconds
	},
	...
]

    Example

    {
    "type": "cdr",
    "scope": {
        "year": 2017,
        "month": 5,
        "day": 5,
        "days": 7,
        "extra": true
    }
}
    {
    "result": "success",
    "values": {
        "acompany": {
            "name": "A Company",
            "in": {
                "446": {
                    "name": "Meeting Room",
                    "calls": [
                        {
                            "acctid": 56609,
                            "calldate": 1521029878,
                            "called_info": "",
                            "called": "203",
                            "dialled": "203",
                            "billsecs": 32,
                            "ringtime": 2,
                            "trunk": "",
                            "cid": "203",
                            "extra": {
                                "frch": "SIP/t42",
                                "toch": "SIP/webrtc111",
                                "crhint": "1521029879-203-203",
                                "toint": true,
                                "frint": true,
                                "frid": 111,
                                "frname": "203t42 L.M.B",
                                "toid": 111,
                                "toname": "203t42 L.M.B",
                                "disposition": "ANSWERED",
                                "frchname": "t42",
                                "tochname": "203t42 L.M.B"
                            },
                            "xfer": [
                                {
                                    "acctid": 56610,
                                    "att": false,
                                    "xferdate": 1521029905
                                }
                            ]
                        },
                        {
                            "acctid": 56610,
                            "calldate": 1521029905,
                            "caller_info": "",
                            "caller": "203",
                            "type": "Internal xfer",
                            "ringtime": 2,
                            "billsecs": 5,
                            "detail": "Answered : 201snom360 Smith",
                            "extra": {
                                "frch": "SIP/t42",
                                "toch": "SIP/webrtc109",
                                "xfch": "SIP/webrtc111",
                                "toint": true,
                                "frint": true,
                                "frid": 111,
                                "frname": "203t42 L.M.B",
                                "toid": 109,
                                "toname": "201snom360 Smith",
                                "xfid": 111,
                                "xfname": "203t42 L.M.B",
                                "disposition": "ANSWERED",
                                "frchname": "t42",
                                "tochname": "201snom360 Smith"
                            }
                        }
                    ]
                }
            },
            "out": {
                "0500000004000": {
                    "name": "YealinkRnD T46",
                    "device": "rndT46",
                    "calls": [
                        {
                            "acctid": 56692,
                            "calldate": 1522244293,
                            "called_info": "",
                            "called": "902",
                            "dialled": "902",
                            "billsecs": 6,
                            "ringtime": 0,
                            "trunk": "",
                            "cid": "203",
                            "extra": {
                                "frch": "SIP/t42",
                                "crhint": "1522244293-203-902",
                                "toint": true,
                                "frint": true,
                                "frid": 111,
                                "frname": "203t42 L.M.B",
                                "disposition": "ANSWERED",
                                "frchname": "t42"
                            }
                        }
                    ]
                }
            }
        }
    }
}