API reference / Phone and calls
Call history
Use these routes to read the record of a call that already happened, inbound or outbound, and to download its recording. To place a call, see Voice calls.
You get a call_id from call webhooks, such as contact.call.hangup, and from
AI agent call results. See
Webhooks.
Routes
| Method | Route | Scope | What it does |
|---|---|---|---|
GET |
/phone/public/calls/{call_id} |
contacts:read |
Get a call |
GET |
/phone/public/calls/{call_id}/recording |
contacts:read |
Get a link to the call's recording |
Get a call
curl https://api-v2.dropcowboy.com/phone/public/calls/2f1391f7-14b1-4435-9863-e0ef72382c72 \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
{
"data": {
"_id": "66f2b1c4e8a9d3f1a2b4c6dd",
"call_id": "2f1391f7-14b1-4435-9863-e0ef72382c72",
"root_call_id": "2f1391f7-14b1-4435-9863-e0ef72382c72",
"team_id": "cd5cd773-4617-4b28-854d-d3adc74c96d5",
"call_direction": "inbound",
"call_type": "external",
"contact_id": "487d8607-e415-4d90-a1e1-f9c1a746e0a1",
"contact_number": "+13125550118",
"from": "+13125550118",
"to": "+13125550142",
"ivr_id": "234ecab5-1811-4c7d-a7a9-8c9ad9ca2e08",
"user_id": "fa933d82-485f-43b0-80ab-860121f06980",
"record_call": true,
"answered": true,
"created_at": 1759312800000,
"started_at": 1759312800000,
"answered_at": 1759312806000,
"completed_at": 1759312900000,
"duration": 94,
"disposition": null
},
"meta": { "request_id": "6ed1ee90-7ec1-42ab-964e-58af116aba1a" }
}
| Field | Description |
|---|---|
call_direction |
inbound or outbound. |
ivr_id |
The phone line that answered an inbound call. See Phone numbers. |
user_id |
The team member on the call, if any. |
duration |
Length of the call in seconds. |
Timestamps are epoch milliseconds.
If you are on a BYOC team and signed the call with a certificate you
uploaded, the same object also carries sti_identity, sti_attestation,
sti_orig_id and sip_call_id. They are omitted (not null) otherwise.
Retail teams never receive them. See
Results of your sends for what the four
fields mean.
If no call has that id, data is an empty object with status 200. Check for
call_id in the response before you read other fields.
Get the recording
Returns a signed link to the call's recording, valid for 5 days. Request a new link each time you play or download it, rather than storing one.
curl https://api-v2.dropcowboy.com/phone/public/calls/2f1391f7-14b1-4435-9863-e0ef72382c72/recording \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
{
"data": {
"url": "https://recordings.example.com/1f96d605-ea75-4c23-a071-93dc9208980f.ogg?X-Amz-Signature=...",
"recording_id": "1f96d605-ea75-4c23-a071-93dc9208980f",
"recording_type": "call",
"extension": ".ogg",
"duration": 94
},
"meta": { "request_id": "d7f2c484-d402-47bc-97c5-f358cfd16d97" }
}
recording_type tells you what was recorded: call for a recorded
conversation, voicemail for a message a caller left.
Sometimes the response has recording_unavailable_reason and no url:
| Reason | Meaning | What to do |
|---|---|---|
negative_balance |
The call was recorded, but your balance is below zero now | Add funds and request the recording again. |
unfunded_at_call_time |
Your balance was too low to record when the call happened, so there is no recording | Nothing to fetch. Keep a positive balance so future calls are recorded. |
Free-trial accounts don't get either reason.
Errors
| Status | When | What to do |
|---|---|---|
404 |
call not found: the call isn't on your account. |
Check the call_id from your webhook. |
404 |
no recording found for this call |
The call wasn't recorded, or the recording isn't ready. Wait for contact.call.recording.available, then try again. |
For every other error, see Responses, errors and limits.