Listing Calls

Listing and Searching Call History

A Call represents a connection between a phone or user agent and the platform. This may be inbound or outbound. The Calls list resource represents the set of phone calls originated and terminated from an account. This section will focus on only using HTTP POST functions.

Section URI

List all calls

/call/2012-04-24/Accounts/{AccountSid}/ListCalls

or

List an individual call

/call/2012-04-24/Accounts/{AccountSid}/ListCalls/{CallSid}

Standard Request Parameters

ParameterRequiredDescription

From

no

The source or from phone number

To

no

The destination or to phone number

Pagination Request Parameters

None of the pagination requests are required

ParameterDescription

Page

The current page number. Zero-indexed, so the first page is 0. 0-20000

PageSize

How many items are on each page 0-2000

StartTime

Only show recordings that were made on this date/time or later EndTime value examples allowed:

2024-04-01T10:10:10

2024-04-01 10:10:10

2024-04-01

EndTime

Only show recordings that were made on this date/time or earlier EndTime value examples allowed:

2024-04-01T10:10:10

2024-04-01 10:10:10

2024-04-01

CallSid

Only show recordings that have been started from this CallSid Value: CallSid=h923fh2h32fj23f2

SortBy

Sort by the date created instead of the most recent on top Value: DateCreated or DateAsc

POST or GET Requests

Send us a request to list the calls for today or search for specific calls

Searching your calls can include POST or GET variables From, To, Sid or Limit.

curl -X POST https://v1.api19.com/call/2012-04-24/Accounts/AC021d7d7d49d3234r34t3ea3769b9ed7/ListCalls \
   -d 'From=17207741111' \
   -d 'To=13038927627' \
   -d 'PageSize=1000 \
   -u '239h2g-23h9-239f23hf:AC021d7d7d49d3234r34t3ea3769b9ed7'

Calls Attributes in Response

Attribute

Description

Sid

A string that uniquely identifies a call.

ParentCallSid

A string that uniquely identifies the call that created this leg.

DateCreated

The date that this call was created.

DateUpdated

The date that this call was last updated.

AccountSid

The unique id of the Account that created this call.

To

The phone number or identifier that will be the recipient of this call.

From

The phone number or identifier that originated this call.

PhoneNumberSid

If the call was inbound, this is the Sid of the IncomingPhoneNumber that received the call.

Status

A string representing the status of the call. Possible values are queued, ringing, in-progress, completed, failed, busy and no-answer.

StartTime

The start time of the call. Empty if the call has not yet been started.

EndTime

The end time of the call. Empty if the call has not ended.

Duration

The length of the call in seconds.

Price

The charge for this call, in the currency associated with the account. Populated after the call is completed.

Direction

A string describing the direction of the call. Possible values are inbound, outbound-api, and outbound-dial

AnsweredBy

If this call was initiated with answering machine detection, either human or machine. Empty otherwise.

ApiVersion

Displays the current API version

ForwardFrom

If this call was an incoming call forwarded from another number, the forwarding phone number (depends on carrier supporting forwarding). Empty otherwise.

CallerName

If this call was an incoming call, the caller’s name. Empty otherwise.

Uri

The URI for this account, relative to https://v1.api19.com/call/2012-04-24/Accounts

Get call details

Example JSON Responses

Here is what the JSON will look like when there are multiple calls vs a single call

{
  "sid": "IDf0cbf85b95df45deb3cb404235e7c26e-CA9a2229464e2843dd84903313b5680714",
  "InstanceId": "IDf0cbf85b95df45deb3cb404235e7c26e",
  "date_created": "Wed, 4 Sep 2024 00:26:56 +0000",
  "date_updated": "Wed, 4 Sep 2024 00:27:03 +0000",
  "account_sid": "AC025S7d7d49d7f923432552ea3769b9ed7",
  "to": "1303666627",
  "from": "1720444493",
  "status": "in-progress",
  "start_time": "2024-09-04T00:27:03.381Z",
  "duration": 0,
  "price_unit": "USD",
  "direction": "outbound-api",
  "answered_by": "1303666627",
  "api_version": "2012-04-24",
  "caller_name": "1720444493",
  "uri": "/call/2012-04-24/Accounts/AC025S7d7d49d7f923432552ea3769b9ed7/Calls/IDf0cbf85b95df45deb3cb404235e7c26e-CA9a2229464e2843dd84903313b5680714.json",
  "ring_duration": 3,
  "subresource_uris": {
    "notifications": "/call/2012-04-24/Accounts/AC025S7d7d49d7f923432552ea3769b9ed7/Calls/IDf0cbf85b95df45deb3cb404235e7c26e-CA9a2229464e2843dd84903313b5680714/Notifications.json",
    "recordings": "/call/2012-04-24/Accounts/AC025S7d7d49d7f923432552ea3769b9ed7/Calls/IDf0cbf85b95df45deb3cb404235e7c26e-CA9a2229464e2843dd84903313b5680714/Recordings.json"
  }
}
PreviousIncoming CallsNextMaking Calls

Last updated