Calls - Plivo

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

string

Unique identifier for the API request.

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

string

Unique identifier for the API request.

call_uuid

string

Unique call identifier.

from

object

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

object

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

hangup_cause

string

Reason for hangup.

hangup_source

string

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

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.

{
  "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

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

​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

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