> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # List phone numbers > Returns a paginated list of WhatsApp business phone numbers you've registered. ## OpenAPI ````yaml /openapi/endpoints/ycloud-api-v2.yaml get /whatsapp/phoneNumbers openapi: 3.0.0 info: description: >- The [YCloud](https://ycloud.com) API is organized around [REST](https://en.wikipedia.org/wiki/Representational_state_transfer). Our API is designed to have predictable, resource-oriented URLs, return [JSON](https://www.json.org) responses, and use standard HTTP response codes and verbs. version: v2 title: YCloud API termsOfService: https://ycloud.com/terms-service contact: email: service@ycloud.com servers: - url: https://api.ycloud.com/v2 description: Base URL security: - api_key: [] tags: - name: Balance - name: Contacts - name: Custom Events - name: Emails - name: SMS - name: Unsubscribers - name: Verify - name: Voices - name: Webhook Endpoints - name: WhatsApp Business Accounts - name: WhatsApp Inbound Messages - name: WhatsApp Media - name: WhatsApp Messages - name: WhatsApp Blocked Users - name: WhatsApp Groups - name: WhatsApp Calling - name: WhatsApp Phone Numbers - name: WhatsApp Templates - name: WhatsApp Flows - name: Meta Business Agent - name: WhatsApp Group Messages externalDocs: description: Homepage url: https://ycloud.com paths: /whatsapp/phoneNumbers: get: tags: - WhatsApp Phone Numbers summary: List phone numbers description: >- Returns a paginated list of WhatsApp business phone numbers you've registered. operationId: whatsapp_phone_number-list parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/includeTotal' - $ref: '#/components/parameters/filter_wabaId' responses: '200': description: Successfully retrieved a paginated list of objects. content: application/json: schema: $ref: '#/components/schemas/WhatsappPhoneNumberPage' components: parameters: page: name: page in: query description: Page number of the results to be returned, 1-based. required: false schema: type: integer format: int32 minimum: 1 maximum: 100 default: 1 limit: name: limit in: query description: >- A limit on the number of results to be returned, or number of results per page, between 1 and 100, defaults to 10. required: false schema: type: integer format: int32 minimum: 1 maximum: 100 default: 10 includeTotal: name: includeTotal in: query description: >- Return results inside an object that contains the total result count or not. required: false schema: type: boolean default: false filter_wabaId: name: filter.wabaId in: query description: |- **Required if you have more than 100 WABAs.** WhatsApp Business Account ID. required: false schema: type: string example: whatsapp-business-account-id schemas: WhatsappPhoneNumberPage: type: object description: Represents a given page of WhatsApp phone numbers. allOf: - $ref: '#/components/schemas/Page' properties: items: description: An array containing WhatsApp phone number objects. type: array items: $ref: '#/components/schemas/WhatsappPhoneNumber' Page: type: object description: Represents a given page of items. required: - offset - limit - length properties: offset: description: >- The position of the item this page starts from, zero-based. e.g., the 11th item is at offset 10. type: integer format: int32 minimum: 0 limit: description: >- A limit on the number of items to be returned, between 1 and 100, defaults to 10. type: integer format: int32 minimum: 1 length: description: The actual number of items in the page. type: integer format: int32 minimum: 0 total: description: >- The total number of items. This field is returned only when the request parameter `includeTotal` is set to `true`. type: integer format: int32 minimum: 0 items: type: array items: type: object WhatsappPhoneNumber: type: object description: >- See [WhatsApp Business Phone Number](https://developers.facebook.com/docs/whatsapp/cloud-api/phone-numbers) properties: id: type: string description: Phone number ID. example: '1234567890123456' phoneNumber: type: string description: Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' displayPhoneNumber: type: string description: Display phone number. example: +1 631-555-1111 wabaId: type: string description: WhatsApp Business Account ID. example: whatsapp-business-account-id businessUsername: type: string description: >- Active Business Username for this phone number. The value is a plain username without `@`. example: acme.support businessUsernameStatus: $ref: '#/components/schemas/WhatsappBusinessUsernameStatus' requestedBusinessUsername: type: string description: >- Last requested Business Username that is still under review. This value can coexist with an active `businessUsername` while the new request is pending. example: acme.help businessUsernameUpdatedAt: type: string format: date-time description: The time when the Business Username state was last updated. example: '2026-05-26T12:00:00.000Z' qualityRating: $ref: '#/components/schemas/WhatsappPhoneNumberQualityRating' messagingLimit: type: string description: >- Messaging limits determine the maximum number of business-initiated conversations each phone number can start in a rolling 24-hour period. See also [Messaging Limits](https://developers.facebook.com/docs/whatsapp/messaging-limits). - `TIER_NOT_SET`: Unknown limit. - `TIER_50`: 50 business-initiated conversations in a rolling 24-hour period. - `TIER_250`: 250 business-initiated conversations in a rolling 24-hour period. - `TIER_1K`: 1K business-initiated conversations with unique customers in a rolling 24-hour period. - `TIER_10K`: 10K business-initiated conversations with unique customers in a rolling 24-hour period. - `TIER_100K`: 100K business-initiated conversations with unique customers in a rolling 24-hour period. - `TIER_UNLIMITED`: An unlimited number of business-initiated conversations in a rolling 24-hour period. example: TIER_1K whatsappBusinessManagerMessagingLimit: type: string description: >- The owning business portfolio's messaging limit. Starting October 7, 2025, messaging limits will instead be calculated and set on a business portfolio basis, and will be shared by all business phone numbers within each portfolio. See also [phone_number_quality_update webhook reference](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/reference/phone_number_quality_update). - `TIER_NOT_SET`: The business phone number has not been used to send a message yet. - `TIER_50`: Messaging limit of 50 business-initiated conversations in a rolling 24-hour period. - `TIER_250`: Messaging limit of 250 business-initiated conversations in a rolling 24-hour period. - `TIER_2K`: Messaging limit of 2,000 business-initiated conversations in a rolling 24-hour period. - `TIER_10K`: Messaging limit of 10,000 business-initiated conversations in a rolling 24-hour period. - `TIER_100K`: Messaging limit of 100,000 business-initiated conversations in a rolling 24-hour period. - `TIER_UNLIMITED`: The business phone number has higher throughput with unlimited business-initiated conversations. example: TIER_2K verifiedName: type: string description: Verified name. example: John's Cake Shop ycloudName: type: string readOnly: true description: >- Optional remark name assigned to this phone number in YCloud. It is populated by the phone-number list, retrieve, and profile GET APIs, and omitted when no remark name is set. example: Support line newName: type: string description: The modified name example: John's Cake codeVerificationStatus: $ref: '#/components/schemas/WhatsappPhoneNumberCodeVerificationStatus' isOfficialBusinessAccount: type: boolean description: >- Whether this phone number is an official business account or not. An official business account has a green checkmark badge in its profile and chat thread headers. See [Official Business Account](https://developers.facebook.com/docs/whatsapp/overview/business-accounts#official-business-account) for more information. status: $ref: '#/components/schemas/WhatsappPhoneNumberStatus' nameStatus: $ref: '#/components/schemas/WhatsappPhoneNumberNameStatus' newNameStatus: $ref: '#/components/schemas/WhatsappPhoneNumberNameStatus' description: >- The review status of the new display name request. See also [Get Display Name Status](https://developers.facebook.com/docs/whatsapp/business-management-api/manage-phone-numbers#get-display-name-status--beta-). decision: $ref: '#/components/schemas/WhatsappReviewDecision' description: >- Review decision made on this phone number. One of `APPROVED` or `REJECTED` or `DEFERRED`. requestedVerifiedName: type: string description: Last requested verified name. rejectionReason: type: string description: Rejection reason. qualityUpdateEvent: $ref: '#/components/schemas/WhatsappPhoneNumberQualityUpdateEventEnum' updateEvent: type: string description: Account update event that triggered this phone number status change. enum: - ACCOUNT_RECONNECTED - ACCOUNT_OFFBOARDED example: ACCOUNT_OFFBOARDED throughputLevel: type: string description: >- Current Meta throughput level of the WhatsApp phone number. - `STANDARD`: Default Cloud API throughput level, currently up to 80 messages per second. - `HIGH`: Upgraded Cloud API throughput level, currently up to 1,000 messages per second, subject to Meta's current Cloud API throughput rules. - `NOT_APPLICABLE`: Throughput level is not applicable to this phone number. enum: - STANDARD - HIGH - NOT_APPLICABLE example: HIGH WhatsappBusinessUsernameStatus: type: string description: >- 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. enum: - not_set - active - pending_review - reserved WhatsappPhoneNumberQualityRating: type: string description: >- Quality rating. One of `GREEN`, `YELLOW`, `RED`, or `UNKNOWN`. See also [Phone Number Quality Rating](https://www.facebook.com/business/help/896873687365001). - `GREEN`: High quality. - `YELLOW`: Medium quality. - `RED`: Low quality. - `UNKNOWN`: Unknown quality. enum: - GREEN - YELLOW - RED - UNKNOWN WhatsappPhoneNumberCodeVerificationStatus: type: string description: To see if a phone number has been verified via OTP (one-time password). enum: - VERIFIED - NOT_VERIFIED - EXPIRED WhatsappPhoneNumberStatus: type: string description: >- The status of a WhatsApp business phone number. - `PENDING`: Pending. Phone number is newly added. Verify and register this phone number so it can be connected to your account. - `UNVERIFIED`: Unverified. Verify this phone number to start sending messages. - `MANUAL_REVIEW`: Being reviewed. Phone number is currently being reviewed for connection to your account. - `DISCONNECTED`: Offline. Phone number is currently not reachable by WhatsApp servers. - `CONNECTED`: Connected. Phone number is associated with this account and working properly. - `FLAGGED`: Flagged. This phone number has been flagged due to low quality messages. - `WARNED`: Warned. A warning has been issued for this number, potentially due to spam reports. - `RATE_LIMITED`: Rate limited. The number of messages you can send from this phone number may be restricted. - `BANNED`: Banned. Phone number cannot be used with a WhatsApp account. - `RESTRICTED`: Restricted. This phone number has reached its 24-hour messaging limit and can no longer send messages to customers. Please wait until the messaging limit is reset to send messages. - `BLOCKED`: Message limit reached. The limit has been reached for this 24-hour period. - `MIGRATED`: Transferred. This phone number has been transferred to another WhatsApp Business account. - `UNKNOWN`: Unavailable. The status of this phone number can't be determined right now. enum: - PENDING - UNVERIFIED - MANUAL_REVIEW - DISCONNECTED - CONNECTED - FLAGGED - WARNED - RATE_LIMITED - BANNED - RESTRICTED - BLOCKED - MIGRATED - UNKNOWN WhatsappPhoneNumberNameStatus: type: string description: >- The review status of the current display name request. See also [Get Display Name Status](https://developers.facebook.com/docs/whatsapp/business-management-api/manage-phone-numbers#get-display-name-status--beta-). - `APPROVED`: The name has been approved. You can download your certificate now. - `AVAILABLE_WITHOUT_REVIEW`: The certificate for the phone is available and display name is ready to use without review. - `DECLINED`: The name has not been approved. You cannot download your certificate. - `EXPIRED`: Your certificate has expire and can no longer be downloaded. - `PENDING_REVIEW`: Your name request is under review. You cannot download your certificate. - `NONE`: No certificate is available. enum: - APPROVED - AVAILABLE_WITHOUT_REVIEW - DECLINED - EXPIRED - PENDING_REVIEW - NONE WhatsappReviewDecision: type: string description: >- Used if a decision about WhatsApp accounts or phone numbers has been made. enum: - APPROVED - REJECTED - DEFERRED WhatsappPhoneNumberQualityUpdateEventEnum: type: string description: >- Indicates the update event type of WhatsApp phone number quality when a notification is sent to you. - `ONBOARDING`: Typically when the messaging limit changes from `TIER_NOT_SET` to another tier. - `UPGRADE`: Messaging limit tier upgraded. - `DOWNGRADE`: Messaging limit tier downgraded. - `FLAGGED`: Flagged status occurs when the quality rating reaches a low state. If the message quality improves to a high or medium state and maintains this for 7 days, your status will return to Connected. If the quality rating doesn't improve, your status will still return to Connected, but you'll be placed in a lower messaging limit tier. Learn more on [Phone Number Quality Rating](https://www.facebook.com/business/help/896873687365001) docs. - `UNFLAGGED`: Phone number status changes from `FLAGGED` to `CONNECTED`. enum: - ONBOARDING - UPGRADE - DOWNGRADE - FLAGGED - UNFLAGGED securitySchemes: api_key: type: apiKey name: X-API-Key in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.