curl --request POST \
--url https://api.eqho.ai/v1/phone-numbers \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--header 'x-org-id: <api-key>' \
--data '
{
"phone_number": "+14155551234",
"campaign_id": "<string>",
"inbound_call_enabled": true,
"outbound_call_enabled": true,
"region": "CA",
"country_code": "US",
"carrier": "twilio"
}
'import requests
url = "https://api.eqho.ai/v1/phone-numbers"
payload = {
"phone_number": "+14155551234",
"campaign_id": "<string>",
"inbound_call_enabled": True,
"outbound_call_enabled": True,
"region": "CA",
"country_code": "US",
"carrier": "twilio"
}
headers = {
"X-API-KEY": "<api-key>",
"x-org-id": "<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>',
'x-org-id': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
phone_number: '+14155551234',
campaign_id: '<string>',
inbound_call_enabled: true,
outbound_call_enabled: true,
region: 'CA',
country_code: 'US',
carrier: 'twilio'
})
};
fetch('https://api.eqho.ai/v1/phone-numbers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.eqho.ai/v1/phone-numbers"
payload := strings.NewReader("{\n \"phone_number\": \"+14155551234\",\n \"campaign_id\": \"<string>\",\n \"inbound_call_enabled\": true,\n \"outbound_call_enabled\": true,\n \"region\": \"CA\",\n \"country_code\": \"US\",\n \"carrier\": \"twilio\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<api-key>")
req.Header.Add("x-org-id", "<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))
}{
"name": "<string>",
"status": "CREATED",
"id": "<string>",
"account_id": "<string>",
"agents": [
"<string>"
],
"agent_snapshot_map": {},
"distribution_strategy": "random",
"distribution_settings": {
"percentages": {},
"last_assigned_agent_index": -1
},
"distribution_by_medium": {},
"phone_numbers": [
"<string>"
],
"inbound_phone_numbers": [
"<string>"
],
"claimed_phone_numbers": {},
"dispositions": [
{
"id": "<string>",
"name": "<string>",
"parent_disposition": "<string>",
"description": "<string>",
"color": "#A5A5A5",
"contacted": true,
"conversion": true,
"blocklist_level": "CAMPAIGN",
"enabled": true
}
],
"disposition_instructions": "<string>",
"disposition_level_2_instructions": "<string>",
"disposition_level_3_prompt": "<string>",
"call_summary_description": "<string>",
"disposition_level_3_reasoning": "none",
"disposition_level_3_model": "gpt-5.4",
"rules": {
"call_limit": 123,
"call_window": [
{
"weekday": 1,
"start_time": 1179,
"end_time": 1179
}
],
"messenger_disposition_threshold_in_minutes": 123,
"medium_response_settings": {},
"api_text_disposition_threshold_in_minutes": 123,
"should_answer_policy": {
"enabled": false,
"mode": "suppress_only",
"enabled_mediums": [
"web_voice"
],
"exact_match_enabled": true,
"jaccard_enabled": true,
"suppress_threshold": 0.85,
"fuzzy_threshold": 0.5,
"llm_judge_enabled": false,
"llm_judge_always": false,
"llm_judge_action": "rewrite",
"model": "gpt-5.4",
"timeout_seconds": 10,
"num_retries": 1,
"max_consecutive_suppressions": 2,
"on_suppression_limit_reached": "force_send",
"suppression_history_enabled": true,
"suppression_history_max_size": 10,
"llm_judge_prompt_markdown": "<string>",
"llm_rewrite_prompt_markdown": "<string>"
},
"message_reaction_policy": {
"action": "completely_ignore",
"enabled_mediums": [
"web_voice"
]
},
"session_timeout": {
"days": 0,
"hours": 0,
"minutes": 0
}
},
"enabled": true,
"history": {
"last_modified_at": "2023-11-07T05:31:56Z",
"revision": 0,
"created_at": "2023-11-07T05:31:56Z",
"created_by": "unknown",
"last_modified_by": "unknown"
},
"tasks": [
{
"task_type": "try_again",
"task_settings": {},
"id": "<string>",
"name": "<string>",
"type": "post_call",
"condition": {
"call_count": [
123
],
"dispositions": [
{
"field": "twilio_status",
"values": [
"<string>"
]
}
],
"ai_conditions": [
{
"condition": "Did the lead say there is a child in the car?",
"confidence_threshold": 0.5
}
],
"eval_conditions": [
{
"grader_name": "<string>",
"values": [
"<string>"
],
"passed": true
}
],
"expression_conditions": [
{
"expression": "conversation.action_runs.call_transfer.last.success"
}
]
},
"required": false,
"enabled": true
}
],
"call_now_threshold_recall_time": 123,
"external_context_template": "<string>",
"system_prompt": {
"inbound": {
"sections": [
{
"title": "<string>",
"description": "<string>"
}
],
"medium": "web_voice",
"conversation_seeder": [
"<string>"
],
"structured_conversation_seeder": [
{
"role": "system",
"content": "<string>",
"tool_calls": [
{
"name": "<string>",
"arguments": {}
}
]
}
],
"type": "outbound",
"extend_sections": false,
"extend_conversation_seeder": false
},
"outbound": {
"sections": [
{
"title": "<string>",
"description": "<string>"
}
],
"medium": "web_voice",
"conversation_seeder": [
"<string>"
],
"structured_conversation_seeder": [
{
"role": "system",
"content": "<string>",
"tool_calls": [
{
"name": "<string>",
"arguments": {}
}
]
}
],
"type": "outbound",
"extend_sections": false,
"extend_conversation_seeder": false
}
},
"disable_system_dispositioning": false,
"campaign_duration": {
"campaign_start_date": "2023-11-07T05:31:56Z",
"campaign_end_date": "2023-11-07T05:31:56Z"
},
"disable_amd": false,
"answering_machine_detection": {
"enabled": true,
"interrupt_on_machine": true,
"machine_ivr_behavior": "native_ivr",
"machine_vm_behavior": "hang_up",
"machine_unavailable_behavior": "hang_up",
"voicemail_message": "<string>",
"llm_model": "<string>",
"stt_model": "<string>",
"detection_options": {
"human_speech_threshold": 123,
"human_silence_threshold": 123,
"machine_silence_threshold": 123,
"no_speech_threshold": 123,
"timeout": 123,
"prompt": "<string>"
}
},
"custom_fields": {},
"a2p_status": "rejected",
"initial_contact_medium": "web_voice",
"precall_tasks_execution_mode": "prolonged_ringing",
"inbound_lead_list": "<string>",
"telephony_outbound_caller_id": "<string>",
"sip_proxy_settings": {
"sip_uri": "<string>",
"enabled": false,
"transport": "tcp",
"username": "<string>",
"password": "<string>",
"password_configured": true
},
"v3_voice_routing_percentage": 0,
"v3_voice_redirect_campaign_id": "<string>",
"source": {
"campaign_id": "<string>",
"account_id": "<string>",
"snapshot_id": "<string>",
"pending_publish": {
"source_snapshot_id": "<string>",
"source_snapshot_tag": "<string>",
"conflicts": [
{
"conflict_type": "field",
"entity_type": "<string>",
"entity_id": "<string>",
"entity_name": "<string>",
"field": "<string>",
"base_value": "<unknown>",
"source_value": "<unknown>",
"clone_value": "<unknown>"
}
],
"created_at": "2023-11-07T05:31:56Z"
}
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Claim Phone Number
curl --request POST \
--url https://api.eqho.ai/v1/phone-numbers \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--header 'x-org-id: <api-key>' \
--data '
{
"phone_number": "+14155551234",
"campaign_id": "<string>",
"inbound_call_enabled": true,
"outbound_call_enabled": true,
"region": "CA",
"country_code": "US",
"carrier": "twilio"
}
'import requests
url = "https://api.eqho.ai/v1/phone-numbers"
payload = {
"phone_number": "+14155551234",
"campaign_id": "<string>",
"inbound_call_enabled": True,
"outbound_call_enabled": True,
"region": "CA",
"country_code": "US",
"carrier": "twilio"
}
headers = {
"X-API-KEY": "<api-key>",
"x-org-id": "<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>',
'x-org-id': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
phone_number: '+14155551234',
campaign_id: '<string>',
inbound_call_enabled: true,
outbound_call_enabled: true,
region: 'CA',
country_code: 'US',
carrier: 'twilio'
})
};
fetch('https://api.eqho.ai/v1/phone-numbers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.eqho.ai/v1/phone-numbers"
payload := strings.NewReader("{\n \"phone_number\": \"+14155551234\",\n \"campaign_id\": \"<string>\",\n \"inbound_call_enabled\": true,\n \"outbound_call_enabled\": true,\n \"region\": \"CA\",\n \"country_code\": \"US\",\n \"carrier\": \"twilio\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<api-key>")
req.Header.Add("x-org-id", "<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))
}{
"name": "<string>",
"status": "CREATED",
"id": "<string>",
"account_id": "<string>",
"agents": [
"<string>"
],
"agent_snapshot_map": {},
"distribution_strategy": "random",
"distribution_settings": {
"percentages": {},
"last_assigned_agent_index": -1
},
"distribution_by_medium": {},
"phone_numbers": [
"<string>"
],
"inbound_phone_numbers": [
"<string>"
],
"claimed_phone_numbers": {},
"dispositions": [
{
"id": "<string>",
"name": "<string>",
"parent_disposition": "<string>",
"description": "<string>",
"color": "#A5A5A5",
"contacted": true,
"conversion": true,
"blocklist_level": "CAMPAIGN",
"enabled": true
}
],
"disposition_instructions": "<string>",
"disposition_level_2_instructions": "<string>",
"disposition_level_3_prompt": "<string>",
"call_summary_description": "<string>",
"disposition_level_3_reasoning": "none",
"disposition_level_3_model": "gpt-5.4",
"rules": {
"call_limit": 123,
"call_window": [
{
"weekday": 1,
"start_time": 1179,
"end_time": 1179
}
],
"messenger_disposition_threshold_in_minutes": 123,
"medium_response_settings": {},
"api_text_disposition_threshold_in_minutes": 123,
"should_answer_policy": {
"enabled": false,
"mode": "suppress_only",
"enabled_mediums": [
"web_voice"
],
"exact_match_enabled": true,
"jaccard_enabled": true,
"suppress_threshold": 0.85,
"fuzzy_threshold": 0.5,
"llm_judge_enabled": false,
"llm_judge_always": false,
"llm_judge_action": "rewrite",
"model": "gpt-5.4",
"timeout_seconds": 10,
"num_retries": 1,
"max_consecutive_suppressions": 2,
"on_suppression_limit_reached": "force_send",
"suppression_history_enabled": true,
"suppression_history_max_size": 10,
"llm_judge_prompt_markdown": "<string>",
"llm_rewrite_prompt_markdown": "<string>"
},
"message_reaction_policy": {
"action": "completely_ignore",
"enabled_mediums": [
"web_voice"
]
},
"session_timeout": {
"days": 0,
"hours": 0,
"minutes": 0
}
},
"enabled": true,
"history": {
"last_modified_at": "2023-11-07T05:31:56Z",
"revision": 0,
"created_at": "2023-11-07T05:31:56Z",
"created_by": "unknown",
"last_modified_by": "unknown"
},
"tasks": [
{
"task_type": "try_again",
"task_settings": {},
"id": "<string>",
"name": "<string>",
"type": "post_call",
"condition": {
"call_count": [
123
],
"dispositions": [
{
"field": "twilio_status",
"values": [
"<string>"
]
}
],
"ai_conditions": [
{
"condition": "Did the lead say there is a child in the car?",
"confidence_threshold": 0.5
}
],
"eval_conditions": [
{
"grader_name": "<string>",
"values": [
"<string>"
],
"passed": true
}
],
"expression_conditions": [
{
"expression": "conversation.action_runs.call_transfer.last.success"
}
]
},
"required": false,
"enabled": true
}
],
"call_now_threshold_recall_time": 123,
"external_context_template": "<string>",
"system_prompt": {
"inbound": {
"sections": [
{
"title": "<string>",
"description": "<string>"
}
],
"medium": "web_voice",
"conversation_seeder": [
"<string>"
],
"structured_conversation_seeder": [
{
"role": "system",
"content": "<string>",
"tool_calls": [
{
"name": "<string>",
"arguments": {}
}
]
}
],
"type": "outbound",
"extend_sections": false,
"extend_conversation_seeder": false
},
"outbound": {
"sections": [
{
"title": "<string>",
"description": "<string>"
}
],
"medium": "web_voice",
"conversation_seeder": [
"<string>"
],
"structured_conversation_seeder": [
{
"role": "system",
"content": "<string>",
"tool_calls": [
{
"name": "<string>",
"arguments": {}
}
]
}
],
"type": "outbound",
"extend_sections": false,
"extend_conversation_seeder": false
}
},
"disable_system_dispositioning": false,
"campaign_duration": {
"campaign_start_date": "2023-11-07T05:31:56Z",
"campaign_end_date": "2023-11-07T05:31:56Z"
},
"disable_amd": false,
"answering_machine_detection": {
"enabled": true,
"interrupt_on_machine": true,
"machine_ivr_behavior": "native_ivr",
"machine_vm_behavior": "hang_up",
"machine_unavailable_behavior": "hang_up",
"voicemail_message": "<string>",
"llm_model": "<string>",
"stt_model": "<string>",
"detection_options": {
"human_speech_threshold": 123,
"human_silence_threshold": 123,
"machine_silence_threshold": 123,
"no_speech_threshold": 123,
"timeout": 123,
"prompt": "<string>"
}
},
"custom_fields": {},
"a2p_status": "rejected",
"initial_contact_medium": "web_voice",
"precall_tasks_execution_mode": "prolonged_ringing",
"inbound_lead_list": "<string>",
"telephony_outbound_caller_id": "<string>",
"sip_proxy_settings": {
"sip_uri": "<string>",
"enabled": false,
"transport": "tcp",
"username": "<string>",
"password": "<string>",
"password_configured": true
},
"v3_voice_routing_percentage": 0,
"v3_voice_redirect_campaign_id": "<string>",
"source": {
"campaign_id": "<string>",
"account_id": "<string>",
"snapshot_id": "<string>",
"pending_publish": {
"source_snapshot_id": "<string>",
"source_snapshot_tag": "<string>",
"conflicts": [
{
"conflict_type": "field",
"entity_type": "<string>",
"entity_id": "<string>",
"entity_name": "<string>",
"field": "<string>",
"base_value": "<unknown>",
"source_value": "<unknown>",
"clone_value": "<unknown>"
}
],
"created_at": "2023-11-07T05:31:56Z"
}
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}How to Claim a Phone Number
Purchasing a phone number is a two-step process. First, you need to search for available phone numbers using the Get available numbers endpoint. Then, you can purchase one of the available phone numbers using this endpoint.Authorizations
Your API key for authentication.
Org impersonation via x-org-id. Superadmins may impersonate any org; admins may impersonate their direct sub-organizations. Enter the target organization ID to act as that org.
Query Parameters
Deprecated: pass carrier in the request body instead. Carrier to purchase from: twilio or telnyx
Body
Request data for purchasing (claiming) a phone number
The phone number to claim from the list of available phone numbers
"+14155551234"
24Whether the phone should be setup to receive inbound calls.
Whether the phone should be setup to make outbound calls.
The region of the phone number. You can use it to easily identify the phone number.
"CA"
The country code of the phone number. You can use this field to easily identify the phone number.
"US"
The type of the phone number. Either local or toll-free. You can use this field to easily identify the phone number.
local, toll-free Carrier to purchase from: twilio or telnyx. Takes precedence over the deprecated carrier query parameter.
"twilio"
Response
Successful Response
CREATED, ACTIVE, INACTIVE, PAUSED, PROCESSED Optional mapping of agent_id to snapshot_id or 'latest'. Keys must be agent IDs present in the campaign's agents array. Values are either ObjectId strings referencing agent snapshots, or 'latest' to auto-resolve the newest snapshot.
Show child attributes
Show child attributes
How calls are distributed among agents in a campaign.
round_robin, custom_percentage, random Settings for the distribution strategy. Required for custom_percentage distribution strategy.
Show child attributes
Show child attributes
Per-medium agent pools and distribution; mediums without an entry use the default distribution.
Show child attributes
Show child attributes
Phone numbers used by this campaign. Keyed by phone number. Using dict to ensure uniqueness. Stored also in phone_numbers and inbound_phone_numbers for backwards compatibility.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
scheduled for removal
scheduled for removal
Custom prompt to classify call outcome. If not provided, a default prompt will be used.
Instructions for this campaign's call summary. Blank uses the system default.
Reasoning effort for disposition classification and its call summary. Null inherits the agent's reasoning setting, then the system default.
none, low, medium, high Model to use for disposition level 3 classification. If not provided, the default model will be used.
gpt-5.4, gpt-5.4-pro, gpt-5.2, gpt-5.2-pro, gpt-5.1, gpt-5, gpt-5-pro, gpt-5-mini, gpt-5-nano, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-4o, gpt-4o-mini, o3, o3-pro, o3-mini, o4-mini, claude-opus-4-6-20260205, claude-sonnet-4-6-20260205, claude-opus-4-5-20251101, claude-sonnet-4-5-20250929, claude-haiku-4-5-20251001, claude-opus-4-20250514, claude-sonnet-4-20250514, gemini-3.1-pro-preview, gemini-3-flash-preview, gemini-2.5-pro, deepseek-chat, deepseek-reasoner, gpt-5-chat-latest, gpt-5.1-chat-latest, gpt-5.2-chat-latest, gpt-5.3-chat-latest Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Deprecated legacy AMD toggle for old carrier paths. New voice engines use per-agent amd settings.
Deprecated campaign-level answering machine detection settings. Use per-agent amd settings instead. Existing old engines may still read this field.
Show child attributes
Show child attributes
Use organization.twilio.a2p_status instead.
rejected, verified, pending, unknown web_voice, telephony, sms, email, chatbot, api_text, chat_app, softphone Inbound PreCallTasks can be executed:
- During the ringing phase (prolonged_ringing) - the tasks will be executed while the call is ringing. Agent will pick up the call only after the tasks are completed. Max duration is 10 seconds.
prolonged_ringing The ID of the lead list associated with this campaign. Used to track and manage inbound leads.
Optional ObjectId referencing the caller ID to be used when making outbound phone calls for this campaign.
Show child attributes
Show child attributes
Percent of inbound SIP-proxy calls for this campaign routed to voice engine v3.
0 <= x <= 100Optional campaign the v3-routed fraction resolves to (via that campaign's inbound lead list). None keeps v3 calls on this campaign.
Tracks the source campaign this was cloned from.
Show child attributes
Show child attributes
Was this page helpful?