Skip to navigation

Calls, Transcripts and Recordings

View as Markdown

List calls

GET /api/partner/v1/calls
Query parameterDefaultNotes
fromto − 24hISO-8601 UTC, inclusive. Filters on the call start time.
tonowISO-8601 UTC, exclusive. The window may be at most 31 days.
limit501–200, or 1–100 when include contains transcript.
include—Comma-separated subset of transcript, summary. Without it, each item carries only the artifact status.
statusallComma-separated call statuses, e.g. Completed,Transferred.
directionbothinbound or outbound.
agent_id—Restrict to one of your agents.
cursor—Opaque token from the previous page. Only limit may accompany it.

Results are ordered newest first. Pagination is cursor based: pass pagination.next_cursor back as cursor. The time window is frozen inside the cursor, so calls that start while you page never produce duplicates or gaps. A cursor expires after 24 hours and is bound to your company.

curl "https://portal.simz.com/api/partner/v1/calls?cursor=eyJ2IjoxLC….3fA" \
-H "X-Company-API-Key: sk_comp_example"

Call item fields

FieldMeaning
call_idStable SimZ call identifier
started_at, ended_atUTC timestamps; ended_at is null while the call is in progress
duration_secondsBilled seconds; null while in progress
directioninbound or outbound
statusInitiated, Ringing, In-Progress, Answered, Queued, Completed, Transferred, Failed, Busy, No Answer, Canceled, Voicemail, AMD Terminated, Hangup by System, DNC Terminated, Callback Requested
end_reasonWhy the call ended, when known
from_number, to_numberE.164 numbers
client_nameName captured for the call, if any
agent{ id, name } of the SimZ voice agent
campaign, amd_resultCampaign tag and answering-machine detection result, when present
transcript, recording, summaryArtifact objects, see below

Retrieve transcripts for specific calls

POST /api/partner/v1/calls/retrieve
{
"call_ids": ["call_A", "call_B", "call_C"],
"include": ["transcript", "summary"]
}
  • call_ids: 1–100 IDs; duplicates are removed.
  • include: defaults to ["transcript"]. summary returns the AI call summary when one exists.

The response is always 200 when the request is valid; every ID gets its own result:

{
"success": true,
"request_id": "…",
"data": {
"requested": 3,
"found": 2,
"not_found": 1,
"items": [
{ "call_id": "call_A", "status": "found", "call": { "...": "same fields as a list item" },
"transcript": { "status": "available", "format": "segments", "segments": [], "text": "…" },
"summary": { "status": "available", "text": "Caller registered for the Chicago event." } },
{ "call_id": "call_B", "status": "found", "call": { "...": "…" },
"transcript": { "status": "not_available", "reason": "call_not_answered" },
"summary": { "status": "not_available" } },
{ "call_id": "call_C", "status": "not_found" }
]
}
}

not_found means the ID does not exist in your company. Unknown IDs and IDs that belong to another customer are indistinguishable.

Download a recording

GET /api/partner/v1/calls/{call_id}/recording
curl -o call_A.mp3 "https://portal.simz.com/api/partner/v1/calls/call_A/recording" \
-H "X-Company-API-Key: sk_comp_example"
  • Success: 200 with Content-Type: audio/mpeg, Content-Length, and Content-Disposition: attachment; filename="call_A.mp3".
  • Range requests are honoured (206 + Content-Range), so an interrupted download can be resumed.
  • 409 RECORDING_NOT_AVAILABLE carries the same status and reason as the recording object in the list.
  • 404 NOT_FOUND when the call is not in your company.

There are no public or pre-signed download links. Every download is authenticated with your key, encrypted in transit (TLS) and at rest, and recorded in your company’s audit trail.

Artifact objects

transcript

{
"status": "available",
"format": "segments",
"segments": [
{ "speaker": "agent", "text": "…", "timestamp": "2026-11-07T15:03:12.410Z", "offset_ms": 0, "complete": true }
],
"text": "AGENT: …\nUSER: …"
}
  • speaker: agent (the SimZ voice AI), user (the caller or callee), operator (a human who joined the call).
  • offset_ms: milliseconds from the start of the recording.
  • complete: false when the utterance was interrupted.
  • text: the whole conversation flattened as SPEAKER: text lines.

recording

{ "status": "available", "encryption": "none", "content_type": "audio/mpeg", "path": "/api/partner/v1/calls/call_A/recording" }

path is relative to the API host; content_type and path are present only when status is available.

summary

{ "status": "available", "text": "Caller registered for the Chicago event." }

Status values

statusMeaningWhat to do
availableReady. Transcript inline (with include=transcript); recording at recording.path.Fetch it.
processingCall in progress, or still being finalised / transcribed.Re-check on your next run.
not_availableNever produced. reason is call_not_answered, no_transcript, not_recorded or legacy_storage.Nothing to fetch.
failedProcessing failed on SimZ’s side; reason given.Nothing to fetch; contact support with the request_id if unexpected.
expiredPast retention (recordings 90 days, transcripts 180 days).Nothing to fetch.
unavailableTemporary outage on SimZ’s side (reason given).Retry later.