> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.simz.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.simz.com/_mcp/server.

# Quickstart

> Pull your company's call history, transcripts and recordings into your own system.

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

```text
/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

```bash
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"
```

```json
{
  "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.

```json
{ "success": true, "request_id": "…", "data": {}, "pagination": {} }
```

```json
{ "success": false, "error": "human readable", "code": "UPPER_SNAKE", "request_id": "…" }
```

## Recommended sync loop

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).