POST
/
v1
/
phone-numbers
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>' \
  --data '{
  "phone_number": "+14155551234",
  "campaign_id": "<string>",
  "inbound_call_enabled": true,
  "outbound_call_enabled": true,
  "region": "CA",
  "country_code": "US",
  "type": "local"
}'
{
  "_id": "<string>",
  "name": "<string>",
  "status": "CREATED",
  "account_id": "<string>",
  "agents": [
    "<string>"
  ],
  "phone_numbers": [
    "<string>"
  ],
  "inbound_phone_numbers": [
    "<string>"
  ],
  "claimed_phone_numbers": {},
  "dispositions": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "parent_disposition": "<string>",
      "color": "<string>",
      "contacted": true,
      "conversion": true,
      "enabled": true
    }
  ],
  "disposition_instructions": "<string>",
  "disposition_level_2_instructions": "<string>",
  "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
  },
  "enabled": true,
  "history": {
    "revision": 0,
    "created_at": "2023-11-07T05:31:56Z",
    "created_by": "unknown",
    "last_modified_at": "2023-11-07T05:31:56Z",
    "last_modified_by": "unknown"
  },
  "call_transfer_phone_number": "<string>",
  "tasks": [
    {
      "task_type": "try_again",
      "task_settings": {},
      "type": "post_call",
      "condition": {
        "call_count": [
          123
        ],
        "dispositions": [
          {
            "field": "twilio_status",
            "values": [
              "<string>"
            ]
          }
        ]
      },
      "required": false
    }
  ],
  "call_now_threshold_recall_time": 123,
  "external_context_template": "<string>",
  "system_prompt": {
    "inbound": {
      "sections": [
        {
          "title": "<string>",
          "description": "<string>"
        }
      ],
      "conversation_seeder": [
        "<string>"
      ],
      "structured_conversation_seeder": [
        {
          "role": "system",
          "content": "<string>",
          "tool_calls": [
            "<any>"
          ]
        }
      ],
      "type": "outbound",
      "medium": "web_voice",
      "extend_sections": false,
      "extend_conversation_seeder": false
    },
    "outbound": {
      "sections": [
        {
          "title": "<string>",
          "description": "<string>"
        }
      ],
      "conversation_seeder": [
        "<string>"
      ],
      "structured_conversation_seeder": [
        {
          "role": "system",
          "content": "<string>",
          "tool_calls": [
            "<any>"
          ]
        }
      ],
      "type": "outbound",
      "medium": "web_voice",
      "extend_sections": true,
      "extend_conversation_seeder": true
    }
  },
  "disable_system_dispositioning": true,
  "campaign_duration": {
    "campaign_start_date": "2023-11-07T05:31:56Z",
    "campaign_end_date": "2023-11-07T05:31:56Z"
  },
  "disable_amd": true,
  "custom_fields": {},
  "a2p_status": "rejected",
  "initial_contact_medium": "web_voice",
  "precall_tasks_execution_mode": "prolonged_ringing",
  "inbound_lead_list": "<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

​
X-API-KEY
string
header
required

Body

application/json

Request data for purchasing (claiming) a phone number

​
phone_number
string<phone>
required

The phone number to claim from the list of available phone numbers

Examples:

"+14155551234"

​
campaign_id
string
required
Required string length: 24
​
inbound_call_enabled
boolean
required

Whether the phone should be setup to receive inbound calls.

​
outbound_call_enabled
boolean
required

Whether the phone should be setup to make outbound calls.

​
region
string | null

The region of the phone number. You can use it to easily identify the phone number.

Examples:

"CA"

​
country_code
string | null

The country code of the phone number. You can use this field to easily identify the phone number.

Examples:

"US"

​
type
enum<string> | null

The type of the phone number. Either local or toll-free. You can use this field to easily identify the phone number.

Available options:
local,
toll-free

Response

Successful Response

Container for a single campaign record.

​
name
string
required
​
status
enum<string>
required
Available options:
CREATED,
ACTIVE,
INACTIVE,
PAUSED,
PROCESSED
​
_id
string | null
​
account_id
string | null
​
agents
string[]
​
phone_numbers
string[] | null
​
inbound_phone_numbers
string[] | null
​
claimed_phone_numbers
object | null

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.

​
dispositions
DispositionModel · object[]
​
disposition_instructions
string | null
deprecated

scheduled for removal

​
disposition_level_2_instructions
string | null
deprecated

scheduled for removal

​
rules
object | null
​
enabled
boolean | null
default:true
​
history
object
​
call_transfer_phone_number
string | null
​
tasks
CallTask · object[]
​
call_now_threshold_recall_time
integer | null
​
external_context_template
string | null
​
system_prompt
object | null
​
disable_system_dispositioning
boolean | null
default:false
​
campaign_duration
object | null
​
disable_amd
boolean | null
default:false
​
custom_fields
object | null
​
a2p_status
enum<string> | null
deprecated

Use organization.twilio.a2p_status instead.

Available options:
rejected,
verified,
pending,
unknown
​
initial_contact_medium
enum<string> | null
Available options:
web_voice,
telephony,
sms,
email,
chatbot
​
precall_tasks_execution_mode
enum<string> | null
default:prolonged_ringing

Inbound PreCallTasks can be executed:

  1. 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.
Available options:
prolonged_ringing
​
inbound_lead_list
string | null

The ID of the lead list associated with this campaign. Used to track and manage inbound leads.