Skip to main content
POST
/
v1
/
organization
/
phone-numbers
/
{appId}
/
purchase
cURL
curl --request POST \
  --url https://api.buildwithchirp.com/v1/organization/phone-numbers/{appId}/purchase \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phoneNumber": "+14155551234",
  "numberType": "local"
}
'
{
  "phoneNumberId": "ph_2DbBs7GWhGvVNJGrDXr5RG0mBWI",
  "appId": "app_2DbBs7GWhGvVNJGrDXr5RG0mBWI",
  "number": "<string>",
  "purchaseHistoryId": "ph_purch_2DbBs7GWhGvVNJGrDXr5RG0mBWI",
  "createdAt": "<string>"
}

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
appId
string
required

Unique identifier for a App. Format: app_[test_]{ksuid}

Example:

"app_2DbBs7GWhGvVNJGrDXr5RG0mBWI"

Body

application/json
​
phoneNumber
string
required

The phone number to purchase in E.164 format

Example:

"+14155551234"

​
numberType
enum<string>
required

Type of phone number

Available options:
local,
tollfree,
mobile
Example:

"local"

Response

Phone number purchased successfully

​
phoneNumberId
string
required

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

Example:

"ph_2DbBs7GWhGvVNJGrDXr5RG0mBWI"

​
appId
string
required

Unique identifier for a App. Format: app_[test_]{ksuid}

Example:

"app_2DbBs7GWhGvVNJGrDXr5RG0mBWI"

​
number
string
required
​
purchaseHistoryId
string
required

Unique identifier for a Phone Number Purchase History. Format: ph_purch_[test_]{ksuid}

Example:

"ph_purch_2DbBs7GWhGvVNJGrDXr5RG0mBWI"

​
createdAt
string
required