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 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.

Call history

Routes

Get a call

Get the recording

Errors

Code samples