Skip to main content
The voice agent places and handles patient phone calls on your behalf. You create a Task; the voice agent calls the patient, has the conversation needed to gather or confirm what the case requires, and returns a structured outcome you can act on — all through the same API you already use. For what the agent can do on a call and the guardrails around each capability, see Voice agent capabilities; for how those guardrails and disclosures are enforced, see Trust & safety.
Availability — enabled organizations, via a voice task_type. The voice agent is delivered by creating a Task with a voice task_type and is available to organizations that have it provisioned during onboarding. There is no separate telephony or calling API — voice runs through the standard Task endpoints. If voice is not enabled for your organization, ask your Synthpop contact.

​
What it does

A phone call is the fastest way to close some gaps — confirming a detail, reaching a patient who never returned a form, answering a question that needs a human on the line. The voice agent automates that call:
  • Places outbound calls to the patient on your behalf, and answers inbound calls from patients calling in — both directions run through the same voice task_type and land on the same Task shape.
  • Handles the conversation to gather or confirm the information the case needs.
  • Returns a structured outcome on the Task — what happened on the call, and what was collected — so the result flows straight back into your workflow.
Like digital outreach, voice is a patient engagement channel: you create a Task, the work happens, and you read the outcome from the same TaskDetails shape as everything else.

​
Asynchronous, like every Task

Voice Tasks follow the standard async model — there is no special case to learn. 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.
A specific inbound configuration provisioned for some organizations can make create return a result synchronously. Treat that as an optimization, not the contract — always keep the poll loop, since it is what makes your integration correct regardless of whether that configuration applies to you.

​
Scheduling

A call can be scheduled for later instead of placed immediately. Externally this looks like any other in-flight Task: the status reads pending (there is no separate “scheduled” status). The target time is exposed as a schedule-status Data Item on the Task, not in the status field — check that Data Item if you need to know when the call is expected to happen.

​
Contact caps

Outbound calling is bounded by the guardrails described in Respects contact limits: at most once a day, at most three times in a rolling seven days, with an optional local-time calling window. On the standard async path, a call that would exceed the cap is not placed: the Task pauses at waiting and carries a machine-readable reason for why it didn’t proceed. Branch on that reason rather than blindly retrying — retrying before the window reopens will hit the same cap every time. (A create-time 403 from POST /task/create is only possible on the synchronous inbound configuration provisioned for some organizations — see Asynchronous, like every Task above.)

​
Using it

1

Create a voice Task

POST /task/create with your voice task_type and the context the call needs.
patient_voice_call is an illustrative placeholder, not a real value. Voice task_types are provisioned per organization; your Synthpop contact tells you the concrete value to use. Passing an unprovisioned type returns 400 "Task type 'X' not in list of tasks for your organization: [...]."
2

Poll for the outcome

Poll GET /task/get exactly as you would for any other Task, until the status is completed, failed, or invalid. If the Task pauses at waiting, it needs more input from you before it can proceed — see Responding to waiting tasks. A synchronous result already carried on the create response (see Asynchronous, like every Task above) is a possible early result for some org configurations, not something to rely on — keep polling regardless.Statuses are exactly pending, processing, waiting, completed, failed, invalid.
3

Read the call outcome

Once the Task is completed, the outcome of the call is available as Data Items on the TaskDetails — what happened on the call and what was gathered — ready to route back into your workflow. See Reading the outcome below for exactly which Data Items to expect.
Set external_id on create to tie the call back to the intake or coverage case it follows up on, then find related Tasks with GET /task/list.

​
Reading the outcome

Every voice Task returns a transcript and a summary Data Item once it completes; a call recording may also be available, depending on the provisioned voice task_type. Beyond the reliably-present transcript and summary, the exact set of Data Items depends on which voice task_type your organization is provisioned into — the shape is a provisioning question, not a universal contract:
  • A patient_caller Task’s response is field-filtered: there is no call-metadata item, call-status is reduced to just a call identifier, and request-spec is restricted to a smaller set of fields. GET /task/get for a patient_caller Task also appends a live call-metrics Data Item that isn’t present on the create response.
  • Other voice task_types (for example a general voice agent or an automation variant) return their Data Items unfiltered.
Treat the concrete set of Data Items as specific to your org’s provisioned voice task_type, and confirm the exact shape with your Synthpop contact rather than assuming it matches another organization’s integration.

​
Good to know

The voice agent is driven entirely through the standard Task endpoints in the API reference. Choosing a voice task_type on create is the only lever — there is no separate dial, transcript, or call-status API to integrate.
Voice sits alongside digital outreach under Patient engagement. Both reach patients and return their outcome on the Task; voice is simply the phone-call channel.

​
Where to go next

Patient engagement

The engagement capability voice belongs to.

Voice agent capabilities

What the agent can do on a call, and the guardrail behind each capability.

Trust & safety

How call review, PHI handling, and contact limits are enforced.

Working with async results

Polling, callbacks, and terminal statuses.

Tasks

The core resource and its status lifecycle.

The patient journey

How engagement closes the loop after intake and coverage.