# Update a phone number (/docs/api/routing/phone-numbers/updatePhoneNumber)

> For the complete documentation index, see [llms.txt](https://docs.tandemcx.ai/llms.txt). Any page on this site can be fetched as Markdown by appending `.md` to its URL.

`PUT /v1/routing/phone-numbers/{phoneNumberId}`

Update a phone number

Change a phone number's label, route target, or variables. Only the fields you send are modified — omit a field to leave it as it is, and send an explicit null to clear it. Clearing the target unroutes the number, so inbound calls to it are no longer answered. The number itself cannot be changed after purchase; a request that includes phoneNumber is rejected.

## Request

**Base URL:** `https://api.tandemcx.ai`

**Authentication:** `Authorization: Bearer <token>` — A Tandem bearer token. Requests are scoped to the organization the token belongs to; no organization header is required.

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `phoneNumberId` | string | Yes | The phone number's unique ID. |

### Body (`application/json`) — required

Every field is optional. An omitted field is left unchanged. A null clears the field — note that label is not nullable, because a phone number must always have one.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | No | — |
| `workflowId` | string \| null | No | Deprecated. Set target instead; a workflow target is mirrored into this field automatically. Still accepted for older integrations. |
| `target` | one of: one of: object \| object \| null | No | The new route. Null unroutes the number, so inbound calls are no longer answered. |
| `variables` | object \| null | No | Replaces the number's variables. Null removes all of them. At most 50 variables, with names up to 128 characters and values up to 2,000 characters. All names and values together may not exceed 64 KB (UTF-8 bytes). A request over a limit is rejected with a 400. |
| `recordCalls` | enum: `inherit` \| `always` \| `never` | No | Whether calls on this number are recorded. inherit follows the organization's default; always and never override it. Absent on a number that has never set one, which behaves as inherit. |

## Responses

### 200 — The updated phone number.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The phone number's unique ID. |
| `label` | string | Yes | Friendly name for the number, up to 200 characters. |
| `phoneNumber` | string | Yes | The number in E.164 format. |
| `workflowId` | string | No | Legacy mirror of a workflow route target, maintained for older integrations. Present only while the number routes to a workflow. Prefer target. |
| `target` | one of: object \| object | No | Where an inbound call to this number is routed. |
| `variables` | object | No | Values made available to the workflow or agent run this number starts. At most 50 variables, with names up to 128 characters and values up to 2,000 characters. All names and values together may not exceed 64 KB (UTF-8 bytes). |
| `recordCalls` | enum: `inherit` \| `always` \| `never` | No | Whether calls on this number are recorded. inherit follows the organization's default; always and never override it. Absent on a number that has never set one, which behaves as inherit. |
| `smsCapability` | enum: `enabled` \| `disabled` \| `pending` | Yes | Whether the number can use a messaging channel. A newly purchased number starts as pending until the carrier confirms it. |
| `mmsCapability` | enum: `enabled` \| `disabled` \| `pending` | Yes | Whether the number can use a messaging channel. A newly purchased number starts as pending until the carrier confirms it. |
| `createdAt` | string (date-time) | Yes | — |
| `updatedAt` | string (date-time) | Yes | — |

### 400 — The request was malformed.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | No | — |
| `error.code` | string | No | — |
| `error.message` | string | No | — |

### 401 — Missing, malformed, or expired bearer token.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | No | — |
| `error.code` | string | No | — |
| `error.message` | string | No | — |

### 404 — The resource does not exist.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | No | — |
| `error.code` | string | No | — |
| `error.message` | string | No | — |