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"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.vobiz.ai/llms.txt

Use this file to discover all available pages before exploring further.

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
Note: If you have insufficient balance, the purchase will fail and the number will remain in inventory. Balance Service is used to debit the amount.

​
HTTP Request

POST /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 E164 format (e.g., “+919876543210”).
currencystringNoCurrency for transaction. Defaults to the number’s currency or “USD” if not specified.

​
Response

Returns a success message and the updated PhoneNumber object with auth_id assigned to your account.
Response - 200 OK
{
  "message": "purchased from inventory",
  "number": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "auth_id": "{auth_id}",
    "e164": "+919876543210",
    "country": "IN",
    "region": "MH",
    "status": "active",
    "provider": "manual",
    "setup_fee": 0.0,
    "monthly_fee": 1.0,
    "currency": "USD",
    "purchased_at": "2025-01-15T10:00:00Z",
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z"
  }
}

​
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): If number does not exist in inventory:
Error Response - 404 Not Found
{
  "error": "not found",
  "message": "number not found in inventory"
}
Error Response (500 Internal Server Error): If balance debit fails:
Error Response - 500 Internal Server Error
{
  "error": "internal server error",
  "message": "failed to purchase number from provider"
}
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