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

# Make Outbound Call

> Initiate a new outbound phone call using an AI agent. The agent will handle the conversation automatically.

## Overview

Initiate a new outbound phone call using an AI agent. The agent will automatically handle the conversation based on its configuration.

## Request Body

<ParamField body="body" name="to_phone_number" type="string" required>
  Phone number to call in E.164 format (e.g., +1234567890)
</ParamField>

<ParamField body="body" name="agent_id" type="string">
  ID of the AI agent to use for the call. Required if `instruction` is not provided.
</ParamField>

<ParamField body="body" name="instruction" type="string">
  AI agent instruction/prompt. Used to create a temporary agent if `agent_id` is not provided. Required if `agent_id` is not provided.
</ParamField>

<ParamField body="body" name="webhook_url" type="string" optional>
  Optional webhook URL to receive call completion notifications. Must be a valid HTTP/HTTPS URL.
</ParamField>

<ParamField body="body" name="external_call_id" type="string" optional>
  Optional external call ID for tracking purposes.
</ParamField>

<ParamField body="body" name="input_parameters" type="string" optional>
  Optional input parameters as JSON string to pass to the agent.
</ParamField>

<ParamField body="body" name="output_parameters" type="string" optional>
  Optional output parameters template as JSON string to extract structured data from the conversation.
</ParamField>

<ParamField body="body" name="call_id" type="string" optional>
  Existing call ID to retrieve status for. If provided, a new call will not be created.
</ParamField>

## Example Request

<CodeGroup>
  ```bash Basic call theme={null}
  curl -X POST https://api.call24x7.ai/outbound_call \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to_phone_number": "+1234567890",
      "agent_id": "agent-123"
    }'
  ```

  ```bash Call with webhook theme={null}
  curl -X POST https://api.call24x7.ai/outbound_call \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to_phone_number": "+1234567890",
      "agent_id": "agent-123",
      "webhook_url": "https://your-app.com/webhooks/call-complete",
      "external_call_id": "order-12345"
    }'
  ```

  ```bash Call with temporary agent theme={null}
  curl -X POST https://api.call24x7.ai/outbound_call \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to_phone_number": "+1234567890",
      "instruction": "You are a friendly customer service representative calling to confirm an appointment."
    }'
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="call_id" type="string">
  Unique identifier for the call
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the call. Initially `RINGING` when call is initiated.
</ResponseField>

<ResponseField name="message" type="string" optional>
  Response message
</ResponseField>

## Example Response

```json theme={null}
{
  "success": true,
  "call_id": "12345",
  "status": "RINGING",
  "message": "Call initiated successfully"
}
```

## Error Responses

<ResponseField name="success" type="boolean">
  Always `false` for errors
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable error message
</ResponseField>

<ResponseField name="error_code" type="string">
  Error code. Possible values: `MISSING_PARAMS`, `AGENT_NOT_FOUND`, `INSUFFICIENT_BALANCE`, `INTERNAL_ERROR`
</ResponseField>

## Webhooks

If you provide a `webhook_url`, you'll receive a POST request when the call completes with the following data:

```json theme={null}
{
  "call_id": "12345",
  "status": "COMPLETED",
  "call_direction": "outbound",
  "from_phone_number": "+1234567890",
  "to_phone_number": "+0987654321",
  "agent_id": "agent-123",
  "duration_seconds": 180,
  "recording_url": "https://...",
  "transcription": "Full call transcription...",
  "output_parameters": "{\"appointment_scheduled\": true}"
}
```

## Billing

Calls are billed at \$0.15 per minute with precise second-by-second billing. Ensure your account has sufficient balance before making calls.


## OpenAPI

````yaml POST /outbound_call
openapi: 3.0.1
info:
  title: Call24x7.AI API
  description: >-
    API for making AI-powered phone calls. Initiate outbound calls, handle
    inbound calls, and manage your AI agents programmatically.
  version: 1.0.0
  contact:
    name: Call24x7.AI Support
    email: support@call24x7.ai
    url: https://manage.call24x7.ai
servers:
  - url: https://api.call24x7.ai
    description: Production server
security:
  - bearerAuth: []
paths:
  /outbound_call:
    post:
      tags:
        - Calls
      summary: Initiate outbound call
      description: >-
        Initiate a new outbound phone call using an AI agent. The agent will
        handle the conversation automatically.
      operationId: createOutboundCall
      requestBody:
        description: Call request parameters
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutboundCallRequest'
      responses:
        '200':
          description: Call initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallResponse'
        '400':
          description: Bad request - missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Insufficient balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    OutboundCallRequest:
      type: object
      required:
        - to_phone_number
      properties:
        call_id:
          type: string
          description: Existing call ID to retrieve status for
        to_phone_number:
          type: string
          description: Phone number to call (E.164 format, e.g., +1234567890)
          pattern: ^\+[1-9]\d{1,14}$
        agent_id:
          type: string
          description: >-
            ID of the AI agent to use for the call. Required if instruction is
            not provided.
        instruction:
          type: string
          description: >-
            AI agent instruction/prompt. Used to create a temporary agent if
            agent_id is not provided.
        webhook_url:
          type: string
          format: uri
          description: Optional webhook URL to receive call completion notifications
        external_call_id:
          type: string
          description: Optional external call ID for tracking
        input_parameters:
          type: string
          description: Optional input parameters as JSON string
        output_parameters:
          type: string
          description: Optional output parameters template as JSON string
    CallResponse:
      type: object
      required:
        - success
        - call_id
        - status
      properties:
        success:
          type: boolean
          description: Whether the request was successful
        call_id:
          type: string
          description: Unique identifier for the call
        status:
          type: string
          description: Current status of the call
          enum:
            - IDLE
            - RINGING
            - IN_PROGRESS
            - COMPLETED
            - FAILED
        message:
          type: string
          description: Response message
    Error:
      type: object
      required:
        - success
        - message
        - error_code
      properties:
        success:
          type: boolean
          description: Always false for errors
          example: false
        message:
          type: string
          description: Human-readable error message
        error_code:
          type: string
          description: Machine-readable error code
          enum:
            - MISSING_PARAMS
            - UNAUTHORIZED
            - INSUFFICIENT_BALANCE
            - AGENT_NOT_FOUND
            - CALL_NOT_FOUND
            - INTERNAL_ERROR
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        API key authentication. Include your API key in the Authorization header
        as: Bearer YOUR_API_KEY

````