> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Place an outbound call
Place an outbound call that routes over a SIP Trunk. PolyAI dials `to_number` and connects the answered call to the specified agent.
Use this endpoint to place calls over your own connected SIP Trunk. To place calls over PolyAI-managed telephony instead, use the Agents API [Trigger an outbound call](/api-reference/agents/endpoint/outbound-calls/trigger-outbound-call) endpoint.
Set the trunk's `outbound.default_caller_id` and the SIP addresses your calls route to with [Update a SIP Trunk](/api-reference/sip-trunking/endpoint/update-a-sip-trunk). See [Connecting to PolyAI Telephony](/api-reference/sip-trunking/connecting) for the outbound transport details.
## Destination number
Provide `to_number` in one of two ways:
| Form | Example | Notes |
| -------- | ------------------------------------------------ | ------------------------------------------------------------------------------- |
| E.164 | `to_number: "+447700900123"` | Recommended. No `country_code` needed. |
| National | `to_number: "07700900123"`, `country_code: "GB"` | `country_code` is an ISO 3166-1 alpha-2 code used to parse the national number. |
`country_code` is **optional**. Only supply it when `to_number` is a national number that needs a region to be parsed — for a full E.164 number, leave it out.
The `caller_id` you present must be in E.164. If you omit it, the trunk's default caller ID is used.
The response returns a `call_sid` (prefixed with `OUT-`). Use it with [Get outbound call status](/api-reference/sip-trunking/endpoint/get-outbound-call-status) to monitor the call.
## OpenAPI
````yaml POST /v1/telephony/sip-trunks/{trunkId}/outbound-call
openapi: 3.0.3
info:
title: PolyAI SIP Trunking API
version: 1.0.0
description: Management API for PolyAI SIP Trunks and their Extensions.
servers:
- url: https://api.us.poly.ai
description: US region
- url: https://api.eu.poly.ai
description: EU region
- url: https://api.uk.poly.ai
description: UK region
security:
- polyApiKey: []
tags:
- name: SIP Trunks
description: >-
A SIP Trunk is a virtual connection between your telephony platform and
PolyAI. It authenticates callers, accepts inbound calls, and holds the
list of Extensions that map a dialed number to a PolyAI agent.
- name: SIP Trunk Extensions
description: >-
An Extension binds a dialed number on a trunk to a PolyAI agent. When a
call reaches a trunk, the dialed user part is matched against that trunk's
extensions to pick the agent.
- name: Outbound Calls
description: Place and query outbound calls that route over a SIP Trunk.
paths:
/v1/telephony/sip-trunks/{trunkId}/outbound-call:
parameters:
- $ref: '#/components/parameters/trunkId'
post:
tags:
- Outbound Calls
summary: Place an outbound call
operationId: placeOutboundCall
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OutboundCallRequest'
responses:
'200':
description: The call was accepted and queued.
content:
application/json:
schema:
$ref: '#/components/schemas/OutboundCallResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
components:
parameters:
trunkId:
name: trunkId
in: path
required: true
description: The SIP Trunk's friendly ID (e.g. tr-...).
schema:
type: string
schemas:
OutboundCallRequest:
type: object
description: The details of the outbound call to place.
properties:
agent:
$ref: '#/components/schemas/OutboundCallAgent'
to_number:
type: string
description: >-
The destination phone number in E.164, or a national number when
country_code is supplied.
example: '+447700900123'
caller_id:
type: string
description: >-
Optional caller ID to present on the call, in E.164 (e.g.
+447700900123). If omitted, the trunk's default caller ID is used.
example: '+447700900000'
country_code:
type: string
description: ISO 3166-1 alpha-2 country code used to parse a national to_number.
example: GB
metadata:
type: object
additionalProperties:
type: string
description: >-
Optional metadata attached to the call. The encoded payload is
capped at roughly 26 KB.
example:
campaign_id: spring-sale
customer_ref: cust-42
required:
- agent
- to_number
OutboundCallResponse:
type: object
description: The result of placing an outbound call.
properties:
call_sid:
type: string
description: >-
Identifier for the placed call; use it to query the call status.
Prefixed with OUT-.
example: OUT-3f2a7c9e-1b4d-4e6a-9c8b-2d5f7a1e0c34
required:
- call_sid
OutboundCallAgent:
type: object
description: The PolyAI agent that handles the outbound call.
properties:
agent_id:
type: string
description: The Agent Studio project (agent) ID.
example: abc123
client_env:
type: string
description: The client environment the agent runs in.
enum:
- sandbox
- pre-release
- live
example: live
variant_id:
type: string
description: Optional agent variant ID.
example: default
required:
- agent_id
- client_env
Error:
type: object
description: Error response body.
properties:
success:
type: boolean
error:
type: string
message:
type: string
required:
- success
- error
- message
responses:
BadRequest:
description: Validation error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Missing or invalid credential.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Caller is not a telephony admin on the account.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
polyApiKey:
type: apiKey
in: header
name: X-API-Key
````