---
title: "Trigger an outbound call"
method: POST
path: "/v1/agents/{agentId}/telephony/outbound-calls"
tags: ["Outbound Calls"]
---

# Trigger an outbound call

`POST /v1/agents/{agentId}/telephony/outbound-calls`

Triggers the PolyAI voice agent to dial a phone number. The agent will call the provided number and conduct the conversation autonomously. Returns a callSid that can be used to poll status.

## Request body

- InitiateOutboundCallBody
  - `toNumber` string, required — Phone number to dial in E.164 format (e.g. +442012345678). If the number lacks a country prefix, also supply countryCode.
  - `environment` 'sandbox' | 'pre-release' | 'live', required — Target environment for the call.
  - `countryCode` string — ISO 3166-1 alpha-2 country code (e.g. GB) for parsing a non-E.164 toNumber.
  - `variantId` string — Variant ID to use for the call. If omitted, the default connector for the environment is used.
  - `encryption` string — Telephony encryption mode for the outbound leg.
  - `metadata` object — Arbitrary key/value pairs delivered to the agent as SIP headers. All values must be strings. The base64 representation must be under 26 KB.

## Response `200`

Call accepted and queued.

- OutboundCallResponse
  - `callSid` string — Unique call identifier (prefixed with OUT-). Use this to poll status.
  - `status` string — Initial call status.

## Other responses

- `400` — Invalid request — malformed phone number, invalid environment, metadata too large, or outbound calling not configured for this environment.
- `401` — Unauthorized — missing or invalid API key.
- `403` — Forbidden — insufficient permissions.
- `404` — No connector found for the specified environment.
- `502` — Outbound calling service unavailable. Retry with exponential backoff.

---

[API](https://skmtc.net/poly/apis/polyai-agents-api.md) · [All operations](https://skmtc.net/poly/apis/polyai-agents-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/poly/polyai-agents-api/revisions/76f3c606e395/schema)