# List WhatsApp subscribers

Retrieve a paginated list of WhatsApp subscribers for the organization.

Source: https://statusdashboard.com/docs/api/subscriptions/whatsapp/subscribers/list

`GET /app/subscribers/whatsapp/subscribers`

Returns a paginated list of WhatsApp subscription records for the organization (one row per dashboard + phone). Includes org-wide unique subscriber quota usage.

Requires the `admin` or `subscriber` role and the **WhatsApp notifications** feature entitlement.

***

## Request
See [API Basics](/docs/api) for required headers.

### Query parameters
| Parameter   | Type    | Required | Description                                                                                              |
| ----------- | ------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `limit`     | integer | No       | Max items per page. Range: 1–100. Default: `10`.                                                         |
| `nextToken` | string  | No       | Next-page bookmark from the previous response — pass unchanged. See [Pagination](/docs/api#pagination).  |
| `phone`     | string  | No       | Filter to an exact E.164 phone number (e.g. `+14155552671`). Must be a valid E.164 number when provided. |

Omit `phone` to list subscribers across all numbers (paginated).

***

## Sample request
```bash
curl "https://api.statusdashboard.com/app/subscribers/whatsapp/subscribers?limit=10&phone=%2B14155552671" \
  -H "Authorization: Bearer bcf847abf5c6:def456"
```

## Sample response
**Status: `200 OK`**

```json
{
  "subscribers": [
    {
      "phone": "+1 415 555 2671",
      "normalizedPhone": "+14155552671",
      "dashboardId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "dashboardName": "Acme Status",
      "verified": true,
      "verifiedAt": "2026-06-01T14:22:00.000Z",
      "createdAt": "2026-06-01T14:20:00.000Z",
      "updatedAt": "2026-06-01T14:22:00.000Z",
      "componentIds": ["b2c3d4e5-f6a7-8901-bcde-f12345678901", "c3d4e5f6-a7b8-9012-cdef-123456789012"],
      "paused": false
    }
  ],
  "nextToken": null,
  "usage": {
    "uniquePhones": 42,
    "limit": 1000
  }
}
```

***

## Response fields
| Field                           | Description                                                                                         |
| ------------------------------- | --------------------------------------------------------------------------------------------------- |
| `subscribers`                   | Page of subscription records                                                                        |
| `subscribers[].phone`           | International display format                                                                        |
| `subscribers[].normalizedPhone` | E.164 identity used in path parameters for update and delete                                        |
| `subscribers[].paused`          | Derived: `true` when verified and `componentIds` is empty (notifications off; subscription remains) |
| `nextToken`                     | See [Pagination](/docs/api#pagination). `null` when there are no more pages.                        |
| `usage.uniquePhones`            | Unique phone numbers org-wide (pending and verified)                                                |
| `usage.limit`                   | Plan `whatsappSubscribers` quota                                                                    |

There is no admin-managed (`locked`) flag for WhatsApp subscribers — that concept applies only to email.

***

## Pagination
See [Pagination](/docs/api#pagination) in API Basics. Re-send the same query parameters on every page request.

***

## Error responses
| Status | When                                                                                                 |
| ------ | ---------------------------------------------------------------------------------------------------- |
| `400`  | Invalid query parameters                                                                             |
| `403`  | Requires admin or subscriber role, or the WhatsApp notifications feature is not enabled on your plan |