Saltar al contenido principal
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": "agent-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "from_number_id": "pn-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "additional_data": [
      { "key": "amount_debt", "value": "14058" }
    ]
  }'

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

​
x-api-key
string
requerido
Your API key for authentication. Found in your dashboard under API settings.

​
Body

​
contact_id
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.
​
agent_id
string
requerido
UUID of the AI agent to use for the call. Use List Agents to get available agents.
​
from_number_id
string
requerido
UUID of the phone number in your organization to call from. Use List Phone Numbers to get available number IDs.
​
additional_data
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.
​
delay
number
Delay in minutes before placing the call. Defaults to 0 (immediate).
​
schedule
object
Schedule the call for a specific date and time.
​
metadata
object
Arbitrary key-value metadata to attach to the call for your own tracking purposes.

​
Response

​
call_id
string
Unique identifier for the created call.
​
agent_id
string
UUID of the AI agent handling the call.
​
contact_id
string
UUID of the contact being called.
​
created_at
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" }
    ]
  }'

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