Skip to main content
POST
/
v1
/
sms
/
phone-numbers
/
purchase
Purchase SMS Number
curl --request POST \
  --url https://api.example.com/v1/sms/phone-numbers/purchase \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "organization_id": "<string>",
  "area_code": "<string>",
  "user_id": "<string>",
  "nickname": "<string>"
}
'
{
  "success": true,
  "phone_number": "<string>",
  "phone_id": "<string>",
  "pretty_phone_number": "<string>",
  "assigned_to": "<string>"
}

​
Purchase SMS Number

Purchase a new SMS phone number for an organization. The number is provisioned under the organization’s existing 10DLC campaign registration.

​
Prerequisites

  • Organization must have 10DLC approval (sms_active: true)
  • Tenant must have enable_multi_sms_numbers enabled
  • Organization must not exceed max_sms_numbers_per_org limit

​
Authentication

​
X-API-Key
string
required
Your API key

​
Request Body

​
organization_id
string
required
The organization’s unique_id that will own this number
​
area_code
string
required
Desired area code for the phone number (e.g., “415”, “212”)
​
user_id
string
Optional user_id to assign the number to immediately upon purchase
​
nickname
string
Optional friendly name for the number (e.g., “Sales Line”, “Support”)

​
Response

​
success
boolean
Whether the purchase was successful
​
phone_number
string
The purchased phone number in E.164 format (+15551234567)
​
phone_id
string
UUID of the phone number record
​
pretty_phone_number
string
Formatted phone number for display (+1 555-123-4567)
​
assigned_to
string
user_id if number was assigned immediately, null otherwise

​
Example Request

curl -X POST "https://api.teli.ai/v1/sms/phone-numbers/purchase" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_abc123",
    "area_code": "415",
    "user_id": "user_xyz789",
    "nickname": "Sales Line"
  }'

​
Example Response

{
  "success": true,
  "phone_number": "+14155551234",
  "phone_id": "6d7f8580-2c18-4ca9-8917-c9ca121a2c49",
  "pretty_phone_number": "+1 415-555-1234",
  "assigned_to": "user_xyz789",
  "stored": true,
  "powered_by": "Teli"
}

​
Error Responses

{
  "success": false,
  "error": "Multi-SMS numbers not enabled for this tenant. Contact support to enable."
}

{
  "success": false,
  "error": "Organization already has 10/10 SMS numbers"
}

{
  "success": false,
  "error": "Organization SMS not active (10DLC approval required)"
}

{
  "success": false,
  "error": "No numbers available in area code 999"
}

​
Billing

When a number is purchased:
  1. One-time purchase fee is charged immediately (if configured)
  2. Weekly recurring fee starts from purchase date
  3. Charges appear in usage_logs with appropriate event types

​
Notes

  • Numbers are purchased from the carrier inventory
  • The number is automatically linked to the org’s 10DLC campaign
  • If user_id is provided, the number is assigned immediately
  • Numbers without user_id go into the org’s “available pool”