Skip to main content
POST

Authorizations

​
X-API-Key
string
header
required

Path Parameters

​
wabaId
string
required

WhatsApp Business Account ID.

Example:

"whatsapp-business-account-id"

​
phoneNumber
string
required

Phone number ID.

Example:

"1234567890123456"

Response

Successfully registered the phone number.

See WhatsApp Business Phone Number

​
id
string

Phone number ID.

Example:

"1234567890123456"

​
phoneNumber
string

Phone number in E.164 format.

Example:

"+16315551111"

​
displayPhoneNumber
string

Display phone number.

Example:

"+1 631-555-1111"

​
wabaId
string

WhatsApp Business Account ID.

Example:

"whatsapp-business-account-id"

​
businessUsername
string

Active Business Username for this phone number. The value is a plain username without @.

Example:

"acme.support"

​
businessUsernameStatus
enum<string>

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.
Available options:
not_set,
active,
pending_review,
reserved
​
requestedBusinessUsername
string

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
string<date-time>

The time when the Business Username state was last updated.

Example:

"2026-05-26T12:00:00.000Z"

​
qualityRating
enum<string>

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.
Available options:
GREEN,
YELLOW,
RED,
UNKNOWN
​
messagingLimit
string

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.
Example:

"TIER_1K"

​
whatsappBusinessManagerMessagingLimit
string

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.
Example:

"TIER_2K"

​
verifiedName
string

Verified name.

Example:

"John's Cake Shop"

​
ycloudName
string
read-only

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
string

The modified name

Example:

"John's Cake"

​
codeVerificationStatus
enum<string>

To see if a phone number has been verified via OTP (one-time password).

Available options:
VERIFIED,
NOT_VERIFIED,
EXPIRED
​
isOfficialBusinessAccount
boolean

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.

​
status
enum<string>

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.
Available options:
PENDING,
UNVERIFIED,
MANUAL_REVIEW,
DISCONNECTED,
CONNECTED,
FLAGGED,
WARNED,
RATE_LIMITED,
BANNED,
RESTRICTED,
BLOCKED,
MIGRATED,
UNKNOWN
​
nameStatus
enum<string>

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.
Available options:
APPROVED,
AVAILABLE_WITHOUT_REVIEW,
DECLINED,
EXPIRED,
PENDING_REVIEW,
NONE
​
newNameStatus
enum<string>

The review status of the new display name request. See also Get Display Name Status.

Available options:
APPROVED,
AVAILABLE_WITHOUT_REVIEW,
DECLINED,
EXPIRED,
PENDING_REVIEW,
NONE
​
decision
enum<string>

Review decision made on this phone number. One of APPROVED or REJECTED or DEFERRED.

Available options:
APPROVED,
REJECTED,
DEFERRED
​
requestedVerifiedName
string

Last requested verified name.

​
rejectionReason
string

Rejection reason.

​
qualityUpdateEvent
enum<string>

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 docs.
  • UNFLAGGED: Phone number status changes from FLAGGED to CONNECTED.
Available options:
ONBOARDING,
UPGRADE,
DOWNGRADE,
FLAGGED,
UNFLAGGED
​
updateEvent
enum<string>

Account update event that triggered this phone number status change.

Available options:
ACCOUNT_RECONNECTED,
ACCOUNT_OFFBOARDED
Example:

"ACCOUNT_OFFBOARDED"

​
throughputLevel
enum<string>

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.
Available options:
STANDARD,
HIGH,
NOT_APPLICABLE
Example:

"HIGH"