Skip to main content
POST
Claim Phone Number

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

Your API key for authentication.

x-org-id
string
header
required

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

carrier
string
default:twilio
deprecated

Deprecated: pass carrier in the request body instead. Carrier to purchase from: twilio or telnyx

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

Example:

"+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.

Example:

"CA"

country_code
string | null

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

Example:

"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
carrier
string | null

Carrier to purchase from: twilio or telnyx. Takes precedence over the deprecated carrier query parameter.

Example:

"twilio"

Response

Successful Response

name
string
required
status
enum<string>
required
Available options:
CREATED,
ACTIVE,
INACTIVE,
PAUSED,
PROCESSED
id
string | null
account_id
string | null
agents
string[]
agent_snapshot_map
Agent Snapshot Map · object | null

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.

distribution_strategy
enum<string>
default:random

How calls are distributed among agents in a campaign.

Available options:
round_robin,
custom_percentage,
random
distribution_settings
DistributionSettings · object | null

Settings for the distribution strategy. Required for custom_percentage distribution strategy.

distribution_by_medium
Distribution By Medium · object | null

Per-medium agent pools and distribution; mediums without an entry use the default distribution.

phone_numbers
string[] | null
inbound_phone_numbers
string[] | null
claimed_phone_numbers
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

disposition_level_3_prompt
string | null

Custom prompt to classify call outcome. If not provided, a default prompt will be used.

call_summary_description
string | null

Instructions for this campaign's call summary. Blank uses the system default.

disposition_level_3_reasoning
enum<string> | null

Reasoning effort for disposition classification and its call summary. Null inherits the agent's reasoning setting, then the system default.

Available options:
none,
low,
medium,
high
disposition_level_3_model

Model to use for disposition level 3 classification. If not provided, the default model will be used.

Available options:
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
rules
Rules · object | null
enabled
boolean | null
default:true
history
HistoryModel · object | null
tasks
CallTask · object[]
call_now_threshold_recall_time
integer | null
external_context_template
string | null
system_prompt
EmbeddedSystemPromptModel · object | null
disable_system_dispositioning
boolean | null
default:false
campaign_duration
CampaignDuration · object | null
disable_amd
boolean | null
default:false
deprecated

Deprecated legacy AMD toggle for old carrier paths. New voice engines use per-agent amd settings.

answering_machine_detection
AnsweringMachineDetectionSettings · object
deprecated

Deprecated campaign-level answering machine detection settings. Use per-agent amd settings instead. Existing old engines may still read this field.

custom_fields
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,
api_text,
chat_app,
softphone
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.

telephony_outbound_caller_id
string | null

Optional ObjectId referencing the caller ID to be used when making outbound phone calls for this campaign.

sip_proxy_settings
SipProxySettings · object | null
v3_voice_routing_percentage
integer
default:0

Percent of inbound SIP-proxy calls for this campaign routed to voice engine v3.

Required range: 0 <= x <= 100
v3_voice_redirect_campaign_id
string | null

Optional campaign the v3-routed fraction resolves to (via that campaign's inbound lead list). None keeps v3 calls on this campaign.

source
CampaignSourceModel · object | null

Tracks the source campaign this was cloned from.