---
title: "Update a phone number business username"
method: PATCH
path: "/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/businessUsername"
tags: ["WhatsApp Phone Numbers"]
---

# Update a phone number business username

`PATCH /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/businessUsername`

Requests a Business Username update for a WhatsApp business phone number.
The requested username may require Meta review before it becomes active. If Meta accepts or reserves the request for review, the response status is usually `reserved`; `pending_review` is kept only as a legacy compatibility value. If Meta returns an error, YCloud returns the error and does not change the stored Business Username state.

The `username` value is a plain username without `@`. YCloud trims leading and trailing whitespace and normalizes the value to lowercase before validation and submission.

## Path parameters

- `wabaId` string, required
- `phoneNumber` string, required

## Request body

- WhatsappBusinessUsernameUpdateRequest
  - `username` string, required — Business Username to request for the phone number. Send the plain username without `@`. YCloud trims leading and trailing whitespace and normalizes the value to lowercase before validation and submission. The value must be 3-35 characters, contain only English letters, numbers, periods, and underscores, and contain at least one English letter. It must not start or end with a period, contain consecutive periods, start with `www`, or end with common domain suffixes such as `.com`, `.org`, `.net`, `.int`, `.edu`, `.gov`, `.mil`, `.us`, `.in`, or `.html`.

## Response `200`

Successfully submitted the update request.

- WhatsappBusinessUsername — Business Username state for a WhatsApp business phone number.
  - `id` string — Phone number ID.
  - `wabaId` string — WhatsApp Business Account ID.
  - `phoneNumber` string — Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
  - `displayPhoneNumber` string — Display phone number.
  - `businessUsername` string — Active Business Username. The value is a plain username without `@`.
  - `businessUsernameStatus` 'not_set' | 'active' | 'pending_review' | 'reserved' — Business Username state for a WhatsApp business phone number. - `not_set`: No active or pending Business Username exists. - `active`: A Business Username is active. - `reserved`: A requested Business Username is reserved by Meta and may still be under review. - `pending_review`: Legacy compatibility value for an under-review request. New writes use `reserved`. If an active username exists while a new request is reserved or under review, `businessUsernameStatus` is `reserved`, `businessUsername` contains the still-active username, and `requestedBusinessUsername` contains the requested username.
  - `requestedBusinessUsername` string — Last requested Business Username that is still under review. This value can coexist with an active `businessUsername` while the new request is pending.
  - `businessUsernameUpdatedAt` string, date-time — The time when the Business Username state was last updated.

## Other responses

- `400` — Bad request. Invalid request parameters.
- `404` — The requested resource does not exist.

---

[API](https://skmtc.dev/ycloud/apis/ycloud-api.md) · [All operations](https://skmtc.dev/ycloud/apis/ycloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ycloud/ycloud-api/revisions/4e13d3ca9df8/schema)