Skip to navigation
API Referencenumbers

Update Number

Update a number. Only the fields you send are changed.

externalId: your own identifier for the number. Send a string to set it, null to clear it, or omit it to leave it unchanged. Must be unique within your account (409 otherwise). Works on any number type. The tag is echoed on every number response and webhook payload and usable for lookup as GET /v1/numbers/ext:<externalId> or GET /v1/numbers?externalId=<externalId>.

expiresAt: hard end date for the number (ISO 8601). After it passes the number is released automatically and a number.released webhook is sent. Send a datetime to set or move it (at least 5 minutes out), null to clear it, or omit it to leave it unchanged.

Fields this endpoint does not support are rejected with 422, never silently ignored.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

number_idstringRequired

Headers

X-Sub-Account-IdstringOptional

Request

This endpoint expects an object.
externalIdstring or nullOptional
expiresAtdatetime or nullOptional

Response

Successful Response
idstring
phoneNumberstring
countrystring
statusstring
createdAtdatetime
typestringOptionalDefaults to sms
agentIdstring or nullOptional
outboundSmsenumOptionalDefaults to enabled

Outbound SMS readiness for this exact number: activating means campaign attachment is in progress; enabled means confirmed; registration_required means registration or attachment is still needed. Check the number and registration in the same account/sub-account scope. See /sms-registration.

Allowed values:
voiceRoutingobject or nullOptional

Where this number’s inbound calls go. Set it with PATCH /v1/numbers/{number_id}/voice-routing.

sipTrunkingEligiblebooleanOptionalDefaults to false

True when this number can be routed to a SIP trunk via PATCH /v1/numbers/{number_id}/voice-routing.

inboundCallsEnabledbooleanOptionalDefaults to true
readReceiptsEnabledbooleanOptionalDefaults to true
whatsappEnabledbooleanOptionalDefaults to false
dailyNewContactsobject or nullOptional
externalIdstring or nullOptional
rcsFallbackForAliasstring or nullOptional
expiresAtstring or nullOptional
purchasedAtdatetime or nullOptional
renewsAtstring or nullOptional
Scheduled renewal of this number's monthly fee, ISO 8601 UTC. Null when no renewal is scheduled or its date is not known.

Errors

422
Unprocessable Entity Error