> For the complete documentation index, see [llms.txt](https://docs.limecall.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limecall.com/developers/calls.md).

# Calls API

List and inspect calls, fetch recordings and transcripts, and write outcomes back.

| Method  | Path                        | Scope         |
| ------- | --------------------------- | ------------- |
| `GET`   | `/calls`                    | `calls:read`  |
| `GET`   | `/calls/{id}`               | `calls:read`  |
| `GET`   | `/calls/{id}/recording`     | `calls:read`  |
| `GET`   | `/calls/{id}/transcription` | `calls:read`  |
| `GET`   | `/calls/{id}/summary`       | `calls:read`  |
| `GET`   | `/calls/{id}/voicemail`     | `calls:read`  |
| `PATCH` | `/calls/{id}`               | `calls:write` |

## List calls

```bash
curl "https://app.limecall.com/api/v1/calls?limit=50&page=1" \
  -H "Authorization: Bearer sk_live_..."
```

Newest first. Returns the standard list envelope:

```json
{
  "data": [ { "id": 4812, "from": "+441134960000", "to": "+447700900123", "...": "..." } ],
  "pagination": { "page": 1, "limit": 50, "total": 1284 }
}
```

### Query parameters

| Parameter     | Notes                                                                                                       |
| ------------- | ----------------------------------------------------------------------------------------------------------- |
| `page`        | Defaults to `1`.                                                                                            |
| `limit`       | Defaults to `50`, capped at `200`.                                                                          |
| `userId`      | Only calls belonging to that user.                                                                          |
| `phoneNumber` | Matches **either** leg. Repeatable — pass it more than once to match any of several numbers.                |
| `peer`        | Matches the other party only.                                                                               |
| `since`       | ISO 8601 timestamp, exclusive lower bound on creation. A value that is not a valid timestamp returns `400`. |

`phoneNumber` being repeatable is the useful one: `?phoneNumber=+44113...&phoneNumber=+44114...` returns calls touching either line in one request.

## Get one call

```bash
curl https://app.limecall.com/api/v1/calls/4812 \
  -H "Authorization: Bearer sk_live_..."
```

Returns the call object directly — no envelope. `404` if the id does not exist **or** belongs to another organization; the two are deliberately indistinguishable.

## Recording, transcription, summary, voicemail

Four sub-resources on a call:

```bash
curl https://app.limecall.com/api/v1/calls/4812/transcription \
  -H "Authorization: Bearer sk_live_..."
```

Each returns `404` when that artefact does not exist for the call — a call with recording disabled has no recording, and a call the AI did not handle has no summary. Check rather than assume.

## Write an outcome back

The most valuable call in the API. It is what turns the call log from a record of activity into a record of revenue.

```bash
curl -X PATCH https://app.limecall.com/api/v1/calls/4812 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"outcome":"appointment_booked","value":250,"currency":"USD"}'
```

| Field      | Rules                                                                                                           |
| ---------- | --------------------------------------------------------------------------------------------------------------- |
| `outcome`  | Non-empty string, truncated to 120 characters. Your own vocabulary — reuse the same name and calls group by it. |
| `value`    | A number. Strings that parse as numbers are accepted.                                                           |
| `currency` | Three-letter ISO 4217, case-insensitive, stored uppercase.                                                      |
| `metadata` | A JSON object. Not an array, not a scalar.                                                                      |

**At least one** of `outcome`, `value` or `metadata` must be present — an empty body returns `400`.

Validation runs before anything is written, so a rejected request never half-applies.

### Errors

| Response                                                | Cause                                        |
| ------------------------------------------------------- | -------------------------------------------- |
| `400 Invalid call id`                                   | The id is not a number.                      |
| `400 outcome must be a non-empty string`                | `outcome` present but blank or not a string. |
| `400 value must be a number`                            | `value` will not parse.                      |
| `400 currency must be a 3-letter ISO-4217 code`         | Wrong shape.                                 |
| `400 metadata must be an object`                        | An array or scalar was sent.                 |
| `400 Provide at least one of: outcome, value, metadata` | Nothing to apply.                            |

See [Conversions](/analytics/conversions.md) for what to do with the data once it is flowing.