Numbers
Purchase a number
Buys a number returned by GET /numbers/available and routes it to your account for messaging.
POST
/
numbers
/
purchase
cURL
curl --request POST \
--url https://api.vobiz.ai/api/v1/sms/numbers/purchase \
--header 'Content-Type: application/json' \
--header 'X-Auth-ID: <api-key>' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"e164": "+14155550100",
"country": "US"
}
'from vobiz import Vobiz
client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN")
client.sms.numbers.purchase_number(
e164="+14155550100",
country="US",
)
const options = {
method: 'POST',
headers: {
'X-Auth-ID': '<api-key>',
'X-Auth-Token': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({e164: '+14155550100', country: 'US'})
};
fetch('https://api.vobiz.ai/api/v1/sms/numbers/purchase', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"purchase": {
"id": "5c2d9e7a-1b4f-4a8c-9e3d-6f7a0b1c2d3e",
"accountId": "MA_XXXXXXXX",
"provider": "internal",
"e164": "+14155550100",
"countryCode": "US",
"type": "VIRTUAL_LONG_NUMBER",
"capabilities": [
"VOICE",
"SMS",
"MMS"
],
"setupAmount": 1,
"monthlyAmount": 1,
"currency": "USD",
"status": "purchased",
"purchasedAt": "2026-10-12T09:06:44Z",
"nextBillingAt": "2026-11-12T09:06:44Z",
"releasedAt": null,
"createdAt": "2026-10-12T09:06:42Z",
"updatedAt": "2026-10-12T09:06:44Z",
"charges": [
{
"purchaseId": "5c2d9e7a-1b4f-4a8c-9e3d-6f7a0b1c2d3e",
"kind": "purchase",
"periodStart": "2026-10-12T09:06:42Z",
"amount": 2,
"currency": "USD",
"status": "paid",
"reference": "sms_number_purchase:5c2d9e7a-1b4f-4a8c-9e3d-6f7a0b1c2d3e",
"attempts": 1,
"attemptedAt": "2026-10-12T09:06:42Z"
}
]
},
"number": {
"id": 1042,
"e164": "+14155550100",
"provider": "internal",
"channelCapabilities": [
"sms",
"mms"
],
"accountId": "MA_XXXXXXXX",
"countryCode": "US",
"createdAt": "2026-10-12T09:06:44Z"
}
}Authorizations
Your Vobiz account Auth ID (MA_XXXXXXXX).
Your Vobiz account Auth Token.
Body
application/json
The number to buy, taken from a GET /numbers/available result.
The number to buy, in E.164 format, exactly as returned in e164 by GET /numbers/available. Required.
Example:
"+14155550100"
ISO 3166-1 alpha-2 code of the number's country, for example US. Required, and must match the number; a mismatch returns 400.
Example:
"US"
The numberKey from GET /numbers/available. Required when the search result has a non-empty numberKey, as for CA and GB numbers; omit it for US numbers, which are bought by e164 alone.
Response
The number is bought, charged and routed to your account.
The result of a successful purchase: the billing record and the routing record.
Was this page helpful?
⌘I
cURL
curl --request POST \
--url https://api.vobiz.ai/api/v1/sms/numbers/purchase \
--header 'Content-Type: application/json' \
--header 'X-Auth-ID: <api-key>' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"e164": "+14155550100",
"country": "US"
}
'from vobiz import Vobiz
client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN")
client.sms.numbers.purchase_number(
e164="+14155550100",
country="US",
)
const options = {
method: 'POST',
headers: {
'X-Auth-ID': '<api-key>',
'X-Auth-Token': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({e164: '+14155550100', country: 'US'})
};
fetch('https://api.vobiz.ai/api/v1/sms/numbers/purchase', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"purchase": {
"id": "5c2d9e7a-1b4f-4a8c-9e3d-6f7a0b1c2d3e",
"accountId": "MA_XXXXXXXX",
"provider": "internal",
"e164": "+14155550100",
"countryCode": "US",
"type": "VIRTUAL_LONG_NUMBER",
"capabilities": [
"VOICE",
"SMS",
"MMS"
],
"setupAmount": 1,
"monthlyAmount": 1,
"currency": "USD",
"status": "purchased",
"purchasedAt": "2026-10-12T09:06:44Z",
"nextBillingAt": "2026-11-12T09:06:44Z",
"releasedAt": null,
"createdAt": "2026-10-12T09:06:42Z",
"updatedAt": "2026-10-12T09:06:44Z",
"charges": [
{
"purchaseId": "5c2d9e7a-1b4f-4a8c-9e3d-6f7a0b1c2d3e",
"kind": "purchase",
"periodStart": "2026-10-12T09:06:42Z",
"amount": 2,
"currency": "USD",
"status": "paid",
"reference": "sms_number_purchase:5c2d9e7a-1b4f-4a8c-9e3d-6f7a0b1c2d3e",
"attempts": 1,
"attemptedAt": "2026-10-12T09:06:42Z"
}
]
},
"number": {
"id": 1042,
"e164": "+14155550100",
"provider": "internal",
"channelCapabilities": [
"sms",
"mms"
],
"accountId": "MA_XXXXXXXX",
"countryCode": "US",
"createdAt": "2026-10-12T09:06:44Z"
}
}