---
title: "Place a real voice call via Sierra"
method: POST
path: "/api/v1/ca/voice-calls"
tags: ["CA Voice Calls"]
---

# Place a real voice call via Sierra

`POST /api/v1/ca/voice-calls`

## Request

- Base URL: `https://api.cloverhealth.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.cloverhealth.com/api/v1/ca/voice-calls`
- Auth: HTTP bearer

Dispatch a real (non-test) Sierra voice-agent call. For
``mammogram-member-availability``, dispatched to Sierra's Playbook API
directly, in-request; for the direct-agent purposes, queued for
dispatch by ``OutboundCallWorker`` (GE-2565/GE-2832). No dry-run/confirm
gate -- once a dispatch is actually attempted, the response is always
``202 {"status": "queued"}`` regardless of purpose or outcome; the real
outcome (dispatched, failed, or a Sierra-reported disposition) is only
ever visible via ``POST .../results``. A request that can't even be
attempted -- ``ENABLE_CA_VOICE_CALLS`` off, or a missing
``SIERRA_PLAYBOOKS_API_TOKEN`` -- returns ``502`` instead, before any
audit row exists.

Requires scope: voice_calls:write

For the direct-agent purposes, ``inputs`` may override the standard member
fields MC2 derives from the member record: ``patient_first_name``,
``patient_last_name``, ``patient_dob``, ``patient_address``,
``patient_email_address``, ``patient_phone`` and ``language_preference``
(``member_id`` is never overridable). Each must be a non-blank string;
``patient_phone`` must be a dialable US or Canadian E.164 number and, for the
agents that call the member, is also the number dialed; ``language_preference``
is passed through as sent (for example ``chinese``), not checked against a list
of languages. An invalid override is a 422.

The ``Idempotency-Key`` request header is required. Replaying the same
key for the same ``api_client`` returns the original ``queued`` response
rather than dispatching again -- but only if the request body is
unchanged; reusing a key with a different body returns 409 instead.

## Request body

- VoiceCallRequest: Request body for ``POST /api/v1/ca/voice-calls`` (real, non-test dispatch). No dry-run/confirm gate -- the caller's idempotency key is supplied via the ``Idempotency-Key`` request header, not this body. ``subscriber_id`` is required for every purpose, including facility-scheduling-agent: every direct agent receives the member's standard identity fields, and the facility call is about a particular member. For the direct agents, ``inputs`` may override the keys in ``MEMBER_FIELD_OVERRIDE_KEYS``.
  - `purpose` string, required
  - `subscriber_id` string
  - `inputs` object
  - `caller_id_number` string, nullable

## Response `202`

Accepted

- VoiceCallDispatchResponse: Response for ``POST /api/v1/ca/voice-calls``. ``id`` is the Engagement id -- what ``POST /api/v1/ca/voice-calls/results`` is later polled with, not Sierra's own call id. ``status`` is always ``"queued"`` (GE-2565) -- dispatch is now async for every purpose; the real outcome (including a Sierra-side dispatch failure) is only ever visible via ``/results``, never in this response.
  - `id` string, required
  - `status` 'queued', required

## Other responses

- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `502`: Bad Gateway

## Changes

- **2026-10-15** `13a895e58953`: 1 info
  - added the new optional request property `caller_id_number`
- **2026-09-24** `d3674766b6b4`: 2 info
  - the request property `subscriber_id` became optional
  - the `subscriber_id` request property default value `` was added
- **2026-09-18** `b61680b5f1e8`: 2 breaking, 5 info
  - the response's body type changed from no type to `object` for status `409`
  - removed the required property `error` from the response with the `202` status
  - removed `#/components/schemas/IdempotencyKeyReusedResponse, #/components/schemas/RequestInProgressResponse` from the response body `anyOf` list for the response status `409`
  - added the optional property `error` to the response with the `409` status
  - …3 more
- **2026-09-04** `da40ef807c67`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cloverhealth/apis/clover-api/changes/api/v1/ca/voice-calls/post.md)

---

[API](https://skmtc.dev/cloverhealth/apis/clover-api.md) - [All operations](https://skmtc.dev/cloverhealth/apis/clover-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cloverhealth/apis/clover-api/revisions/824d541751f2?raw)