Update a voice number
Changes what you have said about this number: the label you gave it, and what happens when a call arrives for it. Omit a field to leave it as it is.
The route replaces whatever was set before, because a number has exactly one answer at a time. A null route returns the number to your workspace's default inbound route, set with Update the voice settings. Type "reject" refuses calls whatever the default is. "trunk" needs a trunk_id: the trunk must be yours and must have inbound calling enabled. "forward" needs a forward_to, which has to be one of your verified caller IDs. That is checked when you set it, and again on every call it forwards, so a caller ID you later remove stops forwarding rather than carrying on.
Sequence management remains in the dashboard. A sequence route needs sequence_id and entry_node_id from an existing active publication in your workspace. Binding a sequence with recording commands or managed recording transfers requires organization preview access. Sequence management endpoints are not available through the public API; see the call sequences guide.
Only a number whose calls arrive here can carry a route. A number from another carrier is somewhere calls can be sent to, and that carrier routes the calls made to it, so inbound_configuration is refused on it. The label can be set on either.
Request
- Base URL: https://us1.platform.bird.com
- URL: https://us1.platform.bird.com/v1/voice/numbers/{number_id}
- Auth: one of:
- HTTP bearer
- API key in cookie bird_session
Headers
Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.
On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.
Two distinct 409 errors signal misuse:
- request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
- idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.
Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).
Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.
Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.
Request body
Example request
{
"name": "Support line",
"inbound_configuration": {
"route": {
"type": "reject"
}
}
}Response
The number as it now stands.
Example response
{
"id": "vnu_01krdgeqcxet5s7t44vh8rt9mg",
"phone_number": "+14155551234",
"country_code": "US",
"name": "Support line",
"provider": {
"type": "allocation",
"number_id": "nda_01krdgeqcxet5s7t44vh8rt9mg"
},
"inbound_configuration": {
"route": {
"type": "reject"
},
"forward_as_options": [
"dialed_number",
"calling_number"
]
}
}Changes
No recorded changes to this operation across all 2 revisions of this API.