Buy Phone Number

Purchases a phone number from available inventory and adds it to your organization. After a successful purchase, the number can be assigned to a voice agent.

Indian (+91) numbers from inventory trigger automatic SIP trunk activation for outbound calling. Use a number returned by Search Phone Numbers.

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

Parameter	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`. Use either field; if both are sent, `phone_number` is used

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": "+918065830105"
  }'

Response

Success (200)

{
  "success": true,
  "message": "Phone number assigned successfully.",
  "phone_number": "08065830105",
  "e164": "+918065830105",
  "id": 1616,
  "organization_id": 3282,
  "tabbly_status": "fulfilled",
  "number_status": "Success",
  "sip_activation_status": "success",
  "sip_activation_country": "IN",
  "sip_trunk_id": "ST_xxx",
  "tabbly_trunk_id": null
}

Field	Description
`phone_number`	Number stored for your organization (national form for India inventory)
`e164`	E.164 form of the number
`tabbly_status`	Purchase provisioning status
`number_status`	Overall purchase result
`sip_activation_status`	SIP trunk activation result (`success`, `failed`, or `skipped`)
`sip_trunk_id`	SIP trunk ID when activation succeeds

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) or insufficient for list price
404	Number not in available inventory
409	Number already registered for your organization, or already assigned
502	SIP activation or inventory claim failed

Notes

Purchases deduct the listed price from your organization wallet.
Only numbers returned by Search (available inventory) can be purchased.
SIP activation runs automatically for Indian inventory numbers.