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

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

Newest first. Returns the standard list envelope:

{
  "data": [ { "id": 4812, "from": "[phone]", "to": "[phone]", "...": "..." } ],
  "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

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:

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.

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 for what to do with the data once it is flowing.