# Calls API Overview

> Endpoints for placing, reading, listing, controlling and recording calls with the Edesy Voice API, plus the call object and pagination.

Source: https://edesy.in/docs/voice-api/calls

The Calls API is the core of the Voice API: `POST /v1/calls` places a call, `GET /v1/calls/{CallSid}` reads it, and the other endpoints list calls, show a call's event timeline, hang up a live call and manage recordings. All endpoints take JSON, return JSON wrapped in `data`, and use the same authentication.

## Endpoints

| Method | Path | What it does |
|---|---|---|
| `POST` | `/v1/calls` | Place an outbound call. See [Make a Call](https://edesy.in/docs/voice-api/calls/make-a-call) |
| `GET` | `/v1/calls` | List calls, newest first |
| `GET` | `/v1/calls/summary` | Count, total price and total duration for the same filters as the list |
| `GET` | `/v1/calls/{CallSid}` | Read one call |
| `POST` | `/v1/calls/{CallSid}` | End a live call. See [Update or End a Call](https://edesy.in/docs/voice-api/calls/update-or-end-a-call) |
| `DELETE` | `/v1/calls/{CallSid}` | Hang up a live call |
| `GET` | `/v1/calls/{CallSid}/events` | Event timeline. See [Call Events and Outcomes](https://edesy.in/docs/voice-api/calls/call-events-and-outcomes) |
| `GET` | `/v1/calls/{CallSid}/recordings` | Recordings of this call |
| `POST` | `/v1/calls/{CallSid}/recordings/start` | Start recording a live call |
| `GET` | `/v1/recordings` | List recordings. See [Recordings and Transcriptions](https://edesy.in/docs/voice-api/calls/recordings-and-transcriptions) |

Twilio-shaped aliases such as `/v1/Accounts/{AccountSid}/Calls` map to the same handlers. See [Migrate from Twilio](https://edesy.in/docs/voice-api/guides/migrate-from-twilio).

## The call object

```json
{
  "call_sid": "CA_6f1c2d3e-0000-4000-8000-000000000000",
  "sid": "CA_6f1c2d3e-0000-4000-8000-000000000000",
  "account_sid": "2b7e0a1c-0000-4000-8000-000000000000",
  "from": "+9180XXXXXXXX",
  "to": "+9198XXXXXXXX",
  "direction": "outbound-api",
  "status": "completed",
  "answered_at": "2026-10-28T09:30:12Z",
  "ended_at": "2026-10-28T09:31:02Z",
  "duration": 50,
  "price": { "amount": 0.5, "currency": "INR" },
  "hangup_cause": "completed",
  "sip_response_code": 200,
  "call_outcome": "answered",
  "custom_parameters": { "order_id": "ORD-1042" },
  "created_at": "2026-10-28T09:30:00Z"
}
```

| Field | Description |
|---|---|
| `call_sid` / `sid` | The call ID, `CA_` plus a UUID. `sid` is the same value, for code written against Twilio |
| `direction` | `outbound-api` (placed with this API), `inbound`, `outbound-dial` (a `dial` leg) or `outbound-trunk` (placed through your SIP trunk) |
| `status` | `queued`, `initiated`, `ringing`, `in-progress`, `completed`, `busy`, `failed`, `no-answer`, `canceled` |
| `duration` | Answered seconds, after the call ends |
| `price` | Amount charged and currency, after the call ends |
| `hangup_cause` | Why the call ended. See [Call Events and Outcomes](https://edesy.in/docs/voice-api/calls/call-events-and-outcomes) |
| `sip_response_code` | Final SIP code, for example `200`, `486`, `480` |
| `call_outcome` | `answered`, `callee`, `unreachable`, `invalid_number`, `network`, `account` or `platform` |
| `answered_by` | `human`, `machine` or `unknown` when answering-machine detection ran |
| `caller_name` | Display name sent with the call, if any |
| `parent_call_sid` | Set on a child leg created by `dial` |
| `custom_parameters` | Your metadata from the request |
| `recording` | Recording details when one exists |

Fields that do not apply yet (for example `ended_at` on a ringing call) are left out.

## Listing calls

`GET /v1/calls?status=completed&direction=outbound-api&per_page=50&page=1`

| Query parameter | Description |
|---|---|
| `status` | Filter by status |
| `direction` | Filter by direction |
| `from`, `to` | Filter by number (E.164) |
| `start_date`, `end_date` | RFC 3339 timestamps, for example `2026-10-01T00:00:00Z` |
| `page`, `per_page` | Pagination. `per_page` defaults to 20 |

The response `meta` carries `total`, `page`, `per_page` and `total_pages`.