Skip to main content
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

​
call_uuid
string
Unique call identifier.
​
from_number
string
Caller ID.
​
to_number
string
Destination number.
​
call_direction
string
Direction. Values: inbound, outbound.
​
call_duration
integer
Actual call duration in seconds.
​
bill_duration
integer
Billed duration in seconds.
​
billed_duration
integer
Billed duration (may differ based on billing interval).
​
initiation_time
string
When call was initiated (UTC).
​
answer_time
string
When call was answered (UTC).
​
end_time
string
When call ended (UTC).
​
hangup_cause_name
string
Reason for hangup.
​
hangup_cause_code
integer
Numeric hangup cause code.
​
hangup_source
string
Who ended the call. Values: customer, carrier, zentrunk.
​
total_rate
string
Per-minute rate (USD).
​
total_amount
string
Total cost (USD).
​
trunk_domain
string
Trunk domain used.
​
from_country
string
Caller’s country (ISO2).
​
to_country
string
Destination country (ISO2).
​
transport_protocol
string
Protocol used (e.g., udp, tcp).
​
srtp
boolean
Whether SRTP encryption was used.
​
secure_trunking
boolean
Whether secure trunking was enabled.
​
secure_trunking_rate
string
Secure trunking per-minute rate.
​
stir_verification
string
STIR/SHAKEN status.
​
attestation_indicator
string
Attestation level. Values: A, B, C.

​
Example Response

{
  "call_uuid": "90b6eb07-796c-4d86-a4fd-44ed11667ddb",
  "from_number": "+12025551234",
  "to_number": "+13128574907",
  "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

​
from_number
string
Filter by caller ID (exact or prefix).
​
to_number
string
Filter by destination (exact or prefix).
​
call_direction
string
Filter by direction. Values: inbound, outbound.
​
hangup_cause_code
integer
Filter by hangup cause code.
​
hangup_source
string
Filter by hangup source. Values: customer, carrier, zentrunk.
​
stir_verification
string
Filter by STIR status. Values: Verified, Not Verified, Not Applicable.
​
bill_duration
integer
Filter by duration in seconds. Supports variants: bill_duration__gt, bill_duration__gte, bill_duration__lt, bill_duration__lte.
​
end_time
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.
​
limit
integer
Results per page. Max: 20. Default: 20.
​
offset
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

{
  "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": "+13128574907",
      "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

{
  "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": "+13128574907",
    "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

​
rtt
string
Round-trip time in milliseconds. High values indicate network latency.
​
jitter
string
Variance in packet delay (ms). Causes robotic-sounding audio.
​
packet_loss
string
Percentage of lost packets. Causes broken audio.
​
post_dial_delay
float
Time from call initiation to ringing (ms).
​
plivo_quality_score
string
Quality rating from 1-5. Higher is better.

​
Quality Score Guidelines

ScoreQuality
4.0 - 5.0Excellent
3.0 - 4.0Good
2.0 - 3.0Fair
1.0 - 2.0Poor

​
STIR/SHAKEN Verification

The stir_verification field indicates call authenticity:
ValueDescription
VerifiedCaller verified with attestation level A
Not VerifiedAttestation level B or C
Not ApplicableNon-US calls or cloud calls (WebRTC/SIP)

​
Hangup Sources

SourceDescription
customerYour infrastructure ended the call
carrierThe terminating carrier ended the call
zentrunkPlivo’s SIP trunking platform ended the call