Saltar al contenido principal
POST
/
v1
/
agents
curl -X POST "https://api.contactship.ai/v1/agents" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Agent",
    "voice_id": "voice-abc123",
    "timezone": "America/Mexico_City",
    "person_name": "Alex",
    "language": "es-MX",
    "interruption_sensitivity": 0.8
  }'

{
  "agent_id": "agent-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Sales Agent",
  "voice_id": "voice-abc123",
  "timezone": "America/Mexico_City",
  "person_name": "Alex",
  "language": "es-MX",
  "interruption_sensitivity": 0.8,
  "created_at": "2026-04-06T12:00:00Z"
}
Creates a new AI phone agent in your organization. The agent can then be used to make outbound calls or handle inbound calls.

​
Headers

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

​
Body

​
name
string
requerido
The agent’s display name.
​
voice_id
string
requerido
The voice ID to use for the agent. Use List Voices to retrieve available voice IDs.
​
timezone
string
requerido
The agent’s timezone in IANA format (e.g. America/Mexico_City, America/New_York, America/Argentina/Buenos_Aires).
​
person_name
string
The human name the agent introduces itself as during calls.
​
language
string
Language code for the agent (e.g. en-US, es-ES). Defaults to the organization default.
​
ambient_sound
string
Background sound to play during calls (e.g. office, cafe).
​
interruption_sensitivity
number
How sensitive the agent is to being interrupted. Value between 0.1 and 1.0. Higher values mean the agent stops speaking more easily when interrupted.
​
webhook_url
string
URL to receive call event webhooks for this agent.

​
Response

Returns the created agent object.
​
agent_id
string
Unique identifier of the created agent.
​
name
string
The agent’s display name.
​
voice_id
string
The voice ID assigned to the agent.
​
timezone
string
The agent’s timezone.
​
created_at
string
Timestamp when the agent 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/agents" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Agent",
    "voice_id": "voice-abc123",
    "timezone": "America/Mexico_City",
    "person_name": "Alex",
    "language": "es-MX",
    "interruption_sensitivity": 0.8
  }'

{
  "agent_id": "agent-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Sales Agent",
  "voice_id": "voice-abc123",
  "timezone": "America/Mexico_City",
  "person_name": "Alex",
  "language": "es-MX",
  "interruption_sensitivity": 0.8,
  "created_at": "2026-04-06T12:00:00Z"
}