REST APIPhone Numbers

Update a phone number

View as Markdown

Update a number’s properties. Send any subset of the fields below — at least one is required; omitted fields are left unchanged. A new inboundInstruction takes effect on the next inbound call; in-progress calls are unaffected.

Authentication

AuthorizationBearer

Your Dial API key, sent as Authorization: Bearer sk_live_...

Path parameters

idstringRequired

Request

This endpoint expects an object.
inboundInstructionstringOptional

New inbound voice-agent system prompt for this number.

inboundVoiceGenderenumOptional

Voice gender for the AI agent on inbound calls to this number. Send null to clear it (the voice reverts to the default, female). Takes effect on the next inbound call.

Allowed values:
inboundLanguagestring or nullOptional

BCP-47 language tag for the AI voice agent on inbound calls to this number. Send null to clear it — the language is then detected from the caller’s country prefix on each call, with the agent handling both that language and en-US. Takes effect on the next inbound call.

nicknamestring or nullOptional

Human-readable label for the number. Trimmed; at most 100 characters. Send null or an empty string to clear it.

maxCallDurationSecondsinteger or nullOptional60-3600
Cap on the length of calls on this number, in seconds, for both inbound calls to the number and outbound calls placed from it. The effective cap on a call is the first one set in priority order — the per-call cap, then this number cap, then the account cap — falling back to the global default. This number cap overrides the account cap (raising or lowering the limit) but is itself overridden by a per-call cap. Must be between 60 and 3600 seconds (1 minute to 1 hour); a value outside that range returns 400. Send null to clear it (falls back to the account cap or global default). When a cap is active, Dial automatically injects a warning to the agent ~40 seconds before the hard cut, prompting it to wrap up naturally.

Response

Updated.
numberobject

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error