Create Agent
curl --request POST \
--url https://api.contactship.ai/v1/agents \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"name": "<string>",
"voice_id": "<string>",
"timezone": "<string>",
"person_name": "<string>",
"language": "<string>",
"conversation_purpose": "<string>",
"prompt": "<string>",
"webhook_url": "<string>",
"ambient_sound": "<string>",
"voice_speed": 123,
"voice_temperature": 123,
"volume": 123,
"ambient_sound_volume": 123,
"responsiveness": 123,
"interruption_sensitivity": 123,
"begin_message": "<string>",
"begin_message_delay_ms": 123,
"max_call_duration_ms": 123,
"boosted_keywords": [
"<string>"
],
"post_call_analysis_data": [
{}
],
"tools": [
{}
]
}
'import requests
url = "https://api.contactship.ai/v1/agents"
payload = {
"name": "<string>",
"voice_id": "<string>",
"timezone": "<string>",
"person_name": "<string>",
"language": "<string>",
"conversation_purpose": "<string>",
"prompt": "<string>",
"webhook_url": "<string>",
"ambient_sound": "<string>",
"voice_speed": 123,
"voice_temperature": 123,
"volume": 123,
"ambient_sound_volume": 123,
"responsiveness": 123,
"interruption_sensitivity": 123,
"begin_message": "<string>",
"begin_message_delay_ms": 123,
"max_call_duration_ms": 123,
"boosted_keywords": ["<string>"],
"post_call_analysis_data": [{}],
"tools": [{}]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
voice_id: '<string>',
timezone: '<string>',
person_name: '<string>',
language: '<string>',
conversation_purpose: '<string>',
prompt: '<string>',
webhook_url: '<string>',
ambient_sound: '<string>',
voice_speed: 123,
voice_temperature: 123,
volume: 123,
ambient_sound_volume: 123,
responsiveness: 123,
interruption_sensitivity: 123,
begin_message: '<string>',
begin_message_delay_ms: 123,
max_call_duration_ms: 123,
boosted_keywords: ['<string>'],
post_call_analysis_data: [{}],
tools: [{}]
})
};
fetch('https://api.contactship.ai/v1/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.contactship.ai/v1/agents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'voice_id' => '<string>',
'timezone' => '<string>',
'person_name' => '<string>',
'language' => '<string>',
'conversation_purpose' => '<string>',
'prompt' => '<string>',
'webhook_url' => '<string>',
'ambient_sound' => '<string>',
'voice_speed' => 123,
'voice_temperature' => 123,
'volume' => 123,
'ambient_sound_volume' => 123,
'responsiveness' => 123,
'interruption_sensitivity' => 123,
'begin_message' => '<string>',
'begin_message_delay_ms' => 123,
'max_call_duration_ms' => 123,
'boosted_keywords' => [
'<string>'
],
'post_call_analysis_data' => [
[
]
],
'tools' => [
[
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.contactship.ai/v1/agents"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"voice_id\": \"<string>\",\n \"timezone\": \"<string>\",\n \"person_name\": \"<string>\",\n \"language\": \"<string>\",\n \"conversation_purpose\": \"<string>\",\n \"prompt\": \"<string>\",\n \"webhook_url\": \"<string>\",\n \"ambient_sound\": \"<string>\",\n \"voice_speed\": 123,\n \"voice_temperature\": 123,\n \"volume\": 123,\n \"ambient_sound_volume\": 123,\n \"responsiveness\": 123,\n \"interruption_sensitivity\": 123,\n \"begin_message\": \"<string>\",\n \"begin_message_delay_ms\": 123,\n \"max_call_duration_ms\": 123,\n \"boosted_keywords\": [\n \"<string>\"\n ],\n \"post_call_analysis_data\": [\n {}\n ],\n \"tools\": [\n {}\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.contactship.ai/v1/agents")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"voice_id\": \"<string>\",\n \"timezone\": \"<string>\",\n \"person_name\": \"<string>\",\n \"language\": \"<string>\",\n \"conversation_purpose\": \"<string>\",\n \"prompt\": \"<string>\",\n \"webhook_url\": \"<string>\",\n \"ambient_sound\": \"<string>\",\n \"voice_speed\": 123,\n \"voice_temperature\": 123,\n \"volume\": 123,\n \"ambient_sound_volume\": 123,\n \"responsiveness\": 123,\n \"interruption_sensitivity\": 123,\n \"begin_message\": \"<string>\",\n \"begin_message_delay_ms\": 123,\n \"max_call_duration_ms\": 123,\n \"boosted_keywords\": [\n \"<string>\"\n ],\n \"post_call_analysis_data\": [\n {}\n ],\n \"tools\": [\n {}\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.contactship.ai/v1/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"voice_id\": \"<string>\",\n \"timezone\": \"<string>\",\n \"person_name\": \"<string>\",\n \"language\": \"<string>\",\n \"conversation_purpose\": \"<string>\",\n \"prompt\": \"<string>\",\n \"webhook_url\": \"<string>\",\n \"ambient_sound\": \"<string>\",\n \"voice_speed\": 123,\n \"voice_temperature\": 123,\n \"volume\": 123,\n \"ambient_sound_volume\": 123,\n \"responsiveness\": 123,\n \"interruption_sensitivity\": 123,\n \"begin_message\": \"<string>\",\n \"begin_message_delay_ms\": 123,\n \"max_call_duration_ms\": 123,\n \"boosted_keywords\": [\n \"<string>\"\n ],\n \"post_call_analysis_data\": [\n {}\n ],\n \"tools\": [\n {}\n ]\n}"
response = http.request(request)
puts response.read_bodyAgentes
Create Agent
Create a voice agent and automatically publish its first version.
POST
/
v1
/
agents
Create Agent
curl --request POST \
--url https://api.contactship.ai/v1/agents \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"name": "<string>",
"voice_id": "<string>",
"timezone": "<string>",
"person_name": "<string>",
"language": "<string>",
"conversation_purpose": "<string>",
"prompt": "<string>",
"webhook_url": "<string>",
"ambient_sound": "<string>",
"voice_speed": 123,
"voice_temperature": 123,
"volume": 123,
"ambient_sound_volume": 123,
"responsiveness": 123,
"interruption_sensitivity": 123,
"begin_message": "<string>",
"begin_message_delay_ms": 123,
"max_call_duration_ms": 123,
"boosted_keywords": [
"<string>"
],
"post_call_analysis_data": [
{}
],
"tools": [
{}
]
}
'import requests
url = "https://api.contactship.ai/v1/agents"
payload = {
"name": "<string>",
"voice_id": "<string>",
"timezone": "<string>",
"person_name": "<string>",
"language": "<string>",
"conversation_purpose": "<string>",
"prompt": "<string>",
"webhook_url": "<string>",
"ambient_sound": "<string>",
"voice_speed": 123,
"voice_temperature": 123,
"volume": 123,
"ambient_sound_volume": 123,
"responsiveness": 123,
"interruption_sensitivity": 123,
"begin_message": "<string>",
"begin_message_delay_ms": 123,
"max_call_duration_ms": 123,
"boosted_keywords": ["<string>"],
"post_call_analysis_data": [{}],
"tools": [{}]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
voice_id: '<string>',
timezone: '<string>',
person_name: '<string>',
language: '<string>',
conversation_purpose: '<string>',
prompt: '<string>',
webhook_url: '<string>',
ambient_sound: '<string>',
voice_speed: 123,
voice_temperature: 123,
volume: 123,
ambient_sound_volume: 123,
responsiveness: 123,
interruption_sensitivity: 123,
begin_message: '<string>',
begin_message_delay_ms: 123,
max_call_duration_ms: 123,
boosted_keywords: ['<string>'],
post_call_analysis_data: [{}],
tools: [{}]
})
};
fetch('https://api.contactship.ai/v1/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.contactship.ai/v1/agents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'voice_id' => '<string>',
'timezone' => '<string>',
'person_name' => '<string>',
'language' => '<string>',
'conversation_purpose' => '<string>',
'prompt' => '<string>',
'webhook_url' => '<string>',
'ambient_sound' => '<string>',
'voice_speed' => 123,
'voice_temperature' => 123,
'volume' => 123,
'ambient_sound_volume' => 123,
'responsiveness' => 123,
'interruption_sensitivity' => 123,
'begin_message' => '<string>',
'begin_message_delay_ms' => 123,
'max_call_duration_ms' => 123,
'boosted_keywords' => [
'<string>'
],
'post_call_analysis_data' => [
[
]
],
'tools' => [
[
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.contactship.ai/v1/agents"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"voice_id\": \"<string>\",\n \"timezone\": \"<string>\",\n \"person_name\": \"<string>\",\n \"language\": \"<string>\",\n \"conversation_purpose\": \"<string>\",\n \"prompt\": \"<string>\",\n \"webhook_url\": \"<string>\",\n \"ambient_sound\": \"<string>\",\n \"voice_speed\": 123,\n \"voice_temperature\": 123,\n \"volume\": 123,\n \"ambient_sound_volume\": 123,\n \"responsiveness\": 123,\n \"interruption_sensitivity\": 123,\n \"begin_message\": \"<string>\",\n \"begin_message_delay_ms\": 123,\n \"max_call_duration_ms\": 123,\n \"boosted_keywords\": [\n \"<string>\"\n ],\n \"post_call_analysis_data\": [\n {}\n ],\n \"tools\": [\n {}\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.contactship.ai/v1/agents")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"voice_id\": \"<string>\",\n \"timezone\": \"<string>\",\n \"person_name\": \"<string>\",\n \"language\": \"<string>\",\n \"conversation_purpose\": \"<string>\",\n \"prompt\": \"<string>\",\n \"webhook_url\": \"<string>\",\n \"ambient_sound\": \"<string>\",\n \"voice_speed\": 123,\n \"voice_temperature\": 123,\n \"volume\": 123,\n \"ambient_sound_volume\": 123,\n \"responsiveness\": 123,\n \"interruption_sensitivity\": 123,\n \"begin_message\": \"<string>\",\n \"begin_message_delay_ms\": 123,\n \"max_call_duration_ms\": 123,\n \"boosted_keywords\": [\n \"<string>\"\n ],\n \"post_call_analysis_data\": [\n {}\n ],\n \"tools\": [\n {}\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.contactship.ai/v1/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"voice_id\": \"<string>\",\n \"timezone\": \"<string>\",\n \"person_name\": \"<string>\",\n \"language\": \"<string>\",\n \"conversation_purpose\": \"<string>\",\n \"prompt\": \"<string>\",\n \"webhook_url\": \"<string>\",\n \"ambient_sound\": \"<string>\",\n \"voice_speed\": 123,\n \"voice_temperature\": 123,\n \"volume\": 123,\n \"ambient_sound_volume\": 123,\n \"responsiveness\": 123,\n \"interruption_sensitivity\": 123,\n \"begin_message\": \"<string>\",\n \"begin_message_delay_ms\": 123,\n \"max_call_duration_ms\": 123,\n \"boosted_keywords\": [\n \"<string>\"\n ],\n \"post_call_analysis_data\": [\n {}\n ],\n \"tools\": [\n {}\n ]\n}"
response = http.request(request)
puts response.read_bodyCreate a voice agent and automatically publish its first version.
Provide a valid voice ID and IANA time zone. Creation publishes version 1, so prepare the prompt before attaching a number, campaign, or widget.
Authentication
string
requerido
Organization API key. Keep it on your server or in a credential store.
Body
The first three fields are required; remaining fields are optional.string
requerido
Internal name.
string
requerido
ID from List voices.
string
requerido
IANA time zone, such as
America/Mexico_City.string
In-call name.
string
Supported language code, such as
en-US, es-ES, es-419, or multi (Spanish and English).string
Conversation objective.
string
Instructions, up to 28,000 characters.
string
Outgoing webhook URL.
string
coffee-shop, convention-hall, summer-outdoor, mountain-outdoor, static-noise, or call-center.number
API range 0.5–2; the app slider exposes a narrower range.
number
0–2.
number
0–2.
number
0–2.
number
0–1.
number
0.1–1.
string
Opening phrase, up to 240 characters.
number
0–5,000 milliseconds.
number
Requested maximum call duration in milliseconds, subject to plan limits.
string[]
Terms to improve recognition.
object[]
Extraction definitions with string, enum, boolean, or number type.
object[]
Tool definitions: booking, transfer_call, custom, end_call, or agent_swap. Use the schema for the selected tool type; changing an array can replace its configuration.
Example
Replace VOICE_ID with a current catalog ID.curl -X POST 'https://api.contactship.ai/v1/agents' -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"name":"Showroom assistant","voice_id":"VOICE_ID","timezone":"America/Mexico_City","person_name":"Ana","language":"es-419","conversation_purpose":"Answer showroom questions.","prompt":"Answer only with the business information provided. Ask a person for help when information is missing."}'
Response
Successful creation returns HTTP 201 withstatusCode and data. The identifier is data.id, not agent_id. See Get agent for response fields and List voices for voice IDs.