---
title: "Update phone number"
method: PATCH
path: "/v1/phone-numbers/{phoneNumberId}"
---

# Update phone number

`PATCH /v1/phone-numbers/{phoneNumberId}`

## Request

- Base URL: `https://api.zavu.dev`
- URL: `https://api.zavu.dev/v1/phone-numbers/{phoneNumberId}`
- Auth: HTTP bearer

Update a phone number's name or sender assignment.

## Path parameters

- `phoneNumberId` string, required

## Request body

- PhoneNumberUpdateRequest
  - `name` string, nullable: Custom name for the phone number. Set to null to clear.
  - `senderId` string, nullable: Sender ID to assign the phone number to. Set to null to unassign. A number under regulatory review is recorded now and connected to the sender when approved; a rejected number is refused.

## Response `200`

Phone number updated.

- PhoneNumberResponse
  - `phoneNumber` OwnedPhoneNumber, required
    - `id` string, required
    - `phoneNumber` string, required
    - `name` string: Optional custom name for the phone number.
    - `capabilities` string[], required
    - `status` 'active' | 'suspended' | 'pending' | 'releasing' | 'released', required: Billing state of an owned number, separate from `regulatoryStatus`. `pending` is legacy and is not written to numbers today. The SDKs carry `active`, `suspended` and `pending` only; `releasing` and `released` are returned by the REST API until their next release.
    - `senderId` string: Sender ID if the phone number is assigned to a sender.
    - `pricing` OwnedPhoneNumberPricing, required
      - `monthlyPrice` number: Monthly price in USD.
      - `upfrontCost` number: One-time purchase cost in cents.
      - `monthlyCost` number: Monthly cost in cents.
      - `isFreeNumber` boolean: Whether this is a free number.
    - `regulatoryStatus` 'approved' | 'pending_review' | 'rejected', required: Regulatory review state. Numbers that need no review are `approved` immediately. A number bought with regulatory information is owned and billed from purchase and starts `pending_review`; it cannot send messages or place calls until this is `approved`. The state is re-checked every 6 hours: poll `GET /v1/phone-numbers/{phoneNumberId}` to follow it. Assign it to a sender with `PATCH /v1/phone-numbers/{phoneNumberId}` (`senderId`) before or after approval. A number assigned while under review is recorded and connected to that sender when it is approved; the connection is retried until it succeeds. A sender created over the API is set up for SMS as part of the assignment. `rejected` means review refused the information: the number cannot be assigned to a sender. A number that stays `pending_review` may be waiting on information the API cannot supply; contact support.
    - `nextRenewalDate` string, date-time
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time

## Other responses

- `400`: Invalid request, or the number was rejected in regulatory review and cannot be assigned to a sender.
- `401`: Unauthorized.
- `404`: Phone number or sender not found.
- `503`: The sender could not be set up for SMS right now. Nothing was assigned; retry.

---

[API](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api.md) - [All operations](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/revisions/75bc777b0ffb?raw)