Saltar al contenido principal
POST
/
v1
/
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" }
    ]
  }'

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

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.

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

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

​
Body

​
from_number
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.
​
to_number
string
requerido
The destination phone number to call, in E.164 format (e.g. +14155552678).
​
full_name
string
requerido
Full name of the person being called. The AI agent uses this to personalize the conversation.
​
agent_id
string
requerido
UUID of the AI agent to use for the call. Use List Agents to get available agents.
​
email
string
Email address of the contact. Passed to the agent for context.
​
country
string
Country of the contact (e.g. Mexico, United States). Passed to the agent for context.
​
delay
number
Delay in minutes before placing the call. Useful for scheduling calls slightly in the future. Defaults to 0 (immediate).
​
schedule
object
Schedule the call for a specific date and time.
​
additional_data
array
Key-value pairs with extra context passed to the agent (e.g. account balance, product name).
​
webhook_url
string
URL to receive call event webhooks (call started, ended, transcript ready, etc.) for this specific call.
​
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 associated with the call, if applicable.
​
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
  • 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" }
    ]
  }'

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