---
title: "Update Number"
method: PATCH
path: "/v1/numbers/{number_id}"
tags: ["numbers"]
---

# Update Number

`PATCH /v1/numbers/{number_id}`

Tag a number with your own identifier.

Send null to clear it. externalId must be unique within your account
(409 otherwise). Works on any number type. The tag is echoed on every
number response and webhook payload and usable for lookup as
GET /v1/numbers/ext:<externalId> or GET /v1/numbers?externalId=<externalId>.

## Path parameters

- `number_id` string, required

## Request body

- UpdateNumberRequest — PATCH /v1/numbers/{id}. externalId is your own identifier for the number, unique within your account, usable in place of our id as `ext:<externalId>` and echoed on every number response and webhook. The field is required: a string sets it, null clears it.
  - `externalId` string, nullable, required

## Response `200`

Successful Response

- PhoneNumberResponse
  - `id` string, required
  - `phoneNumber` string, required
  - `country` string, required
  - `status` string, required
  - `type` string
  - `agentId` string, nullable
  - `outboundSms` 'enabled' | 'activating' | 'registration_required'
  - `inboundCallsEnabled` boolean
  - `readReceiptsEnabled` boolean
  - `whatsappEnabled` boolean
  - `dailyNewContacts` DailyNewContactsUsage
    - `used` integer, required
    - `limit` integer, nullable
  - `externalId` string, nullable
  - `createdAt` string, date-time, required
  - `purchasedAt` string, date-time, nullable

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-26** `66bd9854f8b2` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/agentphone/apis/agentphone-api/changes/v1/numbers/:number_id/patch.md)

---

[API](https://skmtc.dev/agentphone/apis/agentphone-api.md) · [All operations](https://skmtc.dev/agentphone/apis/agentphone-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentphone/apis/agentphone-api/revisions/e22d81f91f2d?raw)