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

# Calls, Transcripts and Recordings

> The three Call Export endpoints and the artifact status model.

## List calls

```text
GET /api/partner/v1/calls
```

| Query parameter | Default    | Notes                                                                                                        |
| --------------- | ---------- | ------------------------------------------------------------------------------------------------------------ |
| `from`          | `to − 24h` | ISO-8601 UTC, **inclusive**. Filters on the call **start** time.                                             |
| `to`            | now        | ISO-8601 UTC, **exclusive**. The window may be at most 31 days.                                              |
| `limit`         | `50`       | 1–200, or 1–100 when `include` contains `transcript`.                                                        |
| `include`       | —          | Comma-separated subset of `transcript`, `summary`. Without it, each item carries only the artifact *status*. |
| `status`        | all        | Comma-separated call statuses, e.g. `Completed,Transferred`.                                                 |
| `direction`     | both       | `inbound` 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.

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

### Call item fields

| Field                                | Meaning                                                                                                                                                                                                                       |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `call_id`                            | Stable SimZ call identifier                                                                                                                                                                                                   |
| `started_at`, `ended_at`             | UTC timestamps; `ended_at` is `null` while the call is in progress                                                                                                                                                            |
| `duration_seconds`                   | Billed seconds; `null` while in progress                                                                                                                                                                                      |
| `direction`                          | `inbound` or `outbound`                                                                                                                                                                                                       |
| `status`                             | `Initiated`, `Ringing`, `In-Progress`, `Answered`, `Queued`, `Completed`, `Transferred`, `Failed`, `Busy`, `No Answer`, `Canceled`, `Voicemail`, `AMD Terminated`, `Hangup by System`, `DNC Terminated`, `Callback Requested` |
| `end_reason`                         | Why the call ended, when known                                                                                                                                                                                                |
| `from_number`, `to_number`           | E.164 numbers                                                                                                                                                                                                                 |
| `client_name`                        | Name captured for the call, if any                                                                                                                                                                                            |
| `agent`                              | `{ id, name }` of the SimZ voice agent                                                                                                                                                                                        |
| `campaign`, `amd_result`             | Campaign tag and answering-machine detection result, when present                                                                                                                                                             |
| `transcript`, `recording`, `summary` | Artifact objects, see below                                                                                                                                                                                                   |

## Retrieve transcripts for specific calls

```text
POST /api/partner/v1/calls/retrieve
```

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

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

```text
GET /api/partner/v1/calls/{call_id}/recording
```

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

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

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

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

### Status values

| `status`        | Meaning                                                                                               | What to do                                                             |
| --------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `available`     | Ready. Transcript inline (with `include=transcript`); recording at `recording.path`.                  | Fetch it.                                                              |
| `processing`    | Call in progress, or still being finalised / transcribed.                                             | Re-check on your next run.                                             |
| `not_available` | Never produced. `reason` is `call_not_answered`, `no_transcript`, `not_recorded` or `legacy_storage`. | Nothing to fetch.                                                      |
| `failed`        | Processing failed on SimZ's side; `reason` given.                                                     | Nothing to fetch; contact support with the `request_id` if unexpected. |
| `expired`       | Past retention (recordings 90 days, transcripts 180 days).                                            | Nothing to fetch.                                                      |
| `unavailable`   | Temporary outage on SimZ's side (`reason` given).                                                     | Retry later.                                                           |