Call Detail Records API

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

Schema

Call Detail Records

custom_sip_headers

Custom SIP headers applied to an INVITE

Fetch

GET /v2/accounts/{ACCOUNT_ID}/cdrs

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

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

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

Get CDRs and update datetime field to local time zone (using seconds for timeoffset from UTC time):

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

Get CDRs as CSV:

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

Get CDRs as CSV and define filename:

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

or

curl -v -X GET \
    -H "Accept: text/csv" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:{PORT}/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}:{PORT}/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}:{PORT}/v2/accounts/{ACCOUNT_ID}/cdrs/interaction

Fetch all legs related to an 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}:{PORT}/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

Flex UC-specific properties

These are properties set by Flex UC for internal purposes. These are the properties found under the custom_channel_varsproperty 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 Flex UC device
  • mobile – the call leg is to/from a known Flex UC 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

Billing-related Properties

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 Flex UC account
  • offnet-termination – Outbound call from a Flex UC account to a resource/carrier
  • onnet-origination – Inbound call from a Flex UC account to another Flex UC account
  • onnet-termination – Outbound call from a Flex UC account to another Flex UC 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