Skip to main content
POST
/
user
/
phone-numbers
/
purchase
Purchase phone number
curl --request POST \
  --url https://call.aiployees.com/api/user/phone-numbers/purchase \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phone_number": "<string>"
}
'
{
  "message": "Phone number purchased successfully.",
  "data": {
    "id": 123,
    "phone_number": "+14155551234",
    "country_code": "US",
    "type": "normal",
    "sms_capable": true
  }
}
This endpoint allows you to purchase a phone number that was found using the search endpoint. The platform automatically handles pricing, billing, and provisioning.
You must have a valid payment method on file before purchasing a phone number. The purchase creates a monthly subscription that will auto-renew.

​
Request Body

​
phone_number
string
required
The phone number to purchase in E.164 format (e.g., +14155551234). Must be a number returned from the search endpoint.

​
Response

​
message
string
Success message
​
data
object
The purchased phone number details
{
  "message": "Phone number purchased successfully.",
  "data": {
    "id": 123,
    "phone_number": "+14155551234",
    "country_code": "US",
    "type": "normal",
    "sms_capable": true
  }
}

​
How It Works

  1. Search - First use the search endpoint to find available numbers
  2. Purchase - Submit the phone number you want to this endpoint
  3. Automatic Processing - The platform:
    • Validates the number is still available
    • Determines the correct pricing based on country
    • Creates a monthly subscription on your payment method
    • Provisions the number with our telephony provider
    • Creates the phone number record in your account
Phone number purchases are non-refundable. The subscription will continue until you release the number.