Skip to main content
POST
/
api
/
v1
/
Account
/
{auth_id}
/
numbers
/
purchase-from-inventory
Purchase from Inventory
curl --request POST \
  --url https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/purchase-from-inventory \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "e164": "+919876543210"
}
'
{
  "message": "Number purchased successfully",
  "number": {
    "id": "aabbccdd-1234-5678-90ab-cdef12345678",
    "account_id": "MA_XXXXXXXX",
    "e164": "+919876543210",
    "country": "IN",
    "region": "Karnataka",
    "capabilities": {
      "voice": true,
      "sms": false,
      "mms": false,
      "fax": false
    },
    "status": "active",
    "provider": "",
    "setup_fee": 100,
    "monthly_fee": 1,
    "currency": "INR",
    "voice_enabled": true,
    "tags": [],
    "purchased_at": "2026-03-25T10:00:00Z",
    "is_blocked": false,
    "created_at": "2026-03-25T10:00:00Z",
    "updated_at": "2026-03-25T10:00:00Z",
    "is_trial_number": false,
    "minimum_commitment_months": 0,
    "aadhaar_verification_required": false,
    "aadhaar_verified": false,
    "source": "inventory"
  },
  "items": [
    {
      "id": "aabbccdd-1234-5678-90ab-cdef12345678",
      "account_id": "MA_XXXXXXXX",
      "e164": "+919876543210",
      "country": "IN",
      "region": "Karnataka",
      "capabilities": {
        "voice": true,
        "sms": false,
        "mms": false,
        "fax": false
      },
      "status": "active",
      "monthly_fee": 1,
      "currency": "INR"
    }
  ]
}
Purchases a number from inventory and assigns it to your account. The operation debits your account balance for the setup fee and monthly fee.
Important: Purchase Process
  1. Verifies number exists in inventory (auth_id IS NULL)
  2. Determines billing account (parent MA_ for SA_ accounts)
  3. Debits balance (setup_fee + monthly_fee)
  4. Assigns auth_id to your account
  5. Sets purchased_at timestamp
  6. Returns updated number
Billing account: the setup fee and monthly fee are debited from the account that owns the credentials. When a sub-account (SA_) purchases, the parent master account (MA_) is charged — not the sub-account.
Insufficient balance: if the balance debit fails, the purchase is rolled back and the number stays in inventory (still auth_id=NULL). Verify available balance covers setup_fee + monthly_fee before calling. A failed debit currently surfaces as a 500 (see below).

​
HTTP Request

POST /api/v1/Account/{auth_id}/numbers/purchase-from-inventory
Authentication required:
  • X-Auth-ID - Your Auth ID (e.g., {auth_id})
  • X-Auth-Token - Your account Auth Token
  • Content-Type: application/json

​
Request Body

FieldTypeRequiredDescription
e164stringYesPhone number to purchase in E.164 format (e.g., +919876543210). Keep the literal + — this field is in the JSON body, so no URL-encoding is needed.
currencystringNoCurrency for the transaction. Defaults to the number’s currency, or USD if neither is set.
The number must currently be in inventory (status='active' and auth_id=NULL). Browse it first with List Inventory Numbers.

​
Response

Returns a success message and the updated PhoneNumber object with auth_id assigned to your account.
Response - 200 OK
{
  "message": "Number purchased successfully",
  "number": {
    "id": "aabbccdd-1234-5678-90ab-cdef12345678",
    "account_id": "MA_XXXXXXXX",
    "e164": "+919876543210",
    "country": "IN",
    "region": "Karnataka",
    "capabilities": {
      "voice": true,
      "sms": false,
      "mms": false,
      "fax": false
    },
    "status": "active",
    "provider": "",
    "setup_fee": 100,
    "monthly_fee": 1.0,
    "currency": "INR",
    "voice_enabled": true,
    "tags": [],
    "purchased_at": "2026-03-25T10:00:00Z",
    "is_blocked": false,
    "created_at": "2026-03-25T10:00:00Z",
    "updated_at": "2026-03-25T10:00:00Z",
    "is_trial_number": false,
    "minimum_commitment_months": 0,
    "aadhaar_verification_required": false,
    "aadhaar_verified": false,
    "source": "inventory"
  }
}
After purchase the number is owned by your account (account_id set, source: "inventory") but not yet routed. Assign it to a trunk, attach it to an application, or hand it to a sub-account to start receiving calls.

​
Examples

​
cURL - Purchase Number from Inventory

cURL Request
curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/purchase-from-inventory \
  -H "X-Auth-ID: {auth_id}" \
  -H "X-Auth-Token: {auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "e164": "+919876543210",
    "currency": "USD"
  }'
Error Response (404 Not Found): the number does not exist in inventory (already owned, released, or never stocked):
Error Response - 404 Not Found
{
  "error": "not_found",
  "message": "number not found in inventory"
}
Error Response (500 Internal Server Error): the purchase failed — most commonly because the balance debit (setup_fee + monthly_fee) could not be completed. The number remains in inventory.
Error Response - 500 Internal Server Error
{
  "error": "internal_server_error",
  "message": "failed to purchase number"
}
Best Practices:
  • Always check inventory first to ensure the number is available
  • Verify you have sufficient balance before purchasing
  • Note that setup_fee + monthly_fee will be debited immediately
  • For sub-accounts (SA_), the parent master account (MA_) will be charged

Authorizations

​
X-Auth-ID
string
header
required

Your Vobiz account Auth ID

​
X-Auth-Token
string
header
required

Your Vobiz account Auth Token

Path Parameters

​
auth_id
string
required

Your account Auth ID

Example:

"MA_XXXXXX"

Body

application/json
​
e164
string
required

Phone number to purchase in E.164 format.

Example:

"+919876543210"

​
currency
string

Currency for transaction. Defaults to the number's currency or "USD".

Example:

"USD"

Response

Number purchased