Phone number endpoints

Model and selection rules: Phone numbers.

GET /api/phone-numbers

page, pageSize. Note this route reads its parameters with single quotes in source, but the names are the same.

Parameter Filter

search

Number substring

state

US state code

areaCode

Area code

provider

external, retell_twilio, retell_telnyx

isActive

true / false

isDeleted

true / false

POST /api/phone-numbers

Purchases a number through MessagingApp and imports it into Retell using the carrier’s SIP trunk and termination URL from EXTERNAL_PROVIDER_CONFIGS.

Body

state or areaCode, and provider (defaults to DEFAULT_EXTERNAL_PROVIDER, i.e. twilio)

The route reads the provider registry dynamically, so adding a carrier requires no change here — only a new entry in EXTERNAL_PROVIDER_CONFIGS.

Automatic purchasing during dialing is currently disabled; this endpoint is the manual path.

GET /api/phone-numbers/{id}

PATCH /api/phone-numbers/{id}

Updates isActive, isDefault, smsEnabled, maxAllowedCallsPerDay, state and cost fields.

Toggling smsEnabled is what makes a number eligible as the from address for outbound SMS, including the send_sms MCP tool.

DELETE /api/phone-numbers/{id}

Releases the number: removed from Retell, returned to the carrier, and marked isReleased with releasedAt. This is a soft delete — the row is retained so historical calls keep a resolvable phoneNumberId.

Scheduled maintenance

Inngest function Schedule Effect

phoneNumberDailyResetCron

Daily 00:00 UTC

Zeroes dailyCallCount on every number

phoneNumberOptimizerCron

Monday 11:15 UTC

Releases numbers unused for 3+ days with fewer than 10 lifetime calls

These are not HTTP endpoints; invoke them from the Inngest dashboard to run them now. See Cron jobs.