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

# Voice agent

> Place and handle patient phone calls through the API — the voice agent has the conversation and returns a structured outcome on the Task.

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](/guides/engagement/capabilities); for how those
guardrails and disclosures are enforced, see
[Trust & safety](/guides/engagement/trust).

<Info>
  **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.
</Info>

## 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](/guides/engagement/overview), voice is a patient
engagement channel: you create a Task, the work happens, and you read the outcome
from the same [`TaskDetails`](/concepts/tasks) 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](/guides/async-results)) until the Task
reaches a terminal status and read the outcome from there.

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

## 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](/concepts/data-items) 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](/guides/engagement/capabilities#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](#asynchronous-like-every-task) above.)

## Using it

<Steps>
  <Step title="Create a voice Task">
    `POST /task/create` with your voice `task_type` and the context the call needs.

    ```bash theme={null}
    curl -X POST "https://app.synthpop.ai/public/v1/task/create" \
      -H "Authorization: Bearer $SYNTHPOP_JWT_TOKEN" \
      -F "task_type=patient_voice_call" \
      -F "external_id=case-4821"
    ```

    <Note>
      `patient_voice_call` is an **illustrative** placeholder, not a real value.
      Voice `task_type`s 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: [...]."`
    </Note>
  </Step>

  <Step title="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](/guides/responding-to-waiting-tasks). A
    synchronous result already carried on the create response (see
    [Asynchronous, like every Task](#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`.
  </Step>

  <Step title="Read the call outcome">
    Once the Task is `completed`, the outcome of the call is available as
    [Data Items](/concepts/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](#reading-the-outcome) below for exactly which Data Items
    to expect.
  </Step>
</Steps>

<Tip>
  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`](/guides/listing-tasks).
</Tip>

## Reading the outcome

Every voice Task returns a `transcript` and a `summary` [Data
Item](/concepts/data-items) 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_type`s (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

<AccordionGroup>
  <Accordion title="No calling or telephony endpoints">
    The voice agent is driven entirely through the standard Task endpoints in the
    [API reference](/api-reference/introduction). Choosing a voice `task_type` on
    create is the only lever — there is no separate dial, transcript, or call-status
    API to integrate.
  </Accordion>

  <Accordion title="It's an engagement channel">
    Voice sits alongside digital outreach under
    [Patient engagement](/guides/engagement/overview). Both reach patients and
    return their outcome on the Task; voice is simply the phone-call channel.
  </Accordion>
</AccordionGroup>

## Where to go next

<CardGroup cols={2}>
  <Card title="Patient engagement" icon="phone" href="/guides/engagement/overview">
    The engagement capability voice belongs to.
  </Card>

  <Card title="Voice agent capabilities" icon="list-check" href="/guides/engagement/capabilities">
    What the agent can do on a call, and the guardrail behind each capability.
  </Card>

  <Card title="Trust & safety" icon="shield-check" href="/guides/engagement/trust">
    How call review, PHI handling, and contact limits are enforced.
  </Card>

  <Card title="Working with async results" icon="clock" href="/guides/async-results">
    Polling, callbacks, and terminal statuses.
  </Card>

  <Card title="Tasks" icon="cube" href="/concepts/tasks">
    The core resource and its status lifecycle.
  </Card>

  <Card title="The patient journey" icon="route" href="/concepts/patient-journey">
    How engagement closes the loop after intake and coverage.
  </Card>
</CardGroup>