About CDRs

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


Call Detail Records

Key Description Type Default Required
app_name The Kazoo application that issued the CDR string false
app_version The internal Kazoo version number of the application that issued the CDR string false
billing_seconds The number of seconds the call leg can be billed for (typically from when the call leg is answered string false
call_direction Direction of the call, relative to the media switch string('inbound', 'outbound') false
call_id Unique identifier of the call leg string true
callee_id_name The indicated name of the callee string false
callee_id_number The indicated number of the callee string false
caller_id_name The indicated name of the caller string false
caller_id_number The indicated number of the caller string false
custom_channel_vars Kazoo-specific key/value pairs set on the channel object false
custom_sip_headers A property list of SIP headers beging with the prefix 'X-' object false
digits_dialed All the DTMF tones detected on this leg of the call string false
disposition Who sent the SIP BYE message string false
duration_seconds The duration of the call leg, in seconds string false
fax_bad_rows string false
fax_ecm_used string false
fax_result_code string false
fax_result_text string false
fax_success string false
fax_total_pages string false
fax_transfer_rate string false
fax_transferred_pages string false
from Built by Kazoo, depending on direction, to represent the From user string false
from_uri The From SIP URI string false
hangup_cause The reason for the call leg's termination string false
hangup_code The SIP hangup code, if available string false
local_sdp The SDP negotiated by the local agent string false
media_server The hostname of the media server that processed the call string false
node The ecallmgr which issued the CDR string false
other_leg_call_id If this leg was bridged, the call-id of the opposite leg string false
other_leg_caller_id_name Caller ID name of the bridged leg string false
other_leg_caller_id_number Caller ID number of the bridged leg string false
other_leg_destination_number Dialed number of the other leg string false
other_leg_direction direction of the other leg, relative to the media server string false
presence_id ID used in NOTIFY SIP messages string false
remote_sdp The SDP negotiated by the remote agent string false
request Built by Kazoo this is the processed request URI string false
ringing_seconds How many seconds the leg was ringing (pre-answer) string false
timestamp UTC timestamp, in gregorian seconds, of when the CDR was generated string false
to Built by Kazoo, depending on direction, to represent the To user string false
to_uri The To SIP URI string false
user_agent User agent header from SIP packet string false

Fetch a summary of CDRs

GET /v2/accounts/{ACCOUNT_ID}/cdrs

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \

Get a time range of CDRs (using gregorian seconds for timestamps):

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \

Get CDRs as CSV:

curl -v -X GET \
    -H "Accept: text/csv" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \

Fetch a CDR's details

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

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \

Fetch interaction summary

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

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \

Crossbar cdrs was extended to provide simplified interaction call detail records. It groups all CDRs that interacted with eachouther 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}" \


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 ducument 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

Edit this page here