Purchase from Inventory

POST

api

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

import requests

url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/purchase-from-inventory"

payload = { "e164": "+919876543210" }
headers = {
    "X-Auth-ID": "<api-key>",
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-ID': '<api-key>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({e164: '+919876543210'})
};

fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/purchase-from-inventory', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

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

{
  "api_id": "<string>",
  "error": "<string>",
  "message": "<string>"
}

{
  "api_id": "<string>",
  "error": "<string>",
  "message": "<string>"
}

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 (auth_id IS NULL)
Determines billing account (parent MA_ for SA_ accounts)
Debits balance (setup_fee + monthly_fee)
Assigns auth_id to your account
Sets purchased_at timestamp
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

Field	Type	Required	Description
`e164`	string	Yes	Phone 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.
`currency`	string	No	Currency 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

⌘I

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

import requests

url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/purchase-from-inventory"

payload = { "e164": "+919876543210" }
headers = {
    "X-Auth-ID": "<api-key>",
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-ID': '<api-key>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({e164: '+919876543210'})
};

fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/purchase-from-inventory', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

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

{
  "api_id": "<string>",
  "error": "<string>",
  "message": "<string>"
}

{
  "api_id": "<string>",
  "error": "<string>",
  "message": "<string>"
}

​HTTP Request

​Request Body

​Response

​Examples

​cURL - Purchase Number from Inventory

Authorizations

Path Parameters

Body

Response

HTTP Request

Request Body

Response

Examples

cURL - Purchase Number from Inventory