> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synthpop.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Call analysis
> Send a recording of a call Synthpop didn't place and get back the same transcript, summary, and structured outcome the voice agent produces for its own calls.
Call analysis runs Synthpop's post-call pipeline over **a recording you already
have**. You send a temporary link to the audio; Synthpop transcribes it,
analyzes it, and returns the same [Data Items](/concepts/data-items) a
[voice agent](/guides/engagement/voice-agent) Task returns for a call it placed
itself — through the same Task endpoints you already use.
Nothing is dialed. The call already happened; this analyzes it.
**Availability — enabled organizations, via the `external_recording` `task_type`.**
Call analysis is delivered by creating a Task with `task_type=external_recording`
and is available to organizations that have it **provisioned during onboarding**,
together with at least one recording-mode call flow. If it is not enabled for your
organization, ask your Synthpop contact.
## What it does
Your agents' own calls hold the same information a voice agent call does — whether
supplies were ordered, whether a disclosure was read, how the patient sounded — but
it sits in audio nobody has time to listen to. Call analysis extracts it:
* **Transcribes the recording**, with speaker labels.
* **Analyzes it against a call flow** you've been provisioned, producing the same
`summary` and export attributes the voice agent produces for its own calls.
* **Returns a structured outcome** on the Task, so human-to-human calls and
agent-placed calls land in your workflow in the same shape and can be compared
directly.
Because the output shape matches, a recording-mode flow is typically provisioned as
the counterpart to a live flow you already run — the same analysis config, applied
to calls your own staff made.
## What it is not
Call analysis **places no calls**. There is no dialing, so none of the outbound
machinery applies: no
[contact caps](/guides/engagement/voice-agent#contact-caps), no
[scheduling](/guides/engagement/voice-agent#scheduling), and no `waiting` pause
for call-window reasons. A call-analysis Task runs straight through.
It is also **not a general-purpose transcription API**. The analysis is driven by a
provisioned call flow, which is what turns a transcript into the structured fields
your workflow reads.
## Asynchronous, like every Task
Call analysis follows the standard async model. `POST /task/create` returns
immediately with `status: "pending"`; you then poll `GET /task/get` (or use a
[callback](/guides/async-results)) until the Task reaches a terminal status and read
the outcome from there.
Analysis time is dominated by the length of the recording. Treat it as minutes, not
seconds, and don't set a timeout that assumes otherwise.
## The recording link
You supply the audio as a **temporary HTTPS download link** — a presigned S3 URL, an
Azure SAS URL, or any HTTPS URL that serves the bytes directly. Synthpop downloads
it and **keeps its own durable copy**, so playback and re-analysis keep working after
your link expires.
Three things to get right:
* **HTTPS only.** An `http://` link is rejected at create time.
* **Serve the bytes directly.** A link that returns an HTML page — a cloud-drive
"share" page, for example — or one that redirects elsewhere, will not work. The
fetch does not follow redirects and does not render pages.
* **Keep it valid long enough to be fetched.** The download happens shortly after
create, but not synchronously with it. A link that expires in seconds is a race
you can lose.
A link that has **already expired** usually cannot be detected at create time —
expired presigned S3 and Azure SAS URLs answer in a way that is indistinguishable
from a server that simply refuses the pre-flight check, so the Task is accepted and
fails later instead of returning `400`. Generous expiry windows avoid this
entirely.
`wav` and `mp3` are recognised directly. Other formats are accepted and still
transcribed, but are stored without a format label, so in-browser playback of the
stored copy may not work.
## Using it
`POST /task/create` with `task_type=external_recording` and a `request_spec`
carrying the link, the flow to analyze against, and any context the flow needs.
```bash theme={null}
curl -X POST "https://app.synthpop.ai/public/v1/task/create" \
-H "Authorization: Bearer $SYNTHPOP_JWT_TOKEN" \
-F "task_type=external_recording" \
-F "external_id=case-4821" \
-F 'request_spec={
"recording_url": "https://example-bucket.s3.amazonaws.com/call.mp3?X-Amz-Signature=...",
"call_flow": "your_recording_flow",
"language": "en-US",
"patient_first_name": "Jane",
"patient_last_name": "Doe"
}'
```
| `request_spec` field | Required | Notes |
| -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `recording_url` | Yes | Temporary HTTPS link to the audio. |
| `call_flow` | Yes | A **recording-mode** flow provisioned for your organization. Your Synthpop contact gives you the value. |
| `language` | No | BCP-47 spoken locale of the recording. Defaults to `en-US`. |
| *anything else* | No | Forwarded as context the flow's analysis can reference — patient, order, or case fields, exactly as for a voice Task. |
`your_recording_flow` is an **illustrative** placeholder. Flow names are
provisioned per organization, and the flow must be a **recording-mode** one —
passing a flow built for live calls fails the Task, because a live flow's
analysis can depend on mid-call state a recording never produced.
Poll `GET /task/get` exactly as for any other Task, until the status is
`completed`, `failed`, or `invalid`.
Statuses are exactly `pending`, `processing`, `waiting`, `completed`, `failed`,
`invalid`. A call-analysis Task does not normally reach `waiting` — there is no
call window to defer to and no mid-call input to request.
Once `completed`, the transcript, summary, and recording are available as
[Data Items](/concepts/data-items) on the `TaskDetails`. See
[Reading the outcome](#reading-the-outcome) below.
Set `external_id` to the identifier of the call in your own telephony or CRM
system, then find the Task again with
[`GET /task/list`](/guides/listing-tasks) without storing a second id.
## Reading the outcome
A completed call-analysis Task carries:
| Data Item | Type | Notes |
| ---------------- | ---- | ------------------------------------------------------------------------------ |
| `transcript` | text | Speaker-labeled transcript, in the language spoken. |
| `transcript-en` | text | English translation. Present only when the call was not in English. |
| `summary` | JSON | The flow's analysis — narrative summary plus the structured fields it defines. |
| `call-recording` | file | Synthpop's durable copy of the audio. |
| `call-status` | JSON | Reduced to a single call identifier. |
| `call-metrics` | JSON | The flow's export attributes, evaluated for this recording. |
Two details worth planning around:
* **`call-metrics` is only on `GET /task/get`.** It is fetched live and is not part
of the create response.
* **`request-spec` comes back reduced** to `call_flow` and `language`. Your
`recording_url` is deliberately **not echoed back**, since the link grants access
to the audio; keep your own copy if you need it. The `call-metadata` item is not
returned at all.
The exact fields inside `summary` and `call-metrics` are defined by your provisioned
flow, not by this endpoint — confirm them with your Synthpop contact rather than
assuming they match another organization's.
## Errors at create time
Beyond the [standard errors](/guides/errors), a call-analysis create validates the
recording link up front and returns `400` — so a bad link is a synchronous error, not
a Task that fails minutes later:
| Cause | Message contains |
| ---------------------------------------- | -------------------------------------------- |
| `recording_url` missing or not a string | `must contain a 'recording_url'` |
| `call_flow` missing or not a string | `must contain a 'call_flow'` |
| Link is not HTTPS | `must use https` |
| Link is not a valid URL | `is not a valid URL` / `is malformed` |
| Link could not be reached at all | `could not be reached` |
| Link resolved but the file isn't there | `is not reachable (HTTP 404)` |
| `task_type` not provisioned for your org | `not in list of tasks for your organization` |
The reachability check runs from Synthpop's network. A link reachable only from
inside your own network will be rejected even though your systems can fetch it —
the link has to be publicly resolvable.
## Good to know
Call analysis is driven entirely through the standard Task endpoints in the
[API reference](/api-reference/introduction). You pass a link on create; there is
no upload endpoint, no transcription endpoint, and no call-status API.
There is no deduplication on the recording. Posting the same link again mints a
second, independent Task that re-runs the analysis. Guard against accidental
resubmission on your side if that matters — a unique `external_id` per call makes
duplicates easy to spot with [`GET /task/list`](/guides/listing-tasks).
Unlike an outbound call — which can complete without reaching anyone — a
call-analysis Task reaching `completed` means the recording was transcribed and
analyzed. The *conclusion* of that analysis lives in `summary`, so branch on the
fields your flow defines rather than on the Task status alone.
A call recording is PHI. It is handled under the same controls and retention as
recordings of calls the voice agent places itself — see
[Trust & safety](/guides/engagement/trust) and
[Security & compliance](/reference/security-compliance).
## Where to go next
The same pipeline, for calls Synthpop places itself.
The capability call analysis belongs to.
How PHI handling and call review are enforced.
Polling, callbacks, and terminal statuses.
How Task outputs are structured.
The standard error shapes.