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

# Call a Contact

> Initiate an outbound AI phone call to an existing contact

Initiates an outbound AI phone call to an existing contact in your system. The contact's phone number, name, and profile data are automatically retrieved — you only need to provide the contact ID, agent ID, and the phone number to call from.

For calling any phone number without a pre-existing contact record, see [Make AI Phone Call](/api-reference/endpoint/make-ai-phone-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="contact_id" type="string" required>
  UUID of the existing contact to call. The contact's phone number and profile data are fetched automatically. Use [Get Contacts](/api-reference/endpoint/get-contacts) to look up contact IDs.
</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="from_number_id" type="string" required>
  UUID of the phone number in your organization to call from. Use [List Phone Numbers](/api-reference/endpoint/get-phone-numbers) to get available number IDs.
</ParamField>

<ParamField body="additional_data" type="array">
  Key-value pairs with extra context passed to the agent for this call (e.g. account balance, product name). Supplements the contact's existing profile data.

  <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="delay" type="number">
  Delay in minutes before placing the call. 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="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 being called.
</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
* `404 Not Found` — Contact or phone number not found
* `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-contact-call" \
    -H "x-api-key: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "contact_id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "agent_id": "agent-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "from_number_id": "pn-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "additional_data": [
        { "key": "amount_debt", "value": "14058" }
      ]
    }'
  ```

  ```bash cURL — Scheduled call theme={null}
  curl -X POST "https://api.contactship.ai/v1/calls/single-contact-call" \
    -H "x-api-key: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "contact_id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "agent_id": "agent-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "from_number_id": "pn-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "schedule": {
        "scheduled_call_time": "2026-06-15 10:00:00",
        "timezone": "America/Mexico_City"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.contactship.ai/v1/calls/single-contact-call',
    {
      method: 'POST',
      headers: {
        'x-api-key': 'your-api-key',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        contact_id: 'c1d2e3f4-a5b6-7890-cdef-123456789012',
        agent_id: 'agent-a1b2c3d4-e5f6-7890-abcd-ef1234567890',
        from_number_id: 'pn-a1b2c3d4-e5f6-7890-abcd-ef1234567890',
        additional_data: [
          { key: 'amount_debt', value: '14058' },
        ],
      }),
    }
  );
  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-contact-call',
      headers={'x-api-key': 'your-api-key'},
      json={
          'contact_id': 'c1d2e3f4-a5b6-7890-cdef-123456789012',
          'agent_id': 'agent-a1b2c3d4-e5f6-7890-abcd-ef1234567890',
          'from_number_id': 'pn-a1b2c3d4-e5f6-7890-abcd-ef1234567890',
          'additional_data': [
              {'key': 'amount_debt', 'value': '14058'},
          ],
      },
  )
  call = response.json()
  print(f"Call created: {call['call_id']}")
  ```
</RequestExample>

<ResponseExample>
  ```json Example Response theme={null}
  {
    "call_id": "call-b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "agent_id": "agent-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "contact_id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
    "created_at": "2026-04-06T15:05:00Z"
  }
  ```
</ResponseExample>