---
title: "Change a number's routing"
method: PATCH
path: "/v1/numbers/{e164}"
---

# Change a number's routing

`PATCH /v1/numbers/{e164}`

## Request

- Base URL: `https://volai.cz`
- URL: `https://volai.cz/v1/numbers/{e164}`
- Auth: HTTP bearer

Changes the number's routing.

## Path parameters

- `e164` string, required

## Request body

- object
  - `routing` object, required: New inbound route for this number. The mode selects which destination fields apply.
    - `mode` 'agent' | 'forward' | 'sip' | 'none', required: agent routes to your voice agent; forward to a phone number; sip to a PBX; none disables the inbound destination.
    - `agentId` string: Owned agent id, required for mode agent.
    - `forwardTo` string: E.164 destination, required for mode forward. The forwarded leg is billed as an outbound call.
    - `sipUri` string: Foreign PBX address as sip:user@host[:port] for mode sip. Omit to use SIP registration with volai credentials.
    - `sipUsername` string: Optional digest username for a foreign PBX. Supply credentials as a pair when setting them; empty values clear authentication.
    - `sipPassword` string: Digest password for the foreign PBX. Omission preserves the saved password when the destination and username stay the same; an empty value clears it. Never returned in routing responses.

## Response `200`

Updated number

- object
  - `number` object, required
    - `e164` string, required
    - `routing` object, required
      - `mode` 'agent' | 'forward' | 'sip' | 'none', required
      - `agentId` string
      - `forwardTo` string
      - `sipUri` string
      - `sipUsername` string
      - `hasSipPassword` boolean, required
      - `sipTarget` 'elevenlabs' | 'engine'
    - `monthlyFeeHal` number, required
    - `boughtAt` number, required
    - `region` string, required
    - `regionLabel` string, required
    - `billingMonths` number, required

## Other responses

- `400`: Error codes: validation (request), invalid_sip_uri (request).
- `401`: Error codes: unauthorized (request).
- `402`: Error codes: insufficient_credit (account).
- `403`: Error codes: account_suspended (account).
- `404`: Error codes: not_found (account).
- `429`: Error codes: rate_limited (busy).
- `500`: Error codes: internal_error (service).
- `502`: Error codes: routing_failed (service), engine_unavailable (service), engine_readback_mismatch (service).

---

[API](https://skmtc.dev/volai/apis/volai-rest-api.md) · [All operations](https://skmtc.dev/volai/apis/volai-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/volai/apis/volai-rest-api/revisions/12029b05e2fa?raw)