Call analysis

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 a 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, no 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) 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

Create a call-analysis Task

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.

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 for the outcome

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.

Read the analysis

Once completed, the transcript, summary, and recording are available as Data Items on the TaskDetails. See 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 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, 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

No separate transcription or upload endpoint

Call analysis is driven entirely through the standard Task endpoints in the API reference. You pass a link on create; there is no upload endpoint, no transcription endpoint, and no call-status API.

Sending the same recording twice creates two Tasks

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.

A completed Task means the analysis ran

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.

PHI in the recording

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 and Security & compliance.

Where to go next

Voice agent

The same pipeline, for calls Synthpop places itself.

Patient engagement

The capability call analysis belongs to.

Trust & safety

How PHI handling and call review are enforced.

Working with async results

Polling, callbacks, and terminal statuses.

Data Items

How Task outputs are structured.

Errors

The standard error shapes.

Get started

Core concepts

Working with the API

Referral & order intake

Coverage & authorization

Patient engagement

Resources

Support

What it does

What it is not

Asynchronous, like every Task

The recording link

Using it

Reading the outcome

Errors at create time

Good to know

Where to go next

Voice agent

Patient engagement

Trust & safety

Working with async results

Data Items

Errors

​What it does

​What it is not

​Asynchronous, like every Task

​The recording link

​Using it

​Reading the outcome

​Errors at create time

​Good to know

​Where to go next

Voice agent

Patient engagement

Trust & safety

Working with async results

Data Items

Errors

What it does

What it is not

Asynchronous, like every Task

The recording link

Using it

Reading the outcome

Errors at create time

Good to know

Where to go next