---
title: "Update a phone number"
method: PUT
path: "/v1/phone-number/{phoneNumberId}"
tags: ["Phone Number"]
---

# Update a phone number

`PUT /v1/phone-number/{phoneNumberId}`

## Request

- Base URL: `https://api.roark.ai`
- URL: `https://api.roark.ai/v1/phone-number/{phoneNumberId}`
- Auth: HTTP bearer

Relabels a number or changes which agent it is assigned to. A field left out is untouched; null clears it.

## Path parameters

- `phoneNumberId` string, uuid, required: Phone number ID

## Request body

- UpdatePhoneNumberInput: Input for relabelling or reassigning a phone number
  - `name` string, nullable: New label; null clears it, omit to leave it alone
  - `agentId` string, uuid, nullable: Agent to assign the number to; null unassigns, omit to leave it alone

## Response `200`

The updated phone number

- object
  - `data` PhoneNumberResponse, required: A phone number the project owns
    - `id` string, uuid, required: Phone number ID
    - `e164` string, required: The number in E.164 format
    - `name` string, nullable, required: Label the project gave the number
    - `localityCode` string, nullable, required: ISO 3166-2 code of the region the number is from, when the carrier gave one
    - `purchasedAt` string, required: When the number was bought (ISO 8601)
    - `rentNextChargeAt` string, required: When the next month of rent is due (ISO 8601)
    - `isFree` boolean, required: Whether the number sits inside the plan free allowance right now
    - `monthlyRentMicros` integer, required: What a month of this number costs in micro-dollars; 0 while it is free
    - `agentId` string, uuid, nullable, required: The agent the number is assigned to, if any

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `500`: Internal Server Error

## Changes

> 188 revisions in range; 1 not diffed.

- **2026-10-26** `0fb1c3b1940a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/phone-number/:phoneNumberId/put.md)

---

[API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) - [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roarkhq/apis/roark-analytics-api/revisions/efc3377249d1?raw)