> ## 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.

# Create Agent

> Create a new AI phone agent

Creates a new AI phone agent in your organization. The agent can then be used to make outbound calls or handle inbound calls.

## Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication. Found in your dashboard under API settings.
</ParamField>

## Body

<ParamField body="name" type="string" required>
  The agent's display name.
</ParamField>

<ParamField body="voice_id" type="string" required>
  The voice ID to use for the agent. Use [List Voices](/api-reference/endpoint/list-agents) to retrieve available voice IDs.
</ParamField>

<ParamField body="timezone" type="string" required>
  The agent's timezone in IANA format (e.g. `America/Mexico_City`, `America/New_York`, `America/Argentina/Buenos_Aires`).
</ParamField>

<ParamField body="person_name" type="string">
  The human name the agent introduces itself as during calls.
</ParamField>

<ParamField body="language" type="string">
  Language code for the agent (e.g. `en-US`, `es-ES`). Defaults to the organization default.
</ParamField>

<ParamField body="ambient_sound" type="string">
  Background sound to play during calls (e.g. `office`, `cafe`).
</ParamField>

<ParamField body="interruption_sensitivity" type="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.
</ParamField>

<ParamField body="webhook_url" type="string">
  URL to receive call event webhooks for this agent.
</ParamField>

## Response

Returns the created agent object.

<ResponseField name="agent_id" type="string">
  Unique identifier of the created agent.
</ResponseField>

<ResponseField name="name" type="string">
  The agent's display name.
</ResponseField>

<ResponseField name="voice_id" type="string">
  The voice ID assigned to the agent.
</ResponseField>

<ResponseField name="timezone" type="string">
  The agent's timezone.
</ResponseField>

<ResponseField name="created_at" type="string">
  Timestamp when the agent was created (ISO 8601).
</ResponseField>

## 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

<RequestExample>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.contactship.ai/v1/agents', {
    method: 'POST',
    headers: {
      'x-api-key': 'your-api-key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Sales Agent',
      voice_id: 'voice-abc123',
      timezone: 'America/Mexico_City',
      person_name: 'Alex',
      language: 'es-MX',
      interruption_sensitivity: 0.8,
    }),
  });
  const agent = await response.json();
  console.log(`Created agent: ${agent.agent_id}`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.contactship.ai/v1/agents',
      headers={'x-api-key': 'your-api-key'},
      json={
          'name': 'Sales Agent',
          'voice_id': 'voice-abc123',
          'timezone': 'America/Mexico_City',
          'person_name': 'Alex',
          'language': 'es-MX',
          'interruption_sensitivity': 0.8,
      },
  )
  agent = response.json()
  print(f"Created agent: {agent['agent_id']}")
  ```
</RequestExample>

<ResponseExample>
  ```json Example Response theme={null}
  {
    "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"
  }
  ```
</ResponseExample>