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

# Assign Phone Number

> Choose which agent answers a phone number

Assigns one of your account's phone numbers to an agent, or unassigns it. It works
for every number on the account, Twilio and SIP alike, and is the same change as
picking an agent for the number in the dashboard.

The number answers with the agent's latest **deployed** version and follows the
agent's later deployments automatically — agents created or updated through the API
are deployed immediately. The assigned agent answers the number's inbound calls, and
is the agent [Dial](https://docs.voicy.co/api-reference/call-dial.md) uses for calls from the number when the
request names no other.

> [!NOTE]
>
> Changing a number's agent ends any A/B split configured on it. Buying, releasing
> and moving numbers between accounts stay in the [dashboard](https://app.voicy.co).

## Path Parameters

**phone\_number** `string` *required*

The number in E.164, URL-encoded: `+972771234567` is sent as `%2B972771234567`.

## Body Parameters

**agent\_id** `string | null` *required*

The agent to answer this number, or `null` to unassign it. The agent must be on your
account and deployed.

## Response

**phone\_number** `string`

The number in E.164.

**type** `string`

`twilio` or `sip`.

**agent\_id** `string | null`

The agent that answers the number, or `null`.

**agent\_name** `string | null`

That agent's name.

**status** `string`

`active` when an agent answers the number, `unassigned` otherwise.

```bash cURL theme={null}
curl -X PATCH https://api.voicy.co/functions/v1/phone-number-modify/%2B972771234567 \
  -H "Authorization: Bearer voicy_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "550e8400-e29b-41d4-a716-446655440000" }'
```

```javascript JavaScript theme={null}
const number = encodeURIComponent('+972771234567');
const phone = await (await fetch(`https://api.voicy.co/functions/v1/phone-number-modify/${number}`, {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer voicy_sk_live_xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ agent_id: '550e8400-e29b-41d4-a716-446655440000' }),
})).json();
```

```python Python theme={null}
import requests
from urllib.parse import quote
phone = requests.patch(
    f"https://api.voicy.co/functions/v1/phone-number-modify/{quote('+972771234567')}",
    headers={'Authorization': 'Bearer voicy_sk_live_xxx'},
    json={'agent_id': '550e8400-e29b-41d4-a716-446655440000'},
).json()
```

```json 200 OK theme={null}
{
  "phone_number": "+972771234567",
  "type": "sip",
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_name": "Appointment Booker",
  "status": "active"
}
```

```json 400 Bad Request theme={null}
{
  "status": "error",
  "message": "Cannot assign phone number to an undeployed agent. Deploy the agent first."
}
```

```json 404 Not Found theme={null}
{
  "status": "error",
  "message": "Phone number not found"
}
```


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