Buy Phone Number

Purchase a phone number and register it for your organization. After a successful purchase, the number is linked to your org and can be assigned to a voice agent.

Indian (+91) numbers trigger automatic SIP trunk activation. If activation fails, the number may still be purchased — you can complete setup from the dashboard.

Endpoint

POST https://www.tabbly.io/api/phone-numbers/buy

Authentication

See Introduction. This is a POST endpoint — include api_key in the JSON request body.

Request body

Field	Type	Required	Description
`api_key`	string	Yes	Your organization API key
`phone_number`	string	Yes	Number from Search Phone Numbers (E.164 format)
`number`	string	No	Alias for `phone_number` (same meaning; `phone_number` is used if both are sent)

Example request

curl -X POST "https://www.tabbly.io/api/phone-numbers/buy" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "phone_number": "+918031321970"
  }'

Response

Success (200)

{
  "success": true,
  "message": "Phone number purchase processed.",
  "phone_number": "+918031321970",
  "id": 1616,
  "organization_id": 3282,
  "tabbly_status": "fulfilled",
  "number_status": "Success",
  "sip_activation_status": "success",
  "sip_activation_country": "IN",
  "sip_trunk_id": 12345,
  "tabbly_trunk_id": "abc-uuid"
}

Field	Description
`tabbly_status`	Telco provisioning status for the purchase
`number_status`	Overall purchase result
`sip_activation_status`	SIP trunk activation result (`success`, `failed`, or `skipped`)
`sip_trunk_id`	Internal Tabbly SIP trunk ID when activation succeeds
`tabbly_trunk_id`	External trunk identifier when provisioned

Error responses

{
  "success": false,
  "error": "Human-readable error description"
}

HTTP status	When
400	Missing API key or phone number
401	Invalid API key
402	Wallet balance below minimum (≥ 7 credits required)
409	Number already registered for your organization
502	SIP activation failed (number may still be purchased)

Notes

Purchases deduct credits from your organization wallet.
If SIP activation fails for +91 numbers, activate manually from the Tabbly dashboard.