# Numbers

> Connect and manage WhatsApp Business numbers. A number is connected only after the WABA is subscribed to WhaBuzz, the number is registered, and a webhook endpoint has passed its verify ping.

Canonical: https://docs.whabuzz.com/api/numbers/

Connect and manage WhatsApp Business numbers. A number is `connected` only after the WABA is subscribed to WhaBuzz, the number is registered, and a webhook endpoint has passed its verify ping.

Base URL `https://api.whabuzz.com`. Every request needs `Authorization: Bearer <key>` unless the operation says otherwise; see [Authentication](https://docs.whabuzz.com/authentication.md). Errors follow the [two-source contract](https://docs.whabuzz.com/errors.md).

Operations on this page:

- [`GET /v1/numbers`](#listNumbers): List numbers
- [`GET /v1/numbers/{phone_number_id}`](#getNumber): Get a number
- [`POST /v1/numbers/embedded-signup`](#completeEmbeddedSignup): Finish Embedded Signup with the code from Meta's popup
- [`POST /v1/numbers/connect`](#connectExisting): Connect an existing WABA with a business system-user token
- [`POST /v1/numbers/migrate`](#migrateNumber): Start migrating a number into one of your WABAs
- [`POST /v1/numbers/{phone_number_id}/register`](#registerNumber): Register the number with Cloud API
- [`POST /v1/numbers/{phone_number_id}/deregister`](#deregisterNumber): Deregister the number
- [`POST /v1/numbers/{phone_number_id}/request-code`](#requestVerificationCode): Request an SMS or voice verification code
- [`POST /v1/numbers/{phone_number_id}/verify-code`](#verifyCode): Verify the code
- [`POST /v1/numbers/{phone_number_id}/two-step`](#setTwoStepPin): Set or change the two-step verification PIN
- [`POST /v1/numbers/{phone_number_id}/subscribe`](#resubscribeWaba): Re-subscribe the number's WABA to WhaBuzz (repair)
- [`GET /v1/numbers/{phone_number_id}/business-profile`](#getBusinessProfile): Get the WhatsApp business profile
- [`POST /v1/numbers/{phone_number_id}/business-profile`](#updateBusinessProfile): Update the WhatsApp business profile

## List numbers {#listNumbers}

`GET /v1/numbers`

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `listNumbers`.

cURL:

```bash
curl -X GET "https://api.whabuzz.com/v1/numbers" \
  -H "Authorization: Bearer $WHABUZZ_KEY"
```

**Responses**

**200** Numbers

```json
{
  "data": [
    {
      "phone_number_id": "1013622581841046",
      "display_phone_number": "+1 469-231-1132",
      "verified_name": "WhaBuzz Demo",
      "waba_id": "26059971920328384",
      "connection_state": "connected",
      "connection_detail": null,
      "quality_rating": "GREEN",
      "messaging_limit_tier": "TIER_250",
      "throughput_level": "STANDARD"
    }
  ]
}
```

## Get a number {#getNumber}

`GET /v1/numbers/{phone_number_id}`

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `getNumber`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `phone_number_id` | path | string | yes |  |
| `refresh` | query | boolean | no | Re-read the number from Meta first (stored as `meta_snapshot`). |

cURL:

```bash
curl -X GET "https://api.whabuzz.com/v1/numbers/$PHONE_NUMBER_ID" \
  -H "Authorization: Bearer $WHABUZZ_KEY"
```

**Responses**

**200** Number

connected:

```json
{
  "phone_number_id": "1013622581841046",
  "display_phone_number": "+1 469-231-1132",
  "verified_name": "WhaBuzz Demo",
  "waba_id": "26059971920328384",
  "connection_state": "connected",
  "connection_detail": null,
  "quality_rating": "GREEN",
  "messaging_limit_tier": "TIER_250",
  "throughput_level": "STANDARD",
  "name_status": "APPROVED",
  "registered_at": "2026-10-02T06:00:00Z",
  "last_event_at": "2026-10-16T05:12:03Z"
}
```

pending:

```json
{
  "phone_number_id": "1013622581841046",
  "display_phone_number": "+1 469-231-1132",
  "waba_id": "26059971920328384",
  "connection_state": "pending",
  "connection_detail": "no_verified_endpoint"
}
```

**Common errors.** Shape and meanings are on the [Errors page](https://docs.whabuzz.com/errors.md).

| HTTP | WhaBuzz code | Meaning |
|---|---|---|
| 404 | `not_found` | Not found |

## Finish Embedded Signup with the code from Meta's popup {#completeEmbeddedSignup}

`POST /v1/numbers/embedded-signup`

Exchanges the code, checks the token, subscribes the WABA to WhaBuzz, registers the number and stores Meta's view of it.

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `completeEmbeddedSignup`.

**Request body** (`application/json`, required)

| Field | Type | Required | Description |
|---|---|---|---|
| `code` | string | yes |  |
| `waba_id` | string | yes |  |
| `phone_number_id` | string | yes |  |
| `pin` | string | no | Two-step PIN to register with. Generated when omitted. Pattern `^[0-9]{6}$`. |

Request example:

```json
{
  "code": "AQBx…",
  "waba_id": "26059971920328384",
  "phone_number_id": "1013622581841046"
}
```

cURL:

```bash
curl -X POST "https://api.whabuzz.com/v1/numbers/embedded-signup" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "AQBx…",
  "waba_id": "26059971920328384",
  "phone_number_id": "1013622581841046"
}'
```

**Responses**

**200** Number stored. `connection_state` tells you what is left.

```json
{
  "phone_number_id": "1013622581841046",
  "display_phone_number": "+1 469-231-1132",
  "waba_id": "26059971920328384",
  "connection_state": "pending",
  "connection_detail": "no_verified_endpoint"
}
```

**Common errors.** Shape and meanings are on the [Errors page](https://docs.whabuzz.com/errors.md).

| HTTP | WhaBuzz code | Meaning |
|---|---|---|
| 400 | `131030` | Meta's error, passed through with Meta's HTTP status |

## Connect an existing WABA with a business system-user token {#connectExisting}

`POST /v1/numbers/connect`

For businesses that already have a WABA. The token must belong to WhaBuzz's Meta app
(`debug_token` app id), carry `whatsapp_business_management` and `whatsapp_business_messaging`,
and list `waba_id` in its granular scopes. WhaBuzz subscribes the WABA and imports its numbers.

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `connectExisting`.

**Request body** (`application/json`, required)

| Field | Type | Required | Description |
|---|---|---|---|
| `waba_id` | string | yes |  |
| `access_token` | string | no |  |
| `code` | string | no | Alternative to access_token: an Embedded Signup code. |

Request example:

```json
{
  "waba_id": "1496378315413646",
  "access_token": "EAAG…"
}
```

cURL:

```bash
curl -X POST "https://api.whabuzz.com/v1/numbers/connect" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "waba_id": "1496378315413646",
  "access_token": "EAAG…"
}'
```

**Responses**

**200** Imported numbers

```json
{
  "waba_id": "1496378315413646",
  "numbers": [
    {
      "phone_number_id": "301234567890123",
      "display_phone_number": "+91 95158 47444",
      "connection_state": "pending",
      "connection_detail": "not_registered"
    }
  ]
}
```

**400** Token checks failed, or Meta error

whabuzz:

```json
{
  "source": "whabuzz",
  "error": {
    "code": "invalid_request",
    "message": "Token is not scoped to WABA 1496378315413646",
    "details": {
      "granular_scopes": [
        "whatsapp_business_messaging"
      ]
    }
  },
  "request_id": "req_01JAB3M0P4Q7R2S5T8V1W4X7Y0"
}
```

Meta 190 passed through (HTTP 401 from Meta becomes 401 here):

```json
{
  "source": "meta",
  "error": {
    "message": "Error validating access token: Session has expired.",
    "type": "OAuthException",
    "code": 190,
    "error_subcode": 463,
    "fbtrace_id": "C3d4E5f6G7h8I9j0"
  }
}
```

## Start migrating a number into one of your WABAs {#migrateNumber}

`POST /v1/numbers/migrate`

Wraps `POST /{waba_id}/phone_numbers` with `migrate_phone_number=true`. Follow with request-code, verify-code and register.

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `migrateNumber`.

**Request body** (`application/json`, required)

| Field | Type | Required | Description |
|---|---|---|---|
| `waba_id` | string | yes |  |
| `cc` | string | yes |  |
| `phone_number` | string | yes |  |

Request example:

```json
{
  "waba_id": "1496378315413646",
  "cc": "91",
  "phone_number": "9515847444"
}
```

cURL:

```bash
curl -X POST "https://api.whabuzz.com/v1/numbers/migrate" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "waba_id": "1496378315413646",
  "cc": "91",
  "phone_number": "9515847444"
}'
```

**Responses**

**200** Meta's response verbatim

```json
{
  "id": "301234567890123"
}
```

**Common errors.** Shape and meanings are on the [Errors page](https://docs.whabuzz.com/errors.md).

| HTTP | WhaBuzz code | Meaning |
|---|---|---|
| 400 | `131030` | Meta's error, passed through with Meta's HTTP status |

## Register the number with Cloud API {#registerNumber}

`POST /v1/numbers/{phone_number_id}/register`

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `registerNumber`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `phone_number_id` | path | string | yes |  |

**Request body** (`application/json`)

| Field | Type | Required | Description |
|---|---|---|---|
| `pin` | string | no | Pattern `^[0-9]{6}$`. |

Request example:

```json
{
  "pin": "482913"
}
```

cURL:

```bash
curl -X POST "https://api.whabuzz.com/v1/numbers/$PHONE_NUMBER_ID/register" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "pin": "482913"
}'
```

**Responses**

**200** Meta's response verbatim

```json
{
  "success": true
}
```

**Common errors.** Shape and meanings are on the [Errors page](https://docs.whabuzz.com/errors.md).

| HTTP | WhaBuzz code | Meaning |
|---|---|---|
| 400 | `131030` | Meta's error, passed through with Meta's HTTP status |

## Deregister the number {#deregisterNumber}

`POST /v1/numbers/{phone_number_id}/deregister`

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `deregisterNumber`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `phone_number_id` | path | string | yes |  |

cURL:

```bash
curl -X POST "https://api.whabuzz.com/v1/numbers/$PHONE_NUMBER_ID/deregister" \
  -H "Authorization: Bearer $WHABUZZ_KEY"
```

**Responses**

**200** Meta's response verbatim

```json
{
  "success": true
}
```

## Request an SMS or voice verification code {#requestVerificationCode}

`POST /v1/numbers/{phone_number_id}/request-code`

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `requestVerificationCode`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `phone_number_id` | path | string | yes |  |

**Request body** (`application/json`, required)

| Field | Type | Required | Description |
|---|---|---|---|
| `code_method` | `SMS` or `VOICE` | yes |  |
| `language` | string | yes |  |

Request example:

```json
{
  "code_method": "SMS",
  "language": "en_US"
}
```

cURL:

```bash
curl -X POST "https://api.whabuzz.com/v1/numbers/$PHONE_NUMBER_ID/request-code" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code_method": "SMS",
  "language": "en_US"
}'
```

**Responses**

**200** Meta's response verbatim

```json
{
  "success": true
}
```

## Verify the code {#verifyCode}

`POST /v1/numbers/{phone_number_id}/verify-code`

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `verifyCode`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `phone_number_id` | path | string | yes |  |

**Request body** (`application/json`, required)

| Field | Type | Required | Description |
|---|---|---|---|
| `code` | string | yes |  |

Request example:

```json
{
  "code": "123456"
}
```

cURL:

```bash
curl -X POST "https://api.whabuzz.com/v1/numbers/$PHONE_NUMBER_ID/verify-code" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "123456"
}'
```

**Responses**

**200** Meta's response verbatim

```json
{
  "success": true
}
```

**Common errors.** Shape and meanings are on the [Errors page](https://docs.whabuzz.com/errors.md).

| HTTP | WhaBuzz code | Meaning |
|---|---|---|
| 400 | `131030` | Meta's error, passed through with Meta's HTTP status |

## Set or change the two-step verification PIN {#setTwoStepPin}

`POST /v1/numbers/{phone_number_id}/two-step`

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `setTwoStepPin`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `phone_number_id` | path | string | yes |  |

**Request body** (`application/json`, required)

| Field | Type | Required | Description |
|---|---|---|---|
| `pin` | string | yes | Pattern `^[0-9]{6}$`. |

Request example:

```json
{
  "pin": "482913"
}
```

cURL:

```bash
curl -X POST "https://api.whabuzz.com/v1/numbers/$PHONE_NUMBER_ID/two-step" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "pin": "482913"
}'
```

**Responses**

**200** Meta's response verbatim

```json
{
  "success": true
}
```

## Re-subscribe the number's WABA to WhaBuzz (repair) {#resubscribeWaba}

`POST /v1/numbers/{phone_number_id}/subscribe`

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `resubscribeWaba`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `phone_number_id` | path | string | yes |  |

cURL:

```bash
curl -X POST "https://api.whabuzz.com/v1/numbers/$PHONE_NUMBER_ID/subscribe" \
  -H "Authorization: Bearer $WHABUZZ_KEY"
```

**Responses**

**200** Subscribed; connection state recomputed

```json
{
  "phone_number_id": "1013622581841046",
  "connection_state": "connected",
  "connection_detail": null
}
```

## Get the WhatsApp business profile {#getBusinessProfile}

`GET /v1/numbers/{phone_number_id}/business-profile`

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `getBusinessProfile`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `phone_number_id` | path | string | yes |  |

cURL:

```bash
curl -X GET "https://api.whabuzz.com/v1/numbers/$PHONE_NUMBER_ID/business-profile" \
  -H "Authorization: Bearer $WHABUZZ_KEY"
```

**Responses**

**200** Meta's response verbatim

```json
{
  "data": [
    {
      "about": "Strength coaching in Kokapet",
      "address": "Kokapet, Hyderabad",
      "description": "Personal training studio",
      "email": "hello@example.com",
      "messaging_product": "whatsapp",
      "profile_picture_url": "https://pps.whatsapp.net/v/t61/…",
      "websites": [
        "https://example.com"
      ],
      "vertical": "HEALTH"
    }
  ]
}
```

## Update the WhatsApp business profile {#updateBusinessProfile}

`POST /v1/numbers/{phone_number_id}/business-profile`

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `updateBusinessProfile`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `phone_number_id` | path | string | yes |  |

**Request body** (`application/json`, required)

Request example:

```json
{
  "messaging_product": "whatsapp",
  "about": "Strength coaching in Kokapet",
  "websites": [
    "https://example.com"
  ]
}
```

cURL:

```bash
curl -X POST "https://api.whabuzz.com/v1/numbers/$PHONE_NUMBER_ID/business-profile" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "messaging_product": "whatsapp",
  "about": "Strength coaching in Kokapet",
  "websites": [
    "https://example.com"
  ]
}'
```

**Responses**

**200** Meta's response verbatim

```json
{
  "success": true
}
```