> ## 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.

# Trigger an outbound call

> 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.



## OpenAPI

````yaml POST /v1/agents/{agentId}/telephony/outbound-calls
openapi: 3.1.0
info:
  title: PolyAI Agents API
  version: 1.0.11
  description: Manage PolyAI agents, telephony, deployments, and real-time configs.
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
  - url: https://api.studio.poly.ai
    description: Studio region
security:
  - polyApiKey: []
paths:
  /v1/agents/{agentId}/telephony/outbound-calls:
    parameters:
      - name: agentId
        in: path
        required: true
        schema:
          type: string
    post:
      tags:
        - Outbound Calls
      summary: Trigger an outbound call
      description: >-
        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.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateOutboundCallBody'
      responses:
        '200':
          description: Call accepted and queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboundCallResponse'
        '400':
          description: >-
            Invalid request — malformed phone number, invalid environment,
            metadata too large, or outbound calling not configured for this
            environment.
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — insufficient permissions.
        '404':
          description: No connector found for the specified environment.
        '502':
          description: >-
            Outbound calling service unavailable. Retry with exponential
            backoff.
components:
  schemas:
    InitiateOutboundCallBody:
      type: object
      required:
        - toNumber
        - environment
      properties:
        toNumber:
          type: string
          description: >-
            Phone number to dial in E.164 format (e.g. +442012345678). If the
            number lacks a country prefix, also supply countryCode.
          example: '+442012345678'
        environment:
          type: string
          description: Target environment for the call.
          enum:
            - sandbox
            - pre-release
            - live
          example: live
        countryCode:
          type: string
          description: >-
            ISO 3166-1 alpha-2 country code (e.g. GB) for parsing a non-E.164
            toNumber.
          example: GB
        variantId:
          type: string
          description: >-
            Variant ID to use for the call. If omitted, the default connector
            for the environment is used.
        encryption:
          type: string
          description: Telephony encryption mode for the outbound leg.
          default: tls_srtp
          example: tls_srtp
        metadata:
          type: object
          description: >-
            Arbitrary key/value pairs delivered to the agent as SIP headers. All
            values must be strings. The base64 representation must be under 26
            KB.
          additionalProperties:
            type: string
          example:
            customer_name: Paul Smith
            appointment_date: '2026-08-26'
    OutboundCallResponse:
      type: object
      properties:
        callSid:
          type: string
          description: >-
            Unique call identifier (prefixed with OUT-). Use this to poll
            status.
          example: OUT-550e8400-e29b-41d4-a716-446655440000
        status:
          type: string
          description: Initial call status.
          example: QUEUED
  securitySchemes:
    polyApiKey:
      type: apiKey
      in: header
      name: X-API-KEY

````