thelastapi
Get started free

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:

Terminal
vibiz phone search --area-code 415 --limit 5
vibiz phone search --type toll_free --limit 5

The 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:

Terminal
vibiz phone buy +14155550100 --project prj_123

A 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:

Terminal
# Move to another project
vibiz phone assign +14155550100 --project prj_456

# Detach back to the account level
vibiz phone assign +14155550100

To see all numbers owned by your account or filtered by project, check the list command:

Terminal
vibiz phone list --project prj_123

What 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:

TypeScript
// 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:

Terminal
vibiz phone messages --number +14155550100

Only 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.

TypeScript
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:

Terminal
vibiz phone call +14155550123 \
  --prompt "Confirm if the guest wants indoor or patio seating tonight." \
  --language en \
  --max-minutes 5 \
  --yes

The 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:

TypeScript
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:

Terminal
vibiz phone answer +14155550100 \
  --prompt "Answer store hours and take table bookings." \
  --max-minutes 5

You 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_statusWhat it means
registration_requiredA local number requiring A2P 10DLC business registration.
verification_requiredA toll-free number requiring business verification.
pending_reviewRegistration submitted; carriers usually take 1 to 2 weeks.
approvedRegistration approved; the number can send outbound SMS.
rejectedCarriers 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:

TypeScript
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.

ItemCost
Local or toll-free numberAbout $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 submissionFree

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:

Terminal
vibiz phone release +14155550100 --yes

System limits and opt-outs

ResourceLimit
Texts200 per project per UTC day
Text length1,600 characters
Calls50 per project per UTC day (up to 3 minutes each)
Voice agent callsUp to 15 minutes each; 60 minutes per number per UTC day
Call message (say)1,000 characters
Voice agent prompt4,000 characters
Voice agent first_message300 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.