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

# Create Phone Call

> Initiate an outbound phone call with an AI agent

## Overview

Creates a new outbound phone call. The AI agent will call the specified phone number and handle the conversation based on its configuration.

<Note>
  Calls are billed based on duration. See [Pricing](/pricing) for details.
</Note>

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication.

  Example: `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

### Body Parameters

<ParamField body="to" type="string" required>
  The phone number to call in E.164 format.

  **Example:** `+14155551234`

  **Constraints:**

  * Must start with `+` followed by country code
  * 10-15 digits total
  * Must be a valid, dialable phone number
</ParamField>

<ParamField body="from" type="string" required>
  Your Magpipe phone number to use as caller ID. Must be a number provisioned in your account.

  **Example:** `+16045551234`
</ParamField>

<ParamField body="agent_id" type="string" required>
  UUID of the AI agent to handle the call.

  **Example:** `c72ea2b8-1234-5678-9abc-def012345678`
</ParamField>

<ParamField body="metadata" type="object">
  Optional key-value pairs to attach to the call. Available in webhooks and call logs.

  **Example:**

  ```json theme={null}
  {
    "customer_id": "cust_123",
    "campaign": "follow_up"
  }
  ```
</ParamField>

<ParamField body="webhook_url" type="string">
  URL to receive call status webhooks. Overrides account-level webhook settings.

  **Example:** `https://yourapp.com/webhooks/calls`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the call was successfully initiated.
</ResponseField>

<ResponseField name="call_id" type="string">
  Unique identifier for the call. Use this to track call status.
</ResponseField>

<ResponseField name="status" type="string">
  Initial call status. One of:

  * `initiated` - Call is being placed
  * `queued` - Call is queued for dialing
</ResponseField>

<ResponseField name="from_number" type="string">
  The caller ID number used.
</ResponseField>

<ResponseField name="to_number" type="string">
  The destination phone number.
</ResponseField>

<ResponseField name="agent_id" type="string">
  The agent handling the call.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the call was created.
</ResponseField>

## Example Request

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.magpipe.ai/functions/v1/initiate-bridged-call" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+14155551234",
      "from": "+16045551234",
      "agent_id": "c72ea2b8-1234-5678-9abc-def012345678"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.magpipe.ai/functions/v1/initiate-bridged-call',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        to: '+14155551234',
        from: '+16045551234',
        agent_id: 'c72ea2b8-1234-5678-9abc-def012345678',
      }),
    }
  );

  const data = await response.json();
  console.log(data.call_id);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.magpipe.ai/functions/v1/initiate-bridged-call',
      headers={
          'Authorization': f'Bearer {api_key}',
          'Content-Type': 'application/json',
      },
      json={
          'to': '+14155551234',
          'from': '+16045551234',
          'agent_id': 'c72ea2b8-1234-5678-9abc-def012345678',
      }
  )

  data = response.json()
  print(data['call_id'])
  ```
</RequestExample>

## Example Response

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "success": true,
    "call_id": "a1b2c3d4-5678-9012-3456-789012345678",
    "status": "initiated",
    "from_number": "+16045551234",
    "to_number": "+14155551234",
    "agent_id": "c72ea2b8-1234-5678-9abc-def012345678",
    "created_at": "2024-01-15T10:30:00.000Z"
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 400 Bad Request theme={null}
  {
    "error": {
      "code": "INVALID_PHONE_NUMBER",
      "message": "The 'to' field must be a valid E.164 phone number"
    }
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 401 Unauthorized theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Invalid or expired access token"
    }
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 402 Payment Required theme={null}
  {
    "error": {
      "code": "INSUFFICIENT_BALANCE",
      "message": "Insufficient account balance to place call"
    }
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 404 Not Found theme={null}
  {
    "error": {
      "code": "AGENT_NOT_FOUND",
      "message": "Agent with specified ID not found"
    }
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 422 Unprocessable Entity theme={null}
  {
    "error": {
      "code": "NUMBER_NOT_OWNED",
      "message": "The 'from' number is not provisioned in your account"
    }
  }
  ```
</ResponseExample>

## Call Status Webhook

When the call status changes, a webhook is sent to your configured URL:

```json theme={null}
{
  "event": "call.status_changed",
  "call_id": "a1b2c3d4-5678-9012-3456-789012345678",
  "status": "completed",
  "duration": 125,
  "recording_url": "https://storage.magpipe.ai/recordings/...",
  "transcript": "Agent: Hello! Caller: Hi there...",
  "metadata": {
    "customer_id": "cust_123"
  },
  "timestamp": "2024-01-15T10:32:05.000Z"
}
```

### Call Status Values

| Status        | Description                         |
| ------------- | ----------------------------------- |
| `initiated`   | Call request received, dialing      |
| `ringing`     | Recipient phone is ringing          |
| `in-progress` | Call is active                      |
| `completed`   | Call ended normally                 |
| `busy`        | Recipient was busy                  |
| `no-answer`   | No answer after timeout             |
| `failed`      | Call failed to connect              |
| `canceled`    | Call was canceled before connecting |