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": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
"from_number_id": "b1b2c3d4-e5f6-4890-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": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
"from_number_id": "b1b2c3d4-e5f6-4890-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: 'a1b2c3d4-e5f6-4890-abcd-ef1234567890',
from_number_id: 'b1b2c3d4-e5f6-4890-abcd-ef1234567890',
additional_data: [
{ key: 'amount_debt', value: '14058' },
],
}),
}
);
const { data: 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': 'a1b2c3d4-e5f6-4890-abcd-ef1234567890',
'from_number_id': 'b1b2c3d4-e5f6-4890-abcd-ef1234567890',
'additional_data': [
{'key': 'amount_debt', 'value': '14058'},
],
},
)
call = response.json()["data"]
print(f"Call created: {call['call_id']}")
{
"statusCode": 201,
"data": {
"call_id": "call-b2c3d4e5-f6a7-8901-bcde-f12345678901",
"agent_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
"contact_id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
"created_at": "2026-04-06T15:05:00Z"
}
}
Voz
Call a Contact
Initiate an outbound AI phone call to an existing contact
POST
/
v1
/
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": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
"from_number_id": "b1b2c3d4-e5f6-4890-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": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
"from_number_id": "b1b2c3d4-e5f6-4890-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: 'a1b2c3d4-e5f6-4890-abcd-ef1234567890',
from_number_id: 'b1b2c3d4-e5f6-4890-abcd-ef1234567890',
additional_data: [
{ key: 'amount_debt', value: '14058' },
],
}),
}
);
const { data: 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': 'a1b2c3d4-e5f6-4890-abcd-ef1234567890',
'from_number_id': 'b1b2c3d4-e5f6-4890-abcd-ef1234567890',
'additional_data': [
{'key': 'amount_debt', 'value': '14058'},
],
},
)
call = response.json()["data"]
print(f"Call created: {call['call_id']}")
{
"statusCode": 201,
"data": {
"call_id": "call-b2c3d4e5-f6a7-8901-bcde-f12345678901",
"agent_id": "a1b2c3d4-e5f6-4890-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
Use
schedule to choose a future calling time. The contact-call route currently does not apply delay to the call request.object
object
Arbitrary key-value metadata to attach to the call for your own tracking purposes.
Response
The response is{ "statusCode": number, "data": object }. The fields below describe data.
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 fields401 Unauthorized— Invalid or missing API key404 Not Found— Contact or phone number not found500 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": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
"from_number_id": "b1b2c3d4-e5f6-4890-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": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
"from_number_id": "b1b2c3d4-e5f6-4890-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: 'a1b2c3d4-e5f6-4890-abcd-ef1234567890',
from_number_id: 'b1b2c3d4-e5f6-4890-abcd-ef1234567890',
additional_data: [
{ key: 'amount_debt', value: '14058' },
],
}),
}
);
const { data: 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': 'a1b2c3d4-e5f6-4890-abcd-ef1234567890',
'from_number_id': 'b1b2c3d4-e5f6-4890-abcd-ef1234567890',
'additional_data': [
{'key': 'amount_debt', 'value': '14058'},
],
},
)
call = response.json()["data"]
print(f"Call created: {call['call_id']}")
{
"statusCode": 201,
"data": {
"call_id": "call-b2c3d4e5-f6a7-8901-bcde-f12345678901",
"agent_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
"contact_id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
"created_at": "2026-04-06T15:05:00Z"
}
}