Make AI Phone Call

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" }
    ]
  }'

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"
    }
  }'

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}`);

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']}")

{
  "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"
}

POST

calls

single-phone-call

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" }
    ]
  }'

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"
    }
  }'

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}`);

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']}")

{
  "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"
}

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

Headers

string

requerido

Your API key for authentication. Found in your dashboard under API settings.

Body

string

requerido

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 to get available numbers.

string

requerido

The destination phone number to call, in E.164 format (e.g. +14155552678).

string

requerido

Full name of the person being called. The AI agent uses this to personalize the conversation.

string

requerido

UUID of the AI agent to use for the call. Use List Agents to get available agents.

string

Email address of the contact. Passed to the agent for context.

string

Country of the contact (e.g. Mexico, United States). Passed to the agent for context.

number

Delay in minutes before placing the call. Useful for scheduling calls slightly in the future. Defaults to 0 (immediate).

object

Schedule the call for a specific date and time.

Mostrar Schedule object

string

requerido

Date and time of the call in yyyy-MM-dd HH:mm:ss format (e.g. 2026-06-15 14:30:00).

string

requerido

Timezone for the scheduled time (IANA format, e.g. America/New_York, America/Mexico_City).

array

Key-value pairs with extra context passed to the agent (e.g. account balance, product name).

Mostrar Additional data item

string

requerido

The key name (e.g. amount_debt).

string

requerido

The value (e.g. 14058).

string

URL to receive call event webhooks (call started, ended, transcript ready, etc.) for this specific call.

object

Arbitrary key-value metadata to attach to the call for your own tracking purposes.

Response

string

Unique identifier for the created call.

string

UUID of the AI agent handling the call.

string

UUID of the contact associated with the call, if applicable.

string

Timestamp when the call was created (ISO 8601).

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

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" }
    ]
  }'

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"
    }
  }'

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}`);

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']}")

{
  "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"
}

Introduction Call a Contact

Documentación API

Voz

WhatsApp (WABA)

Canales y Conversaciones

Organización

Agentes

Contactos

Etiquetas

Llamadas

Números de Teléfono

Headers

Body

Response

Error Codes

Code Examples

​Headers

​Body

​Response

​Error Codes

​Code Examples

Headers

Body

Response

Error Codes

Code Examples