---
title: "Update a phone number's display label"
method: PATCH
path: "/numbers/phones/{id}"
tags: ["Numbers"]
---

# Update a phone number's display label

`PATCH /numbers/phones/{id}`

## Request

- Base URL: `https://api.mobilerun.ai`
- URL: `https://api.mobilerun.ai/numbers/phones/{id}`
- Auth: HTTP bearer

Updates the display label. Omitting `label` leaves it unchanged; null or an empty string clears it.

## Path parameters

- `id` string, uuid, required

## Request body

- PatchPhoneInput
  - `label` string, nullable: User-defined display label — NFC-normalized, up to 100 GRAPHEMES (not UTF-16 code units; an emoji/flag may span several). Display-only, never used for routing.

## Response `200`

Number updated

- object
  - `data` PublicNumber, required
    - `id` string, uuid, required
    - `phoneNumber` string, nullable, required
    - `label` string, nullable, required
    - `state` 'awaiting_payment' | 'provisioning' | 'active' | 'cancel_scheduled' | 'expired' | 'failed', required
    - `failureReason` 'out_of_stock' | 'unknown' | 'null', nullable, required: Why setup failed. Null unless state is failed, and null when the failure has no classified reason. out_of_stock: no number is currently available for the requested country.
    - `countryCode` string, nullable, required
    - `lineCapabilities` LineCapabilities, required: What this line supports in principle, per channel. Use `actions` for what you can do right now.
      - `sms` ChannelCapabilities, required
        - `inbound` boolean, required: This line can receive on this channel.
        - `outbound` boolean, required: This line can send on this channel.
    - `currentPeriodEnd` string, date-time, nullable, required
    - `cancelAtPeriodEnd` boolean, required
    - `actions` PublicNumberActions, required: Actions currently available for this phone number.
      - `send` boolean, required: True when this number passes the send gate of POST /numbers/phones/{id}/messages: self-service sending is switched on and the number is active and able to send SMS. Daily and burst limits and recipient/body checks still apply; the send endpoint stays the final judge.
      - `cancel` boolean, required: True when DELETE /numbers/phones/{id} would currently succeed.
    - `createdAt` string, date-time, nullable, required
    - `updatedAt` string, date-time, nullable, required
    - `capabilities` string[], nullable, required: Deprecated: use `lineCapabilities`
    - `canSend` boolean, required: Deprecated: use `actions.send`
    - `purpose` string, nullable, required
    - `checkoutUrl` string, nullable, required
    - `cancellable` boolean, required: Deprecated: use `actions.cancel`

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `404`: Not Found
- `500`: Internal Server Error
- `503`: The phone-number service is unavailable. See `code` for details.

## Changes

- **2026-10-16** `4ad548c528a8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/droidrun/apis/droidrun-cloud/changes/numbers/phones/:id/patch.md)

---

[API](https://skmtc.dev/droidrun/apis/droidrun-cloud.md) - [All operations](https://skmtc.dev/droidrun/apis/droidrun-cloud/llms.txt) - [OpenAPI document](https://skmtc.dev/droidrun/apis/droidrun-cloud/revisions/1cc95586c933?raw)