Skip to main content
GET
List all calls
Use GET /calls to retrieve call records across all customers in the company associated with your X-API-Key. No customer ID is required, and there is no default date cutoff. The response includes inbound calls, outbound calls, uploaded recordings, and unsuccessful attempts, including records still being processed. Test-customer calls are included. Deleted calls, calls belonging to deleted customers, and legacy calls without a creation timestamp are excluded. For calls made to borrowers, use callType=OUTBOUND. Future scheduled calls are available through the Scheduled Calls API.

First request

id is the stable Finosu call UUID, also accepted by Get Call by ID. customerId is your external customer reference, falling back to the Finosu customer UUID when no reference is stored. duration is in seconds. timestamp is the call record’s creation time. status describes its processing stage; callResult describes its outcome. Outcomes, duration, transcripts, and phone numbers can be null when unavailable. Fetch a call by ID for its recording link; recordings are omitted from the bulk listing so exports do not require a storage lookup for every call. Recording links expire after one hour and can be refreshed by fetching the call again.

Retrieve every page

Calls are ordered newest first by creation time, then call UUID to break ties. limit defaults to 50 and accepts 1–100. Pagination happens in the database. The endpoint allows 60 requests per 60-second window per company, shared across its API keys. If the quota is exhausted (429) or its enforcement is temporarily unavailable (503), wait for the Retry-After interval before retrying the same page. When nextCursor contains a string, pass that exact value as the next request’s cursor. Keep the same API-key company and filters on every page; you may change limit. Treat cursors as opaque and URL-encode them. A null cursor means the export is complete. An empty result is {"calls": [], "nextCursor": null}. This Python example writes one call per line to a private JSON Lines file without accumulating the entire history in memory or logging call data. It requires the requests package, a FINOSU_API_KEY environment variable, and FINOSU_CALL_EXPORT_PATH set to a new file in an access-controlled directory. On POSIX systems, the file is readable and writable only by its owner; on other systems, configure equivalent directory permissions. The example refuses to overwrite an existing file. Treat the export as sensitive data: it contains customer identifiers, phone numbers, and transcripts. The example retries 429 and 503 responses up to four times per page, respecting Retry-After. A failed request can leave a partial export.
Newer calls created during pagination appear in a fresh traversal; they do not shift subsequent pages. This is a live history, not a frozen snapshot: existing call outcomes and artifacts can change as processing finishes, and backfilled or deleted records can change the available history. Deduplicate exports by id. Use call webhooks for completed-call updates, or reread an overlapping creation-time window to refresh recent records.

Filter the history

All filters are optional and combined: Dates must include a timezone (Z or an explicit offset). createdAfter must precede createdBefore. These filters use creation time, not last-updated time. Unknown customer references return an empty list.

Errors

Errors use FastAPI’s detail field. Validation errors contain an array of field errors; authentication, cursor/range, and quota errors contain a string. Existing call-by-ID and customer-specific routes retain their current response shapes.

Authorizations

X-API-Key
string
header
required

Query Parameters

limit
integer
default:50

Maximum records per page. Default 50; range 1–100.

Required range: 1 <= x <= 100
cursor
string

Opaque nextCursor from the preceding response. Keep the same company and filters.

Required string length: 1 - 2048
customerId
string

Exact external customer reference. Unknown references return an empty list.

Required string length: 1 - 255
callType
enum<string>

Filter by call type; omit for all types.

Available options:
INBOUND,
OUTBOUND,
UPLOAD
createdAfter
string<date-time>

Inclusive creation-time lower bound. Must include a timezone and precede createdBefore.

createdBefore
string<date-time>

Exclusive creation-time upper bound. Must include a timezone.

Response

A page of calls, newest first. nextCursor is null on the last page.

calls
object[]
required
nextCursor
string | null
required

Opaque continuation cursor, or null when no more records remain.