> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Place a Call

> Place an outbound programmable voice call, optionally bridging to an agent on answer.

Places an outbound call from one of your assigned numbers to a destination. When `connectTo` is supplied, the destination and the connect target are bridged into a conference once the call is answered.

Requires the `voice_calls.write` scope and the **Voice Calls** product entitlement.

## Body Parameters

<ParamField body="to" type="string" required>
  Destination phone number in E.164 format (e.g. `+14155551234`).
</ParamField>

<ParamField body="from" type="string" required>
  The calling number in E.164 format. Must be a number that has been assigned to your account.
</ParamField>

<ParamField body="connectTo" type="string" optional>
  A number to bridge the call to once it is answered. Accepts either an E.164 number or the `id` of a [voice agent](/api-reference/voice/agents/create-agent). The resolved destination is screened against your account's compliance suppression (DNC, opt-out, quiet hours) before dialing.
</ParamField>

<ParamField body="record" type="boolean" default={false}>
  Whether to record the call from the moment it is answered. Recording may require caller consent — see [call recording](/api-reference/voice/overview#call-recording).
</ParamField>

<ParamField body="customData" type="object" optional>
  Arbitrary key/value metadata echoed back on the call object and forwarded to the provider. Values must be JSON-serializable.
</ParamField>

## Headers

<ParamField header="Idempotency-Key" type="string" optional>
  A unique key to make the request idempotent. A retry with the same key returns the original call instead of placing a second one.
</ParamField>

## Response Fields

<ResponseField name="call" type="object">
  The created call.

  <Expandable title="Call properties" defaultOpen>
    <ResponseField name="call.id" type="string">The call's unique identifier.</ResponseField>
    <ResponseField name="call.direction" type="string">`outbound` for calls placed through this endpoint.</ResponseField>
    <ResponseField name="call.state" type="string">Lifecycle state. A freshly placed call starts as `calling`. See [Call states](/api-reference/voice/overview#call-states).</ResponseField>
    <ResponseField name="call.legKind" type="string">`primary`, `bridge`, or `monitor`. Calls placed here are `primary`.</ResponseField>
    <ResponseField name="call.from" type="string">The calling number.</ResponseField>
    <ResponseField name="call.to" type="string">The destination number.</ResponseField>
    <ResponseField name="call.connectTo" type="string | null">The resolved bridge target, if any.</ResponseField>
    <ResponseField name="call.queueId" type="string | null">The queue this call is parked in, if any.</ResponseField>
    <ResponseField name="call.conferenceId" type="string | null">The provider conference id once a bridge or monitor leg is attached.</ResponseField>
    <ResponseField name="call.parentCallId" type="string | null">For a bridge/monitor leg, the primary call it belongs to.</ResponseField>
    <ResponseField name="call.bridgedCallId" type="string | null">For a primary call, the currently bridged agent leg.</ResponseField>
    <ResponseField name="call.monitorRole" type="string | null">`MONITOR` or `ADVISOR` for a monitor leg.</ResponseField>
    <ResponseField name="call.record" type="boolean">Whether recording was requested.</ResponseField>
    <ResponseField name="call.recordingState" type="string | null">`requested`, `started`, `stopped`, `ready`, `failed`, or `deleted`.</ResponseField>
    <ResponseField name="call.recordingFileIds" type="array">Provider file ids for completed recordings.</ResponseField>
    <ResponseField name="call.customData" type="object">The metadata you supplied.</ResponseField>
    <ResponseField name="call.error" type="string | null">A machine-readable reason when the call failed.</ResponseField>
    <ResponseField name="call.startedAt" type="string | null">ISO 8601 timestamp when the call was placed.</ResponseField>
    <ResponseField name="call.answeredAt" type="string | null">ISO 8601 timestamp when the call was answered.</ResponseField>
    <ResponseField name="call.endedAt" type="string | null">ISO 8601 timestamp when the call ended.</ResponseField>
    <ResponseField name="call.createdAt" type="string | null">ISO 8601 timestamp when the record was created.</ResponseField>
  </Expandable>
</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.tracklysms.com/api/v1/voice/calls \
    -H "X-Api-Key: trk_your_api_key_here" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: 8f2c1a9e-4b7d-4c3a-9e21-3f0a1b2c3d4e" \
    -d '{
      "to": "+14155551234",
      "from": "+18005551234",
      "connectTo": "+14155559876",
      "record": true,
      "customData": { "caseId": "abc-123" }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "call": {
      "id": "665f1e2a9c4b1a0012ab34cd",
      "direction": "outbound",
      "state": "calling",
      "legKind": "primary",
      "from": "+18005551234",
      "to": "+14155551234",
      "connectTo": "+14155559876",
      "queueId": null,
      "conferenceId": null,
      "parentCallId": null,
      "bridgedCallId": null,
      "monitorRole": null,
      "record": true,
      "recordingState": "requested",
      "recordingFileIds": [],
      "customData": { "caseId": "abc-123" },
      "error": null,
      "startedAt": "2026-08-21T18:00:00.000000Z",
      "answeredAt": null,
      "endedAt": null,
      "createdAt": "2026-08-21T18:00:00.000000Z"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Status | Code                                                                                           | Meaning                                                 |
| ------ | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| 403    | `voice_not_entitled`                                                                           | Voice calling is not enabled for your account.          |
| 403    | `compliance_dnc` / `compliance_opted_out` / `compliance_suppressed` / `compliance_quiet_hours` | The destination is blocked by a compliance rule.        |
| 422    | `from_not_owned`                                                                               | `from` is not a number assigned to your account.        |
| 422    | `missing_fields`                                                                               | A required field (`to` or `from`) is missing.           |
| 422    | `invalid_number`                                                                               | `to` or `connectTo` is not a valid E.164 number.        |
| 404    | `agent_not_found`                                                                              | `connectTo` is an agent id that does not exist.         |
| 429    | `concurrency_limit`                                                                            | Your account has too many concurrent calls in progress. |
| 502    | `provider_error`                                                                               | The upstream telephony provider rejected the request.   |