---
title: "Start an outbound agent call"
method: POST
path: "/v1/telephony/calls"
tags: ["Telephony"]
---

# Start an outbound agent call

`POST /v1/telephony/calls`

## Request

- Base URL: `https://api.pyai.com`
- URL: `https://api.pyai.com/v1/telephony/calls`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Start an outbound call from one of your active managed numbers into an Omni agent. A valid Idempotency-Key is mandatory. PyAI never retries an ambiguous dispatch and never changes routes after answer; only a confirmed retryable pre-answer result may advance an approved route plan. Limited availability: returns 404 until outbound telephony is enabled for the deployment. Requires `telephony:manage`.

## Headers

- `Idempotency-Key` string, required

## Request body

- TelephonyCallCreateRequest
  - `from_number_id` string, required: Active managed-number ID to present as caller ID.
  - `to` string, required: Supported E.164 destination.
  - `agent_id` string, required: Omni agent that handles the connected call.
  - `use_case` 'transactional' | 'support' | 'sales' | 'collections' | 'survey', required: Declared calling purpose. Determines consent, identity, CNAM, and policy gates.
  - `routing_profile` 'quality_first' | 'balanced' | 'cost_optimized'

## Response `201`

Call accepted

- TelephonyCall
  - `object` string
  - `id` string
  - `from_number_id` string
  - `to` string
  - `agent_id` string
  - `use_case` 'transactional' | 'support' | 'sales' | 'collections' | 'survey'
  - `routing_profile` 'quality_first' | 'balanced' | 'cost_optimized'
  - `status` 'queued' | 'dispatching' | 'ringing' | 'in_progress' | 'completed' | 'failed' | 'canceled' | 'dispatch_unknown'
  - `attempt_count` integer
  - `max_attempts` integer
  - `failure_reason` 'network_unavailable' | 'congestion' | 'timeout' | 'no_answer' | 'busy' | 'rejected' | 'invalid_number' | 'identity_blocked' | 'compliance_blocked' | 'unknown' | 'null', nullable
  - `created_at` integer: Unix ms.
  - `updated_at` integer: Unix ms.
  - `answered_at` integer, nullable: Unix ms.
  - `ended_at` integer, nullable: Unix ms.
  - `artifacts` object: Post-call artifact and billing readiness. Included on the single-call detail response; pending until the media edge finalizes the call.
    - `status` 'pending' | 'ready' | 'unavailable'
    - `omni_call_id` string
    - `recording` object
      - `status` string
      - `reason` string, nullable
      - `resource` string, nullable
    - `transcript` object
      - `status` string
      - `resource` string, nullable
    - `usage` object
      - `status` 'pending' | 'recorded'
      - `meter` string
      - `units` number
      - `billable` boolean

## Other responses

- `400`: Invalid request (bad field, unsupported value)
- `401`: Missing or invalid API key (`code: unauthorized`)
- `404`: Source number/agent not found, or outbound telephony is not enabled.
- `409`: Idempotency conflict or source number is not voice-capable.

---

[API](https://skmtc.dev/pyai/apis/pyai-api.md) · [All operations](https://skmtc.dev/pyai/apis/pyai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pyai/apis/pyai-api/revisions/271a1539185b?raw)