Call a Contact

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

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

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

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

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

POST

calls

single-contact-call

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

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

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

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

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

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

Headers

string

requerido

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

Body

string

requerido

UUID of the existing contact to call. The contact’s phone number and profile data are fetched automatically. Use Get Contacts to look up contact IDs.

string

requerido

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

string

requerido

UUID of the phone number in your organization to call from. Use List Phone Numbers to get available number IDs.

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.

Mostrar Additional data item

string

requerido

The key name (e.g. amount_debt).

string

requerido

The value (e.g. 14058).

number

Delay in minutes before placing the call. 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).

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 being called.

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
404 Not Found — Contact or phone number not found
500 Internal Server Error — Server-side error

Code Examples

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

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

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

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

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

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