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

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

```bash
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:

```bash
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:

```bash
# 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:

```bash
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`:

```ts
// 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:

```bash
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](https://thelastapi.dev/blog/reminder-calls-speak-message).

```ts
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](https://thelastapi.dev/blog/ai-voice-agent-phone-calls) and [how to give an AI agent a phone number: texts, calls and a voice agent](https://thelastapi.dev/blog/give-ai-agent-phone-number).

### Outbound agent calls

Provide a mission prompt for the conversation:

```bash
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:

```ts
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:

```bash
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_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:

```ts
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:

```bash
vibiz phone release +14155550100 --yes
```

## System 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](https://thelastapi.dev/docs/phone) 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.

---

Published 2026-11-15 · https://thelastapi.dev/blog/buy-us-phone-number-api
