---
title: "Set business username"
method: POST
path: "/v1/whatsapp/business-profile/username"
tags: ["WhatsApp"]
---

# Set business username

`POST /v1/whatsapp/business-profile/username`

Claim or transfer a WhatsApp Business username for the account.

Username rules: 3-35 characters, letters/digits/period/underscore only, must contain at least one letter,
no leading or trailing periods, no consecutive periods, no `www` prefix, no domain TLD suffix (e.g. `.com`).

If the desired username is currently held by another account, pass `transferAction: "force_transfer"` to
request a transfer. On failure the API returns a standard error envelope with one of these codes:
`whatsapp_username_unavailable` (already taken and transfer not requested),
`whatsapp_username_ineligible` (account not eligible to claim a username), or
`whatsapp_username_transfer_required` (username is held elsewhere; retry with `force_transfer`).

## Request body

- object
  - `accountId` string, required — WhatsApp social account ID
  - `username` string, required — Desired username. Letters, digits, period, and underscore only. Must contain at least one letter. No leading, trailing, or consecutive periods. No www prefix. No domain TLD suffix.
  - `transferAction` 'none' | 'force_transfer' — Pass `force_transfer` to request a transfer if the username is held by another account

## Response `200`

Username claimed successfully

- object
  - `success` boolean
  - `username` string
  - `status` 'approved' | 'reserved' | 'none'

## Other responses

- `400` — Validation error or username unavailable (see error code in response)
- `401` — Unauthorized
- `404` — WhatsApp account not found

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/revisions/15e893e69e8c/schema)