Skip to content

List call history

GET
/v1/organizations/{org}/calls
curl --request GET \
--url 'https://api.caller9.app/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/calls?direction=inbound&page=1&limit=50' \
--header 'Authorization: Bearer <token>'

Paginated, newest-first history of inbound and outbound calls across the organization. Requires a full-access key.

org
required
string format: uuid

Organization ID (UUID). Must be the organization that owns the API key.

q
string

Phone number search. Non-digits are stripped; matches calls whose external party or dialed Caller 9 number contains the digits.

direction
string
Allowed values: inbound outbound

Filter by direction. Other values are ignored.

trunk
string

Filter to calls on a SIP trunk: a trunk ID, or any for calls on any trunk.

page
integer
default: 1 >= 1

Page number (1-based).

limit
integer
default: 50 >= 1 <= 200

Page size. Values are clamped to 1–200.

A page of call history.

Media typeapplication/json
object
calls
required
Array<object>

A call in the organization’s call history.

object
guid

Call ID.

string
direction
string
Allowed values: inbound outbound
number

The external party (caller for inbound, callee for outbound), E.164.

string
caller

Caller ID name (may equal the number).

string
status
string
call_type
string | null
Allowed values: primary hotline
error_code
string | null
billable
integer
Allowed values: 0 1
billed_minutes
integer | null
screening_billed_minutes
integer | null
went_to_voicemail
integer
Allowed values: 0 1
went_to_forward
integer
Allowed values: 0 1
forward_to
string | null
forward_dest_type
string | null
Allowed values: sip phone
queued_at
string | null format: date-time
initiated_at
string format: date-time
answered_at
string | null format: date-time
ended_at
string | null format: date-time
trunk_guid

SIP trunk the call used, if any.

string | null
trunk_name
string | null
studio_name

Studio the call landed in (null for calls that never reached a studio).

string | null
did_number

The Caller 9 phone number involved.

string | null
number_name

That phone number’s label.

string | null
total
required

Total calls matching the filters.

integer
page
required
integer
limit
required
integer

Example

{
"calls": [
{
"direction": "inbound",
"call_type": "primary",
"billable": 0,
"went_to_voicemail": 0,
"went_to_forward": 0,
"forward_dest_type": "sip"
}
]
}

Missing, invalid, expired or revoked API key.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

The key isn’t allowed to do this (e.g. a read-only key making a change).

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Not found, or belongs to another organization.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Too many requests for this API key. Retry after Retry-After seconds.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}
Retry-After
integer

Seconds until the rate-limit window resets.