frecall Developers
API reference API operational Get API key
Frecall Call API · v1

Bring customer conversations into your workflow.

Read call history, customer-specific conversations, service outcomes, timing, ratings, and short-lived recording links through one focused REST API.

Make your first request ↓ Download OpenAPI
Production base URL https://api.frecall.com/v1
ProtocolHTTPS + JSONPredictable REST responses
AuthenticationBearer API keyScoped and revocable
Recordings30-minute URLsCreated only when requested
01 · Quick start

Make your first request in minutes.

Generate a key from your manager workspace, keep it on a trusted server, then request the newest calls in your account.

2

Store it as a secret

Use your backend environment or secret manager. Never embed the key in browser, Android, or iOS application code.

3

List your calls

Send the key as a Bearer token and follow the returned opaque cursor when another page is available.

Terminal
curl "https://api.frecall.com/v1/calls?limit=20" \
  -H "Authorization: Bearer $FRECALL_CALL_API_KEY"
02 · Authentication

One secret, tightly controlled.

Every protected endpoint expects an API key in the HTTP Authorization header.

Server-side only

Treat the key like a password. Frecall stores only its SHA-256 hash. Rotation revokes the previous key immediately.

  • Scopecalls:read is always required
  • Recordingrecordings:read is optional
  • Expiry30–365 days, controlled by you
  • NetworkOptional server IP allowlist
HTTP authorization header Authorization: Bearer fc_live_...

Keys entered into the playground below remain in page memory only and disappear on refresh.

03 · Interactive playground

Explore a request before you write code.

Choose an endpoint, adjust its inputs, generate language examples, or run a real request with your key.

Request builderConfigure endpoint
Key not saved
GET/v1/calls?limit=20

Real requests count toward your API rate limit and update the key’s last-used status.

Example response200 OK
GET/v1/calls

List calls

Returns calls across every room owned by the authenticated manager, newest first.

Query parameterTypeDescription
limitinteger

Items per page. Default 20; maximum 50.

cursorstring

Opaque cursor returned by the previous response.

GET/v1/customers/{customerId}/calls

List customer calls

Returns only the conversations associated with one customer identifier. This is the recommended endpoint for customer-profile integrations.

ParameterTypeDescription
customerIdstring

Required customer identifier used when joining Frecall.

limitinteger

Items per page. Default 20; maximum 50.

cursorstring

Opaque cursor for the next page.

GET/v1/calls/{callId}

Get one call

Returns the complete six-field call object, including comments and recording metadata where available.

idCall-log identifier
customerIdYour customer identifier
agentAgent ID and display name
timingQueue, answer, and connected times
resultOutcome, rating, and call health
recordingAvailability and file metadata
GET/v1/calls/{callId}?includeRecording=true

Request recording access

Creates a signed listening URL only when playback is requested. The URL expires after 30 minutes and requires the recordings:read scope.

Authorized user selects Play→Your trusted backend calls Frecall→30-minute MP3 URL returned
Keep playback ephemeral

Hold the signed URL in frontend memory only. Do not save it in Firestore, logs, analytics, or long-lived application state.

04 · Pagination

Move through history with opaque cursors.

When paging.hasMore is true, pass paging.nextCursor unchanged to the next request. Never decode, edit, or manufacture a cursor.

JSON
{
  "paging": {
    "nextCursor": "opaque-cursor",
    "hasMore": true
  }
}
05 · Timing semantics

Every duration has one clear meaning.

01
ringAt

Customer entered the queue.

02
assignedAt

An agent successfully claimed the call.

03
answeredAt

Both participants established LiveKit media.

04
endedAt

The call was successfully finalized.

durationSeconds measures connected talk time. Recording duration can differ by a few seconds because LiveKit Egress starts and finalizes separately.

06 · Outcomes

Understand how the conversation finished.

completedAnswered and ended normally.
unansweredEnded before an answer.
activeConnected and still ongoing.
abandoned_in_queueExceeded the unanswered queue limit.
agent_no_answerAssigned agent did not establish media.
connection_failedRoom ended before media connected.
07 · Errors and limits

Errors are predictable and actionable.

StatusCodeMeaning
400invalid_cursor

A pagination cursor is malformed.

401unauthorized

The key is missing, invalid, or expired.

403forbidden

The key lacks a required scope or IP access.

404not_found

The endpoint or owned call does not exist.

429rate_limited

The key exceeded 120 requests per minute.

Error shape
{
  "error": {
    "code": "unauthorized",
    "message": "A valid API key is required."
  }
}
08 · Security

Designed for trusted server integrations.

Keys are scoped to one manager account and calls are returned only when their room belongs to that manager.

✓ TLS required ✓ Hashed keys at rest ✓ Immediate rotation ✓ Optional IP restrictions ✓ Private recording bucket ✓ Short-lived playback URLs
Changelog

API v1

Developer portal and diagnostics

Added interactive documentation, OpenAPI 3.1, API discovery, request IDs, version headers, and rate-limit response headers. Existing endpoints and response fields remain unchanged.

Recording access

Added private MP3 metadata and on-demand 30-minute signed listening URLs.