> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Business usernames

> Reserve and manage WhatsApp business usernames through the Meta proxy API

Use the Username API to reserve, read, change, or delete the username for a WhatsApp business phone number.

Base URL:

```txt theme={null}
https://api.kapso.ai/meta/whatsapp/v24.0
```

## Get current username

```bash theme={null}
curl 'https://api.kapso.ai/meta/whatsapp/v24.0/647015955153740/username' \
  -H 'X-API-Key: YOUR_API_KEY'
```

```json theme={null}
{
  "username": "kapso_support",
  "status": "reserved"
}
```

`username` is omitted when the phone number has no username.

## Get reserved suggestions

```bash theme={null}
curl 'https://api.kapso.ai/meta/whatsapp/v24.0/647015955153740/username_suggestions' \
  -H 'X-API-Key: YOUR_API_KEY'
```

```json theme={null}
{
  "data": [
    {
      "username_suggestions": ["kapso_support", "kapso_ai"]
    }
  ]
}
```

## Claim or change username

```bash theme={null}
curl -X POST 'https://api.kapso.ai/meta/whatsapp/v24.0/647015955153740/username' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "kapso_support",
    "transfer_action": "none"
  }'
```

`transfer_action` is optional:

* `none`: default. Fail if the username belongs to another phone number in the same business portfolio.
* `force_transfer`: move the username from another phone number in the same business portfolio.

Success response:

```json theme={null}
{
  "status": "reserved"
}
```

## Delete username

```bash theme={null}
curl -X DELETE 'https://api.kapso.ai/meta/whatsapp/v24.0/647015955153740/username' \
  -H 'X-API-Key: YOUR_API_KEY'
```

```json theme={null}
{
  "success": true
}
```

## Statuses

* `reserved`: approved but not visible until usernames are available in the user's region.
* `approved`: visible to WhatsApp users.
* `deleted`: username was removed.

Kapso records username state when requests go through the Meta proxy. Kapso also processes Meta `business_username_updates` webhooks and updates the visible username on the WhatsApp configuration.

## Format

Usernames:

* are 3-35 characters
* use English letters, digits, periods, and underscores
* contain at least one English letter
* do not start or end with a period
* do not contain consecutive periods
* do not start with `www`
* do not end with a domain suffix like `.com`, `.org`, `.net`, `.io`, or `.ai`

Case is ignored for comparisons. Periods and underscores are distinct.

## Common errors

| Code     | Meaning                                                             |
| -------- | ------------------------------------------------------------------- |
| `10`     | Token or business asset permissions are missing                     |
| `33`     | Phone number or WABA access is invalid                              |
| `100`    | Username format is invalid                                          |
| `147001` | Username is not available                                           |
| `147002` | Account is not eligible to request a username                       |
| `147003` | Facebook account must be linked                                     |
| `147004` | Instagram account must be linked                                    |
| `147005` | Use `force_transfer` to move the username inside the same portfolio |
| `133010` | Phone number is not registered for API use                          |

## Related docs

* [Business-scoped user IDs](/docs/whatsapp/business-scoped-user-ids)
* [API overview](/api-reference/whatsapp-api-overview)