<!-- Source: https://docs.vinsi.ai/api-docs/phone-number-update -->
# Update Phone Number

Assign an agent to a phone number (or send agentId as null to unassign it) and set its fallback number. Assigning an agent also updates carrier and LiveKit routing so inbound calls reach that agent. The agent must belong to your organization. Returns the updated phone number; warnings lists any routing steps that did not complete.

```http
PUT https://dashboard.vinsi.ai/api/phone-numbers/{phoneNumberId}
```

## Authentication

Send your API key in the `x-api-key` header. Create keys in the VINSI dashboard under Settings → API Keys.

## Headers

| Name | Type | Required |
|---|---|---|
| Content-Type | string | yes (application/json) |
| x-api-key | string | yes |

## Path parameters

| Name | Example |
|---|---|
| phoneNumberId | phn_1757964000123_k2j4h5g6f |

## Example request body

```json
{
  "agentId": "cmexampleagent000000000001",
  "fallbackNumber": "+15555550100"
}
```

## Example request

```bash
curl -X PUT 'https://dashboard.vinsi.ai/api/phone-numbers/phn_1757964000123_k2j4h5g6f' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"agentId":"cmexampleagent000000000001","fallbackNumber":"+15555550100"}'
```

## Example response

```json
{
  "id": "phn_1757964000123_k2j4h5g6f",
  "phoneNumber": "+15555550199",
  "friendlyName": "Main Line",
  "providerId": "2468013579246801357",
  "provider": "telnyx",
  "capabilities": "{\"voice\":true,\"sms\":true}",
  "agentId": "cmexampleagent000000000001",
  "fallbackNumber": "+15555550100",
  "isActive": true,
  "userId": "cmexampleuser0000000000001",
  "organizationId": "cmexampleorg00000000000001",
  "createdAt": "2026-09-01T18:00:00.000Z",
  "updatedAt": "2026-09-10T21:14:00.000Z",
  "SIPUserName": null,
  "SIPPassword": null,
  "SIPTerminationURI": null,
  "livekitTrunkConfigured": true,
  "trunkName": "Main Line",
  "livekitTrunkId": "ST_exampleTrunk01",
  "livekitOutboundTrunkId": null,
  "livekitOutboundConfigured": null,
  "stripeSubscriptionId": null,
  "routingMode": "agent",
  "routingDeskPhoneId": null,
  "voicemailEnabled": false,
  "voicemailPin": null,
  "huntGroupId": null,
  "queueId": null,
  "queuePriority": null,
  "livekitCluster": "vinsi-do",
  "agent": {
    "id": "cmexampleagent000000000001",
    "name": "Front Desk Agent",
    "isAfterHoursFallback": false,
    "routeOutboundVia": "telnyx"
  },
  "warnings": []
}
```