Skip to navigation

Quickstart

View as Markdown

The Call Export API lets a partner or white-label customer retrieve its own voice-AI call history from SimZ: call metadata for any time window, full transcripts, and recording downloads. It is read-only and scoped to your company — a key issued to your company can never see another company’s calls.

Base path

/api/partner/v1

Authentication

Every request carries a company API key with the calls:read scope in the X-Company-API-Key header. A company admin creates it in the SimZ portal under API Access → API Keys; the full key is shown once. Up to two keys can be active at the same time so you can rotate without downtime.

The Call Export API must be enabled for your company by SimZ before keys can be created. Contact your SimZ representative if the API Keys tab is not visible.

First request

curl "https://portal.simz.com/api/partner/v1/calls?from=2026-11-07T00:00:00Z&to=2026-11-08T00:00:00Z&include=transcript&limit=100" \
-H "X-Company-API-Key: sk_comp_example"
{
"success": true,
"request_id": "4d1b0e2a-7c3f-4f1e-9b6a-2d9e8a1c5f00",
"data": [
{
"call_id": "call_1762561234567_ab12cd",
"started_at": "2026-11-07T15:03:11.000Z",
"ended_at": "2026-11-07T15:07:40.000Z",
"duration_seconds": 269,
"direction": "inbound",
"status": "Completed",
"end_reason": "caller_hangup",
"from_number": "+13125550123",
"to_number": "+18667401998",
"client_name": "Jane Doe",
"agent": { "id": "agent_123", "name": "Registration Line" },
"campaign": null,
"amd_result": null,
"transcript": {
"status": "available",
"format": "segments",
"segments": [
{ "speaker": "agent", "text": "Thanks for calling…", "timestamp": "2026-11-07T15:03:12.410Z", "offset_ms": 0, "complete": true },
{ "speaker": "user", "text": "Hi, I'd like to…", "timestamp": "2026-11-07T15:03:16.530Z", "offset_ms": 4120, "complete": true }
],
"text": "AGENT: Thanks for calling…\nUSER: Hi, I'd like to…"
},
"recording": {
"status": "available",
"encryption": "none",
"content_type": "audio/mpeg",
"path": "/api/partner/v1/calls/call_1762561234567_ab12cd/recording"
},
"summary": null
}
],
"pagination": { "limit": 100, "returned": 1, "has_more": false, "next_cursor": null }
}

Response envelope

All JSON responses share one shape and carry an X-Request-Id header. Quote the request ID when you contact SimZ support.

{ "success": true, "request_id": "…", "data": {}, "pagination": {} }
{ "success": false, "error": "human readable", "code": "UPPER_SNAKE", "request_id": "…" }
  1. Every 15 minutes call GET /calls with from = the to of your previous successful run, to = now, include=transcript, limit=100. Follow pagination.next_cursor until has_more is false.
  2. Persist each call_id and skip IDs you already stored.
  3. For items whose recording.status is available, download recording.path right away.
  4. Items that were processing (call still in progress or still being transcribed) are re-checked on the next run with POST /calls/retrieve.
  5. Retry 429 after Retry-After seconds and 503 with exponential backoff. Every endpoint is read-only and safe to retry.

Data retention

Recordings are kept for 90 days and transcripts for 180 days after the call. Older artifacts are reported with status: "expired". Plan your backfill accordingly.

What is and is not returned

Returned per call: identifiers, start/end time, duration, direction, status, the phone numbers, the captured client name, the handling agent, transcript (on request) and a recording download path.

Never returned: internal storage keys, telephony provider identifiers, prompt or model configuration, billing data.

Transcripts are returned as captured (not redacted).