This document is for an older version of Kazoo (version 4.3) that is no longer supported. You should upgrade and read the current documentation.

Call Detail Records

CDRs (Call Detail Records) provide a summary view of a call leg.

Schema

Call Detail Records

KeyDescriptionTypeDefaultRequiredSupport Level
app_nameThe Kazoo application that issued the CDRstring()false
app_versionThe internal Kazoo version number of the application that issued the CDRstring()false
billing_secondsThe number of seconds the call leg can be billed for (typically from when the call leg is answeredinteger()false
call_directionDirection of the call, relative to the media switch`string(‘inbound''outbound’)`false
call_idUnique identifier of the call legstring()true
callee_id_nameThe indicated name of the calleestring()false
callee_id_numberThe indicated number of the calleestring()false
caller_id_nameThe indicated name of the callerstring()false
caller_id_numberThe indicated number of the callerstring()false
channel_created_timeUnix timestamp in microseconds of channel createinteger()false
custom_application_varsAny custom-set valuesobject()false
custom_channel_varsKazoo-specific key/value pairs set on the channelobject()false
custom_sip_headers.inCustom SIP Headers to be applied to calls inbound to Kazoo from the endpoint#/definitions/custom_sip_headersfalse
custom_sip_headers.outCustom SIP Headers to be applied to calls outbound from Kazoo to the endpoint#/definitions/custom_sip_headersfalse
custom_sip_headers.^[a-zA-z0-9_\-]+$The SIP header to addstring()false
custom_sip_headersA property list of SIP headersobject()false
digits_dialedAll the DTMF tones detected on this leg of the callstring()false
dispositionWho sent the SIP BYE messagestring()false
duration_secondsThe duration of the call leg, in secondsinteger()false
fax_bad_rowsstring()false
fax_ecm_usedstring()false
fax_result_codestring()false
fax_result_textstring()false
fax_successstring()false
fax_total_pagesstring()false
fax_transfer_ratestring()false
fax_transferred_pagesstring()false
fromBuilt by Kazoo, depending on direction, to represent the From userstring()false
from_tagSIP From TAGstring()false
from_uriThe From SIP URIstring()false
hangup_causeThe reason for the call leg’s terminationstring()false
hangup_codeThe SIP hangup code, if availablestring()false
interaction_idcorrelating ID among related call legsstring()false
local_sdpThe SDP negotiated by the local agentstring()false
media_serverThe hostname of the media server that processed the callstring()false
nodeThe ecallmgr which issued the CDRstring()false
other_leg_call_idIf this leg was bridged, the call-id of the opposite legstring()false
other_leg_caller_id_nameCaller ID name of the bridged legstring()false
other_leg_caller_id_numberCaller ID number of the bridged legstring()false
other_leg_destination_numberDialed number of the other legstring()false
other_leg_directiondirection of the other leg, relative to the media serverstring()false
presence_idID used in NOTIFY SIP messagesstring()false
remote_sdpThe SDP negotiated by the remote agentstring()false
requestBuilt by Kazoo this is the processed request URIstring()false
ringing_secondsHow many seconds the leg was ringing (pre-answer)integer()false
timestampUTC timestamp, in Gregorian seconds, of when the CDR was generatedinteger()false
toBuilt by Kazoo, depending on direction, to represent the To userstring()false
to_tagSIP TO Tagstring()false
to_uriThe To SIP URIstring()false
user_agentUser agent header from SIP packetstring()false

custom_sip_headers

Custom SIP headers applied to an INVITE

KeyDescriptionTypeDefaultRequiredSupport Level
^[a-zA-z0-9_\-]+$The SIP header to addstring()false

Fetch

Prerequisites

By default requests are paginated. The default page size is 50 records though it can vary based on the system’s configuration. It is recommended to fetch CDRs by page to not overload the system on particularly busy accounts.

Clients should use the next_start_key to move to the next page on subsequent requests.

Filtering results.

KAZOO provides filters to filter out rows from the results. This can be helpful if you’re looking for rows related to each other (like the same presence_id, for instance).

Timestamps

KAZOO timestamps, unless otherwise noted, are in Gregorian seconds. Alternative timestamp formats are generally noted by the field name (e.g. unix_timestamp, rfc1036, or iso8601).

Fetch request

GET /v2/accounts/{ACCOUNT_ID}/cdrs

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/cdrs

Fetch CDRs within a time range

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/cdrs?created_from={FROM_TIMESTAMP}&created_to={TO_TIMESTAMP}

Convert timestamps to local timezone (vs UTC)

Get CDRs and update datetime field to local time zone (using seconds for timeoffset from UTC time) - Timestamps must still be in Gregorian time:

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/cdrs?created_from={FROM_TIMESTAMP}&created_to={TO_TIMESTAMP}&utc_offset={SECONDS_OFFSET}

Fetch as CSV instead of JSON

curl -v -X GET \
    -H "Accept: text/csv" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/cdrs

Fetch as CSV with defined filename

Using request headers:

curl -v -X GET \
    -H "Accept: text/csv" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-File-Name: {FILE_NAME}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/cdrs

Alternatively on the querystring:

curl -v -X GET \
    -H "Accept: text/csv" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/cdrs?file_name={FILE_NAME}

Fetch a CDR’s details

GET /v2/accounts/{ACCOUNT_ID}/cdrs/{CDR_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/cdrs/{CDR_ID}

Fetch interaction summary

GET /v2/accounts/{ACCOUNT_ID}/cdrs/interaction

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/cdrs/interaction

Crossbar cdrs was extended to provide simplified interaction call detail records. It groups all CDRs that interacted with each other to form a list of calls.

GET /v2/accounts/{ACCOUNT_ID}/cdrs/legs/{INTERACTION_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/cdrs/legs/{INTERACTION_ID}

Variations

You can select CDRs/interactions for a specific user by adding them to the URI:

GET /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/cdrs

Notes on fields

Some fields need a little more explanation to help you understand what they are telling you about the call leg.

  • call_direction - direction of the leg, relative to the media switch
    • inbound - leg came into the media switch (typically the A-leg)
    • outbound - leg started on the media switch (typically the B-leg)
  • hangup_cause - The reason why the call leg ended. See the FreeSWITCH Hangup Causes page for descriptions.
  • billing_seconds - How many seconds of the call are billable (post answer, normally)
  • to - Depends on the direction of the leg
    • outbound - Uses the presence-id or else it uses the SIP Request address
    • inbound - the SIP To header

Kazoo-specific properties

These are properties set by Kazoo for internal purposes. These are the properties found under the custom_channel_vars property at the top-level of the CDR JSON object. The non-exhaustive list of properties:

  • account_id - Account ID this leg belongs to
  • authorizing_id - Document ID used to authorize this call leg
  • authorizing_type - Type of document used to authorize call
    • device - the call leg is to/from a known Kazoo device
    • mobile - the call leg is to/from a known Kazoo mobile device
    • resource - the call leg is from a known offnet carrier
    • outbound_fax
  • bridge_id - Typically the A-leg’s call-id; helps with tracking transfers
  • ecallmgr_node - Which ecallmgr node is processing the call leg
  • fetch_id - The dialplan XML fetch ID from FreeSWITCH
  • realm - the SIP realm of the account
  • resource_id - Resource ID used for the leg; typically a carrier, local or global, that the call was routed to
  • username - the SIP username of the endpoint that started the leg

These properties relate to how the leg was rated and billed. Some of these properties are not accessible via Crossbar, but may exist on the CDR

  • reseller_billing - tag describing what billing was used for the reseller
  • reseller_id - Account ID of the reseller for the account of this leg
  • account_billing - tag describing what billing was used for the account
  • rate - Rate of the call
  • base_cost - How much the call costs to start (if per-minute)
  • rate_name - Name of the rate doc used
  • surcharge - Surcharge added to the leg
  • rate_minimum - Minimum number of seconds to bill for
  • rate_increment - Increment of seconds to bill for

Fax-specific Properties

These properties may exist on a CDR for a fax request (inbound or outbound):

  • fax_transfer_rate - Baud of the fax transfer
  • fax_bad_rows - Number of rows that failed to transfer
  • fax_total_pages - Number of pages in the fax (see fax_transferred_pages for how many made it)
  • fax_transferred_pages - Number of pages transferred
  • fax_ecm_used - Was ECM (error correction mode) used on the fax
  • fax_result_text - Error String, if any, or ‘OK’ if successful
  • fax_result_code - Result code of the transmission
  • fax_success - boolean for whether the fax was considered a success
  • fax_t38 - boolean for whether the fax T.38 was used

Resource Properties

All resource properties are set by the Stepswitch application.

  • resource_type - This property attempts to explain the reason the resource was used. The possible values are:
    • offnet-origination - Inbound call from a resource/carrier to a Kazoo account
    • offnet-termination - Outbound call from a Kazoo account to a resource/carrier
    • onnet-origination - Inbound call from a Kazoo account to another Kazoo account
    • onnet-termination - Outbound call from a Kazoo account to another Kazoo account
  • global_resource - This boolean is TRUE when the channel has been created by processing a resource from the offnet database, and FALSE if the resource is from an account database (local).
  • resource_id - This is resource document id used to create the channel

On this page