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

> Initiate an outbound call using an AI phone agent. Use when orchestrating voice calls programmatically — placing outbound calls or listing call history.

# Make an AI phone call



## OpenAPI

````yaml post /phone/outbound-call
openapi: 3.1.0
info:
  title: OpenCX API
  description: >

    OpenCX is an AI-powered, all-in-one platform for customer support and
    outbound communications.


    Use this API to manage your OpenCX organization's AI agents, actions,
    conversations, contacts, and more.


    To get started, generate a new API key from the dashboard.


    ## Authentication

    All API endpoints require authentication using a Bearer token. You can
    generate an API key from your OpenCX dashboard.


    ## Rate Limiting

    API requests are rate limited to ensure fair usage. The current limits are:

    - 100 requests per minute for standard endpoints

    - 1000 requests per minute for streaming endpoints


    ## Error Handling

    The API uses standard HTTP status codes and returns detailed error messages
    in the response body.
  version: 1.0-beta
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: http://localhost:8080
    description: Development
  - url: https://api.open.cx
    description: Production
security:
  - bearerAuth: []
paths:
  /phone/outbound-call:
    post:
      summary: Make an AI phone call
      description: >-
        Initiate an outbound call using an AI phone agent. You can target either
        an existing contact by ID or a raw phone number in E.164 format.
      operationId: makeOutboundCall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MakeOutboundCallDto'
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MakeOutboundCallResponseDto'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
components:
  schemas:
    MakeOutboundCallDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/MakeOutboundCallDtoInput'
      type: object
      properties:
        phoneAgentId:
          type: string
        contact:
          anyOf:
            - type: object
              properties:
                id:
                  type: string
              required:
                - id
            - type: object
              properties:
                phoneNumber:
                  type: string
              required:
                - phoneNumber
        sessionCustomData:
          description: >-
            Custom attributes saved on the call session before the call starts,
            so workflows and webhooks that fire at call start already see them.
            Also surfaced to the AI agent as session context. Equivalent to the
            X-OPENCX-SESSION-CUSTOM-DATA header on inbound calls.
          type: object
          propertyNames:
            type: string
          additionalProperties:
            anyOf:
              - type: string
              - type: number
              - type: boolean
        extraInstructions:
          description: >-
            Extra instructions for the AI agent, scoped to this call only.
            Appended to the agent instructions in a clearly-scoped block — they
            complement, never replace, the agent prompt.
          type: string
          maxLength: 10000
      required:
        - phoneAgentId
        - contact
    MakeOutboundCallResponseDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/MakeOutboundCallResponseDto'
      type: object
      properties:
        error:
          description: Error details if the call failed
          type: object
          properties:
            code:
              type: string
            status:
              type: number
          additionalProperties: false
        result:
          description: Raw call result from the provider
        sessionId:
          description: >-
            ID of the session created for this call, available at dial time. Use
            it to correlate call webhooks (phone_call.started / phone_call.ended
            carry the same session_id) and to fetch the session — including its
            custom data — after the call.
          type: string
        callId:
          description: Provider call ID
          type: string
      additionalProperties: false
    ErrorDto:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````