Skip to main content
POST
/
v1
/
organization
/
whatsapp
/
phone-numbers
cURL
curl --request POST \
  --url https://api.buildwithchirp.com/v1/organization/whatsapp/phone-numbers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "displayPhoneNumber": "+15551234567",
  "metaPhoneNumberId": "123456789012345",
  "metaBusinessAccountId": "987654321098765",
  "appIds": [
    "app_2DbBs7GWhGvVNJGrDXr5RG0mBWI"
  ]
}
'
{
  "id": "wapn_2DbBs7GWhGvVNJGrDXr5RG0mBWI",
  "displayPhoneNumber": "<string>",
  "metaPhoneNumberId": "<string>",
  "metaBusinessAccountId": "<string>",
  "verified": true,
  "qualityRating": "<string>",
  "throughputTier": "<string>",
  "qualityEvent": "<string>",
  "qualityEventAt": "2023-11-07T05:31:56Z",
  "nameStatus": "<string>",
  "requestedVerifiedName": "<string>",
  "nameRejectionReason": "<string>",
  "nameDecisionAt": "2023-11-07T05:31:56Z",
  "isTestNumber": true,
  "cloudApiRegistered": true,
  "businessProfile": {
    "id": "<string>",
    "metaWabaId": "<string>",
    "businessName": "<string>"
  },
  "apps": [
    {
      "appId": "<string>",
      "appName": "<string>",
      "appSlug": "<string>"
    }
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.buildwithchirp.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Admin API key (format: sk_admin_*) for organization-level operations

Body

application/json
​
displayPhoneNumber
string
required

The display phone number in E.164 format

Example:

"+15551234567"

​
metaPhoneNumberId
string
required

The phone_number_id from Meta's WhatsApp Business API

Example:

"123456789012345"

​
metaBusinessAccountId
string
required

The WhatsApp Business Account ID from Meta

Example:

"987654321098765"

​
appIds
string[]

Optional array of app IDs to assign the phone number to

Example:
["app_2DbBs7GWhGvVNJGrDXr5RG0mBWI"]

Response

WhatsApp phone number registered successfully

​
id
string
required

Unique identifier for a WhatsApp Phone Number. Format: wapn_[test_]{ksuid}

Pattern: ^wapn_(?:test_)?[a-zA-Z0-9]{27}$
Example:

"wapn_2DbBs7GWhGvVNJGrDXr5RG0mBWI"

​
displayPhoneNumber
string
required
​
metaPhoneNumberId
string
required
​
metaBusinessAccountId
string
required
​
verified
boolean
required
​
qualityRating
string | null
required
​
throughputTier
string | null
required

Messaging throughput tier from phone_number_quality_update (e.g. STANDARD, HIGH)

​
qualityEvent
string | null
required

Most recent quality event (e.g. FLAGGED, ONBOARDED, UPGRADE)

​
qualityEventAt
string<date-time> | null
required
​
nameStatus
string | null
required

Display name verification status (APPROVED, REJECTED, PENDING, DEFERRED)

​
requestedVerifiedName
string | null
required
​
nameRejectionReason
string | null
required
​
nameDecisionAt
string<date-time> | null
required
​
isTestNumber
boolean
required
​
cloudApiRegistered
boolean
required

Whether the phone number has been registered with Meta Cloud API (two-step verification)

​
businessProfile
object
required

The WhatsApp Business Account (WABA) this phone number belongs to

​
apps
object[]
required
​
createdAt
string<date-time>
required
​
updatedAt
string<date-time>
required