{
"id": "1234567890123456",
"phoneNumber": "+16315551111",
"displayPhoneNumber": "+1 631-555-1111",
"wabaId": "whatsapp-business-account-id",
"businessUsername": "acme.support",
"businessUsernameContext": "revoked",
"businessUsernameStatus": "not_set",
"requestedBusinessUsername": "acme.help",
"businessUsernameUpdatedAt": "2026-05-26T12:00:00.000Z",
"qualityRating": "GREEN",
"messagingLimit": "TIER_1K",
"whatsappBusinessManagerMessagingLimit": "TIER_2K",
"verifiedName": "John's Cake Shop",
"ycloudName": "Support line",
"newName": "John's Cake",
"codeVerificationStatus": "VERIFIED",
"isOfficialBusinessAccount": true,
"status": "PENDING",
"nameStatus": "APPROVED",
"newNameStatus": "APPROVED",
"decision": "APPROVED",
"requestedVerifiedName": "<string>",
"rejectionReason": "<string>",
"qualityUpdateEvent": "ONBOARDING",
"updateEvent": "ACCOUNT_OFFBOARDED",
"throughputLevel": "HIGH"
}{
"error": {
"status": 404,
"code": "NOT_FOUND",
"message": "The requested resource does not exist.",
"target": "",
"docUrl": "",
"requestId": "req_1KjtKI80IKoaJNa6n6p",
"whatsappApiError": {
"message": "HSM Template creation failed",
"code": 200002,
"type": "OAuthException",
"is_transient": false,
"error_subcode": 2388109,
"error_user_msg": "This message template cannot be created.",
"error_user_title": "Message Cannot Be Submitted",
"fbtrace_id": "AVGjJ7ia2zJkrHG",
"error_data": "<string>"
},
"metaBusinessAgentApiError": {
"title": "<string>",
"detail": "<string>",
"type": "<string>",
"status": 123,
"requestId": "<string>"
},
"messengerApiError": {
"code": "100",
"subcode": "2018276"
}
}
}Retrieve a phone number
Retrieves a WhatsApp business phone number you’ve registered.
{
"id": "1234567890123456",
"phoneNumber": "+16315551111",
"displayPhoneNumber": "+1 631-555-1111",
"wabaId": "whatsapp-business-account-id",
"businessUsername": "acme.support",
"businessUsernameContext": "revoked",
"businessUsernameStatus": "not_set",
"requestedBusinessUsername": "acme.help",
"businessUsernameUpdatedAt": "2026-05-26T12:00:00.000Z",
"qualityRating": "GREEN",
"messagingLimit": "TIER_1K",
"whatsappBusinessManagerMessagingLimit": "TIER_2K",
"verifiedName": "John's Cake Shop",
"ycloudName": "Support line",
"newName": "John's Cake",
"codeVerificationStatus": "VERIFIED",
"isOfficialBusinessAccount": true,
"status": "PENDING",
"nameStatus": "APPROVED",
"newNameStatus": "APPROVED",
"decision": "APPROVED",
"requestedVerifiedName": "<string>",
"rejectionReason": "<string>",
"qualityUpdateEvent": "ONBOARDING",
"updateEvent": "ACCOUNT_OFFBOARDED",
"throughputLevel": "HIGH"
}{
"error": {
"status": 404,
"code": "NOT_FOUND",
"message": "The requested resource does not exist.",
"target": "",
"docUrl": "",
"requestId": "req_1KjtKI80IKoaJNa6n6p",
"whatsappApiError": {
"message": "HSM Template creation failed",
"code": 200002,
"type": "OAuthException",
"is_transient": false,
"error_subcode": 2388109,
"error_user_msg": "This message template cannot be created.",
"error_user_title": "Message Cannot Be Submitted",
"fbtrace_id": "AVGjJ7ia2zJkrHG",
"error_data": "<string>"
},
"metaBusinessAgentApiError": {
"title": "<string>",
"detail": "<string>",
"type": "<string>",
"status": 123,
"requestId": "<string>"
},
"messengerApiError": {
"code": "100",
"subcode": "2018276"
}
}
}Path Parameters
Phone number in E.164 format.
"+16315551111"
Response
Successfully retrieved the object.
Phone number in E.164 format.
"+16315551111"
Optional context of this username notification. revoked is included only when the username from a successful current Meta query matches this revoked notification. Omitted for an obsolete revocation or a notification without context; it does not expose historical page warnings.
"revoked"
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 usereserved. If an active username exists while a new request is reserved or under review,businessUsernameStatusisreserved,businessUsernamecontains the still-active username, andrequestedBusinessUsernamecontains the requested username.
not_set, active, pending_review, reserved Quality rating. One of GREEN, YELLOW, RED, or UNKNOWN. See also Phone Number Quality Rating.
GREEN: High quality.YELLOW: Medium quality.RED: Low quality.UNKNOWN: Unknown quality.
GREEN, YELLOW, RED, UNKNOWN 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.
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.
"TIER_1K"
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.
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.
"TIER_2K"
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 for more information.
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.
PENDING, UNVERIFIED, MANUAL_REVIEW, DISCONNECTED, CONNECTED, FLAGGED, WARNED, RATE_LIMITED, BANNED, RESTRICTED, BLOCKED, MIGRATED, UNKNOWN The review status of the current display name request. See also Get Display Name Status.
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.
APPROVED, AVAILABLE_WITHOUT_REVIEW, DECLINED, EXPIRED, PENDING_REVIEW, NONE The review status of the new display name request. See also Get Display Name Status.
APPROVED, AVAILABLE_WITHOUT_REVIEW, DECLINED, EXPIRED, PENDING_REVIEW, NONE Indicates the update event type of WhatsApp phone number quality when a notification is sent to you.
ONBOARDING: Typically when the messaging limit changes fromTIER_NOT_SETto 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 docs.UNFLAGGED: Phone number status changes fromFLAGGEDtoCONNECTED.
ONBOARDING, UPGRADE, DOWNGRADE, FLAGGED, UNFLAGGED 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.
STANDARD, HIGH, NOT_APPLICABLE "HIGH"

