Skip to main content

Documentation Index

Fetch the complete documentation index at: https://plivo.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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