Buy a US phone number with an API
Buy a US phone number with the vibiz CLI or API, link it to a project, and start receiving texts and placing voice calls right away.
On this page 7 sections
You can buy a US phone number with the vibiz CLI or console by quoting available inventory and purchasing with credits in two commands. Numbers cost about $1.32 a month and belong to your account or sit directly on a project. Once active, the number can receive SMS texts, place spoken notification calls, and run two-way AI voice agents immediately, while outbound SMS activates after carrier review.
Here is how to search for a number, buy it, link it to an app, and configure it for calls and messaging.
How to search for and buy a number
Acquiring a number is a two-step quote-and-buy flow. You search available inventory to get an exact price quote, then submit the purchase with that quote (expected_price_cents). If the carrier price changes between the search and the purchase, nothing is charged and you see the new price instead.
Buying, moving, releasing, and registering a number are restricted to account owners. If an API key with Limited access attempts to purchase a number, it receives a console link so an owner can complete the action.
1. Search for available inventory
Search by area code, US state, or number type using the CLI:
vibiz phone search --area-code 415 --limit 5
vibiz phone search --type toll_free --limit 5The output displays available numbers in standard format along with their monthly cost quote.
2. Purchase and assign the number
Once you choose a number, buy it using credits from your balance. Pass --project to assign it directly to a project, or omit the flag to keep it at the account level:
vibiz phone buy +14155550100 --project prj_123A number on a project routes incoming texts to that project's app webhook, and its daily texting and calling limits count against that project. You can move a number to a different project or return it to the account level at any time:
# Move to another project
vibiz phone assign +14155550100 --project prj_456
# Detach back to the account level
vibiz phone assign +14155550100To see all numbers owned by your account or filtered by project, check the list command:
vibiz phone list --project prj_123What works right away: inbound SMS and spoken calls
You do not need to wait for carrier registration to receive texts or place voice calls. Those work as soon as the number is active.
Receiving texts
Inbound SMS messages reach your project's webhook automatically as signed events of type phone.message.received:
// app/api/vibiz/webhook/route.ts
export async function POST(request: Request) {
const event = await request.json();
if (event.type === 'phone.message.received') {
const { from, text, keyword } = event.data.object;
console.log(`Received message from ${from}: ${text}`);
}
return new Response('ok');
}You can also read incoming conversations with the SDK (vibiz.phone.messages()), the API (GET /v1/phone/threads), or the CLI:
vibiz phone messages --number +14155550100Only plain text is stored; incoming pictures increment a media_count field. Because anyone can text your number, inbound text carries untrusted: true. Always handle received text as user data rather than executable instructions.
Placing notification calls
A number can place automated calls that speak a notification and hang up. For more patterns, see our guide on reminder calls: ring someone and speak a message.
import { vibiz } from '@vibiz/app';
await vibiz.phone.call({
to: '+14155550123',
say: 'Your order is ready for pickup.',
confirm_new_contact: true,
});When the recipient answers, the service states who is calling using your project name, speaks your message, gives your contact info, and hangs up. Your number displays as the caller ID.
Synthetic speech counts legally as an artificial voice, so recipient consent is required. Automated marketing calls are prohibited. When placing the first call to someone you have not previously contacted, pass confirm_new_contact: true (or --yes in the CLI) after confirming they agreed to receive calls. Calls are subject to federal quiet hours between 8:00 AM and 9:00 PM in the recipient's time zone.
Running an AI voice agent on the number
Instead of reciting a static text message, your number can run a two-way AI voice agent. See an AI voice agent that makes phone calls and how to give an AI agent a phone number: texts, calls and a voice agent.
Outbound agent calls
Provide a mission prompt for the conversation:
vibiz phone call +14155550123 \
--prompt "Confirm if the guest wants indoor or patio seating tonight." \
--language en \
--max-minutes 5 \
--yesThe system automatically opens the call by stating that an AI assistant is calling, naming the project, stating that the call is transcribed, and explaining how to reach you. The agent never claims to be human, and the call is terminated when max_minutes is reached.
Once the call ends, inspect the result:
const done = await vibiz.phone.getCall(call.id);
console.log(done.summary);
console.log(done.outcome); // achieved, not_achieved, or unclear
console.log(done.transcript);Answering inbound calls
To have an AI agent answer incoming calls, set an answering prompt:
vibiz phone answer +14155550100 \
--prompt "Answer store hours and take table bookings." \
--max-minutes 5You can turn off answering at any time with vibiz phone answer +14155550100 --off.
Registering to send outbound texts
US carriers block application texts sent from unregistered numbers. Your number cannot send outbound SMS until carriers approve its registration. Use vibiz phone list to check sending_status:
sending_status | What it means |
|---|---|
registration_required | A local number requiring A2P 10DLC business registration. |
verification_required | A toll-free number requiring business verification. |
pending_review | Registration submitted; carriers usually take 1 to 2 weeks. |
approved | Registration approved; the number can send outbound SMS. |
rejected | Carriers rejected the registration; review the reason and resubmit. |
The registration form in the console asks for your legal business name, brand name, EIN (or sole proprietor registration with your mobile number), address, website, contact, messaging use case, two sample messages including opt-out instructions, and an explanation of how recipients give consent.
Once approved, send messages with the SDK or CLI:
await vibiz.phone.send({
to: '+14155550123',
text: 'Your order shipped. Reply STOP to unsubscribe.',
idempotency_key: 'order-101',
});Using a development key records the message as simulated at zero charge.
Pricing and billing
Phone usage is billed against your credits.
| Item | Cost |
|---|---|
| Local or toll-free number | About $1.32 / month |
| Outbound SMS (local) | $0.011 / segment |
| Outbound SMS (toll-free) | $0.013 / segment |
| Inbound SMS | $0.006 / segment |
| Outbound notification call | $0.012 / started minute (unanswered calls are free) |
| Voice agent call (either direction) | $0.095 / started minute (unanswered calls are free) |
| Business registration submission | $23.40 / submission, then $1.80 / month while approved |
| Sole proprietor registration submission | $23.40 / submission, then $2.40 / month while approved |
| Toll-free verification submission | Free |
A segment is 160 plain characters, or 70 characters with emojis. Number rent is deducted from credits three days before each month ends. If credits run out, the number enters a seven-day grace period where sending and calls pause but inbound texts continue. If credits are not added within seven days, the number is permanently released.
To cancel a number manually:
vibiz phone release +14155550100 --yesSystem limits and opt-outs
| Resource | Limit |
|---|---|
| Texts | 200 per project per UTC day |
| Text length | 1,600 characters |
| Calls | 50 per project per UTC day (up to 3 minutes each) |
| Voice agent calls | Up to 15 minutes each; 60 minutes per number per UTC day |
Call message (say) | 1,000 characters |
Voice agent prompt | 4,000 characters |
Voice agent first_message | 300 characters |
When someone replies STOP, UNSUBSCRIBE, CANCEL, END, QUIT, REVOKE, or OPT OUT, they are flagged across your entire account. Future outbound texts or calls to that contact return recipient_opted_out at no charge until they reply START.
Read the Phone documentation for additional API parameters and event payloads.
Frequently asked questions
Can an API key with Limited access purchase a phone number?
No. Purchasing, assigning, releasing, and registering numbers requires account owner permissions. A Limited key receives a console link for an owner to approve.
How long does carrier approval take for outbound texting?
Carrier review for A2P 10DLC local registrations and toll-free verifications usually takes one to two weeks after submission.
Do automated calls require carrier registration?
No. Carrier registration applies strictly to outbound SMS. Outbound notification calls and AI voice agents work immediately on active numbers, provided you obtain recipient consent and respect quiet hours.