Calls

The Calls API lets you retrieve call detail records (CDRs) and quality insights for calls made through your SIP trunks.

API Endpoint

https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Call/

The Call Object

Attributes

string

Unique call identifier.

string

Caller ID. On India domestic calls retried through automatic carrier failover, this field records the fallback caller ID used on the retry, not the number you originally sent.

string

Destination number.

string

Direction. Values: inbound, outbound.

integer

Actual call duration in seconds.

integer

Billed duration in seconds.

integer

Billed duration (may differ based on billing interval).

string

When call was initiated (UTC).

string

When call was answered (UTC).

string

When call ended (UTC).

string

Reason for hangup.

integer

Numeric hangup cause code.

string

Who ended the call. Values: customer, carrier, zentrunk.

string

Per-minute rate (USD).

string

Total cost (USD).

string

Trunk domain used.

string

Caller’s country (ISO2).

string

Destination country (ISO2).

string

Protocol used (e.g., udp, tcp).

boolean

Whether SRTP encryption was used.

boolean

Whether secure trunking was enabled.

string

Secure trunking per-minute rate.

string

STIR/SHAKEN status.

string

Attestation level. Values: A, B, C.

Example Response

{
  "call_uuid": "90b6eb07-796c-4d86-a4fd-44ed11667ddb",
  "from_number": "+12025551234",
  "to_number": "+13125551234",
  "call_direction": "outbound",
  "call_duration": 180,
  "bill_duration": 180,
  "billed_duration": 180,
  "end_time": "2024-01-15 14:32:00",
  "hangup_cause_name": "normal_hangup",
  "hangup_source": "carrier",
  "total_rate": "0.00500",
  "total_amount": "0.01500",
  "initiation_time": "2024-01-15 14:28:48",
  "answer_time": "2024-01-15 14:29:00",
  "trunk_domain": "93667062664669661.zt.plivo.com",
  "from_country": "US",
  "to_country": "US",
  "transport_protocol": "udp",
  "srtp": false,
  "hangup_cause_code": 3000,
  "secure_trunking": false,
  "secure_trunking_rate": "0.00000",
  "stir_verification": "Verified",
  "attestation_indicator": "A"
}

Retrieve a Call

Get the call detail record (CDR) for a specific call.

GET https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Call/{call_uuid}/

cURL

curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Call/90b6eb07-796c-4d86-a4fd-44ed11667ddb/

Response

Returns the Call object for the specified call UUID.

List All Calls

Retrieve CDRs for all calls with optional filtering.

GET https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Call/

Query Parameters

string

Filter by caller ID (exact or prefix).

string

Filter by destination (exact or prefix).

string

Filter by direction. Values: inbound, outbound.

integer

Filter by hangup cause code.

string

Filter by hangup source. Values: customer, carrier, zentrunk.

string

Filter by STIR status. Values: Verified, Not Verified, Not Applicable.

integer

Filter by duration in seconds. Supports variants: bill_duration__gt, bill_duration__gte, bill_duration__lt, bill_duration__lte.

string

Filter by call end time. Format: YYYY-MM-DD HH:MM[:ss] (UTC). Supports variants: end_time__gt, end_time__gte, end_time__lt, end_time__lte.

integer

Results per page. Max: 20. Default: 20.

integer

Pagination offset. Default: 0.

You can retrieve only calls from the last 90 days. Without an end_time filter, the API searches the last 30 days.

Example Request

cURL

curl -i --user AUTH_ID:AUTH_TOKEN \
    "https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Call/?call_direction=outbound&end_time__gte=2024-01-01%2000:00&limit=20"

Response

string

Unique identifier for the API request.

object

Pagination metadata: limit (results per page), offset (items skipped), total_count (total matching calls).

array

Array of call objects — see The Call Object.

{
  "api_id": "a04ad809-3b78-4bbe-9baf-acfc7800b10f",
  "meta": {
    "limit": 20,
    "offset": 0,
    "total_count": 2,
    "previous": null,
    "next": null
  },
  "objects": [
    {
      "call_uuid": "90b6eb07-796c-4d86-a4fd-44ed11667ddb",
      "from_number": "+12025551111",
      "to_number": "+13125551234",
      "call_direction": "outbound",
      "call_duration": 180,
      "bill_duration": 180,
      "stir_verification": "Verified",
      "attestation_indicator": "A"
    }
  ]
}

Retrieve Call Insights

Get quality metrics for a specific call.

GET https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Call/{call_uuid}/Insights/

cURL

curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Call/c9d6be3d-94c3-4b38-a2eb-8063ca404d77/Insights/

Response

string

Unique identifier for the API request.

string

Unique call identifier.

object

Details of the caller: carrier, number, and region.

object

Details of the destination: carrier, number, and region.

string

Reason for hangup.

string

Who ended the call. Values: customer, carrier, zentrunk.

string

Round-trip time in milliseconds. High values indicate network latency.

string

Variance in packet delay (ms). Causes robotic-sounding audio.

string

Percentage of lost packets. Causes broken audio.

float

Time from call initiation to ringing (ms).

string

Quality rating from 1-5. Higher is better.

{
  "api_id": "a63df7e3-9f24-4aae-2152-dc8f92548290",
  "call_uuid": "c9d6be3d-94c3-4b38-a2eb-8063ca404d77",
  "from": {
    "carrier": "Verizon Wireless",
    "number": "+12025551234",
    "region": "US"
  },
  "to": {
    "carrier": "AT&T",
    "number": "+13125551234",
    "region": "US"
  },
  "hangup_cause": "normal_hangup",
  "hangup_source": "customer",
  "rtt": "24",
  "jitter": "3",
  "packet_loss": "0",
  "post_dial_delay": 1000.0,
  "plivo_quality_score": "4.2"
}

Insights Metrics

string

Round-trip time in milliseconds. High values indicate network latency.

string

Variance in packet delay (ms). Causes robotic-sounding audio.

string

Percentage of lost packets. Causes broken audio.

float

Time from call initiation to ringing (ms).

string

Quality rating from 1-5. Higher is better.

Quality Score Guidelines

Score	Quality
`4.0 - 5.0`	Excellent
`3.0 - 4.0`	Good
`2.0 - 3.0`	Fair
`1.0 - 2.0`	Poor

STIR/SHAKEN Verification

The stir_verification field indicates call authenticity:

Value	Description
`Verified`	Caller verified with attestation level A
`Not Verified`	Attestation level B or C
`Not Applicable`	Non-US calls or cloud calls (WebRTC/SIP)

Hangup Sources

Source	Description
`customer`	Your infrastructure ended the call
`carrier`	The terminating carrier ended the call
`zentrunk`	Plivo’s SIP trunking platform ended the call

Trunks - Manage SIP trunks
Hangup Codes - Complete hangup cause reference

Concepts

SIP REFER

Security

API Reference

Troubleshooting

PBX Integration

API Endpoint

The Call Object

Attributes

Example Response

Retrieve a Call

Response

List All Calls

Query Parameters

Example Request

Response

Retrieve Call Insights

Response

Insights Metrics

Quality Score Guidelines

STIR/SHAKEN Verification

Hangup Sources

API Endpoint

The Call Object

Attributes

Example Response

Retrieve a Call

Response

List All Calls

Query Parameters

Example Request

Response

Retrieve Call Insights

Response

Insights Metrics

Quality Score Guidelines

STIR/SHAKEN Verification

Hangup Sources

Related