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