Sign in
Voice

Enable phone calling on a number

Turns on regular phone (PSTN) calling for one of your numbers and configures how inbound calls are handled. Inbound calls route to forwardTo: your own AI voice agent (Vapi/Retell), a phone, or a SIP endpoint. Optional extras: voicemail, business-hours windows, an IVR menu, a caller blocklist, recording, and transcription. A number can also be voice-enabled with no forward (outbound-only).

Idempotent, and doubles as the settings update: only fields present in the body are written. Omitting forwardTo preserves the current destination; sending an empty string clears it.

post/v1/phone-numbers/{id}/voice

Path parameters

idstring required

Phone number record ID (from GET /v1/phone-numbers).

Request body

forwardTostring

tel:+E164, sip:..., or wss://... destination for inbound calls. Empty string clears the forward (outbound-only); omitted preserves the current one.

recordingEnabledboolean
transcriptionEnabledboolean
transcriptionLanguage'auto' | 'en' | 'es'
voicemailEnabledboolean

Voicemail is taken when there's no live destination. Default on.

voicemailGreetingstring

Custom spoken greeting; empty string restores the default.

businessHoursEnabledboolean

Outside the windows, inbound skips the forward and goes to voicemail. Off = 24/7.

businessHoursTimezonestring

IANA timezone the windows are evaluated in.

blockedCallersstring[]

E.164 numbers rejected before answer. Replaces the whole list; bare 10-digit values are normalized as US numbers.

forwardCallerId'business' | 'caller'

Caller ID on the forwarded leg: your number (business) or the original caller's (caller).

ivrEnabledboolean

IVR menu (supersedes the plain forward within business hours).

ivrPromptstring

Response

Voice enabled; the full effective voice config is echoed back.

enabledboolean
phoneNumberstring
pstnForwardTostring nullable
recordingEnabledboolean
transcriptionEnabledboolean
transcriptionLanguage'auto' | 'en' | 'es'
voicemailEnabledboolean
voicemailGreetingstring nullable
businessHoursEnabledboolean
businessHoursTimezonestring nullable
blockedCallersstring[]
forwardCallerId'business' | 'caller'
ivrEnabledboolean
ivrPromptstring nullable

Changes

Changed in 1 of the 33 revisions of this API.1