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

# Make AI Phone Call

> Initiate an outbound AI phone call using raw phone numbers

Initiates an outbound AI phone call by providing the destination phone number and contact details directly. Use this endpoint when you want to call any phone number without first creating a contact record.

For calling an existing contact in your system, see [Call a Contact](/api-reference/endpoint/make-contact-call) instead.

## Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication. Found in your dashboard under API settings.
</ParamField>

## Body

<ParamField body="from_number" type="string" required>
  The phone number to call from, in E.164 format (e.g. `+12025551234`). Must be a number registered in your organization. Use [List Phone Numbers](/api-reference/endpoint/get-phone-numbers) to get available numbers.
</ParamField>

<ParamField body="to_number" type="string" required>
  The destination phone number to call, in E.164 format (e.g. `+14155552678`).
</ParamField>

<ParamField body="full_name" type="string" required>
  Full name of the person being called. The AI agent uses this to personalize the conversation.
</ParamField>

<ParamField body="agent_id" type="string" required>
  UUID of the AI agent to use for the call. Use [List Agents](/api-reference/endpoint/list-agents) to get available agents.
</ParamField>

<ParamField body="email" type="string">
  Email address of the contact. Passed to the agent for context.
</ParamField>

<ParamField body="country" type="string">
  Country of the contact (e.g. `Mexico`, `United States`). Passed to the agent for context.
</ParamField>

<ParamField body="delay" type="number">
  Delay in minutes before placing the call. Useful for scheduling calls slightly in the future. Defaults to `0` (immediate).
</ParamField>

<ParamField body="schedule" type="object">
  Schedule the call for a specific date and time.

  <Expandable title="Schedule object">
    <ParamField body="scheduled_call_time" type="string" required>
      Date and time of the call in `yyyy-MM-dd HH:mm:ss` format (e.g. `2026-06-15 14:30:00`).
    </ParamField>

    <ParamField body="timezone" type="string" required>
      Timezone for the scheduled time (IANA format, e.g. `America/New_York`, `America/Mexico_City`).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="additional_data" type="array">
  Key-value pairs with extra context passed to the agent (e.g. account balance, product name).

  <Expandable title="Additional data item">
    <ParamField body="key" type="string" required>
      The key name (e.g. `amount_debt`).
    </ParamField>

    <ParamField body="value" type="string" required>
      The value (e.g. `14058`).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="webhook_url" type="string">
  URL to receive call event webhooks (call started, ended, transcript ready, etc.) for this specific call.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value metadata to attach to the call for your own tracking purposes.
</ParamField>

## Response

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

<ResponseField name="agent_id" type="string">
  UUID of the AI agent handling the call.
</ResponseField>

<ResponseField name="contact_id" type="string">
  UUID of the contact associated with the call, if applicable.
</ResponseField>

<ResponseField name="created_at" type="string">
  Timestamp when the call was created (ISO 8601).
</ResponseField>

## Error Codes

* `400 Bad Request` — Invalid or missing required fields
* `401 Unauthorized` — Invalid or missing API key
* `500 Internal Server Error` — Server-side error

## Code Examples

<RequestExample>
  ```bash cURL — Immediate call theme={null}
  curl -X POST "https://api.contactship.ai/v1/calls/single-phone-call" \
    -H "x-api-key: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "from_number": "+12025551234",
      "to_number": "+14155552678",
      "full_name": "Jane Smith",
      "agent_id": "agent-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "jane.smith@example.com",
      "country": "United States",
      "additional_data": [
        { "key": "plan", "value": "premium" },
        { "key": "account_balance", "value": "250.00" }
      ]
    }'
  ```

  ```bash cURL — Scheduled call theme={null}
  curl -X POST "https://api.contactship.ai/v1/calls/single-phone-call" \
    -H "x-api-key: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "from_number": "+12025551234",
      "to_number": "+14155552678",
      "full_name": "Jane Smith",
      "agent_id": "agent-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "schedule": {
        "scheduled_call_time": "2026-06-15 14:30:00",
        "timezone": "America/New_York"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.contactship.ai/v1/calls/single-phone-call',
    {
      method: 'POST',
      headers: {
        'x-api-key': 'your-api-key',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        from_number: '+12025551234',
        to_number: '+14155552678',
        full_name: 'Jane Smith',
        agent_id: 'agent-a1b2c3d4-e5f6-7890-abcd-ef1234567890',
        email: 'jane.smith@example.com',
        country: 'United States',
        additional_data: [
          { key: 'plan', value: 'premium' },
        ],
      }),
    }
  );
  const call = await response.json();
  console.log(`Call created: ${call.call_id}`);
  ```

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

  response = requests.post(
      'https://api.contactship.ai/v1/calls/single-phone-call',
      headers={'x-api-key': 'your-api-key'},
      json={
          'from_number': '+12025551234',
          'to_number': '+14155552678',
          'full_name': 'Jane Smith',
          'agent_id': 'agent-a1b2c3d4-e5f6-7890-abcd-ef1234567890',
          'email': 'jane.smith@example.com',
          'country': 'United States',
          'additional_data': [
              {'key': 'plan', 'value': 'premium'},
          ],
      },
  )
  call = response.json()
  print(f"Call created: {call['call_id']}")
  ```
</RequestExample>

<ResponseExample>
  ```json Example Response theme={null}
  {
    "call_id": "call-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "agent_id": "agent-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "contact_id": null,
    "created_at": "2026-04-06T15:00:00Z"
  }
  ```
</ResponseExample>