> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verbeo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update phone number

> Change the assistants a number answers and dials with, its dial rate, or its inbound call webhook. Send only the fields you are changing.

Updates a phone number in place. Every field is optional and anything you leave out is untouched.

The number itself, its label (`nickname`), its carrier and its credentials cannot be changed: [delete the number](/api-reference/phone-numbers/delete) and add it again. Fields not listed below are ignored.

## Path parameters

<ParamField path="id" type="string" required>
  UUID of the phone number.
</ParamField>

## Body

At least one field is required.

<ParamField body="inbound_agent_id" type="string | null">
  UUID of the assistant that answers calls to this number. `null` unassigns it: calls to the number are no longer answered.
</ParamField>

<ParamField body="outbound_agent_id" type="string | null">
  UUID of the assistant that places calls from this number when a call names none. `null` unassigns it.
</ParamField>

<ParamField body="max_cps" type="number">
  How many calls per second Verbeo dials from this number, at least `0.1`. Keep it at or below what your carrier allows on the trunk.
</ParamField>

<ParamField body="inbound_webhook_url" type="string | null">
  The [inbound call webhook](/guides/inbound-call-webhook): an `https://` URL, up to 2,048 characters. `null` or an empty string switches it off. Only a SIP-trunk number (`provider: "livekit_sip"`) has one.
</ParamField>

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.verbeo.ai/v1/phone-number/7d9f3b52-4c1e-4a8e-9b1a-2f6c0d4e8a11" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "outbound_agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "inbound_webhook_url": "https://api.example.com/verbeo/inbound"
    }'
  ```

  ```javascript Node.js theme={null}
  const id = "7d9f3b52-4c1e-4a8e-9b1a-2f6c0d4e8a11";
  const res = await fetch(`https://api.verbeo.ai/v1/phone-number/${id}`, {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${process.env.VERBEO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      outbound_agent_id: "550e8400-e29b-41d4-a716-446655440000",
      inbound_webhook_url: "https://api.example.com/verbeo/inbound",
    }),
  });
  const { data: number } = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  number_id = "7d9f3b52-4c1e-4a8e-9b1a-2f6c0d4e8a11"
  number = requests.put(
      f"https://api.verbeo.ai/v1/phone-number/{number_id}",
      headers={"Authorization": f"Bearer {os.environ['VERBEO_API_KEY']}"},
      json={
          "outbound_agent_id": "550e8400-e29b-41d4-a716-446655440000",
          "inbound_webhook_url": "https://api.example.com/verbeo/inbound",
      },
  ).json()["data"]
  ```
</CodeGroup>

## Response

`200 OK` with the updated [phone number object](/api-reference/phone-numbers/overview#the-phone-number-object).

```json theme={null}
{
  "success": true,
  "data": {
    "id": "7d9f3b52-4c1e-4a8e-9b1a-2f6c0d4e8a11",
    "phone_number": "+14155550123",
    "provider": "livekit_sip",
    "max_cps": 1,
    "inbound_agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "outbound_agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "inbound_webhook_url": "https://api.example.com/verbeo/inbound",
    "updated_at": "2026-01-23T09:12:00.456789+00:00",
    "inbound_agent_name": "Customer Support",
    "outbound_agent_name": "Customer Support",
    "…": "the rest of the object"
  }
}
```

## Errors

| Code | Status | When |
| - | - | - |
| `VALIDATION_FAILED` | 422 | An empty body; an assistant id that is not an assistant of your workspace; `max_cps` below `0.1`; a webhook URL that is not `https://`; or a webhook URL on a number imported from Twilio. |
| `NOT_FOUND` | 404 | No such phone number, or it belongs to another workspace. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.