Purchase from Inventory

Purchase a phone number from inventory and assign it to your account.

This endpoint 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

Verifies number exists in inventory (account_id IS NULL)
Determines billing account (parent MA_ for SA_ accounts)
Debits balance (setup_fee + monthly_fee)
Assigns account_id to your account
Sets purchased_at timestamp
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/{accountID}/numbers/purchase-from-inventory

Authentication: Bearer token required.

Request Body

Request Parameters

Name	Type	Description
`e164`Required	string	Phone number to purchase in E164 format (e.g., "+919876543210").
`currency`	string	Currency for transaction. Defaults to the number's currency or "USD" if not specified.

Response

Returns a success message and the updated PhoneNumber object with account_id assigned to your account.

Response - 200 OK

{
  "message": "purchased from inventory",
  "number": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "account_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: YOUR_AUTH_ID" \
  -H "X-Auth-Token: YOUR_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

List Inventory Numbers

Unrent a Number