# Number Provisioning

> Give your voice service a reachable address: bring your own DID over a SIP trunk, use your per-tenant SIP subdomain, or buy from the managed catalog. Then assign the address to a trunk, agent, or flow.

Give callers a way to reach your voice service. There are three routes to an
address. The routes are not equally finished, so start with the one that is
production-ready today:

| Route | What you get | Status |
|-------|--------------|--------|
| **Per-tenant SIP subdomain** | A ready-to-use address `<orgId>.sip.firstbyte.fast`, provisioned when your workspace is created. You need no carrier and no purchase. | **Shipped** |
| **Bring your own numbers (DID)** | Your existing carrier DIDs, pointed at a SIP trunk and imported into the number registry. | **Shipped** |
| **Buy from the managed catalog** | Search for a new DID from an upstream carrier and purchase it through FirstByte. | **Preview / stub** |

The last step is the same for all three routes: **assign** the address to
a trunk, an agent, or a routing flow, so that inbound calls land somewhere.
This page is really about that mapping.

> **NOTE:**
> The **managed "buy a number" catalog is a stub today**. Search returns a
> small demo set (India-only, a placeholder catalog provider), pending live
> Twilio / Telnyx / Bandwidth integration. The **allocation registry is real,
> and the inbound routing that reads it is real**. A number that you import by
> hand behaves exactly like a purchased one will. If you need a live number now,
> bring your own DID (below).

## Your tenant already has an address

Every workspace gets a **per-tenant SIP subdomain** at onboarding. Org
bootstrap creates CNAMEs for `<orgId>.sip.firstbyte.fast` (SIP),
`<orgId>.webrtc.firstbyte.fast` (browser media), and the bare
`<orgId>.firstbyte.fast`. All of them point at the voice engine. When a call
arrives, the engine reads the **leftmost DNS label** of the inbound SIP
request as the tenant id. Multiple tenants share the engine with no
cross-tenant extension collisions.

You do not provision this subdomain. It exists the moment your org does. It is
the SIP realm that your agent endpoints register against. It is also the host
that a carrier or upstream SBC points its trunk at. See
[SIP trunking](/modalities/voice/transport-telephony/sip-trunking) for the
trunk side. See [PBX & ACD](/modalities/voice/transport-telephony/pbx-acd) for
how to register human-agent phones under that realm.

> **TIP:**
> A per-tenant SIP subdomain is enough to place and receive SIP calls
> internally (softphones, deskphones, on-net dialing). You only need a **DID** —
> a real E.164 phone number — when you want the public phone network to reach
> you.

## Bring your own numbers (DID)

This is the production path. You already own DIDs from a carrier. You keep them
and point them at FirstByte. There are two parts: make the carrier deliver
calls to a trunk, then register the number so the engine knows where to route
it.

  1. **Create a trunk for the carrier**
Configure a SIP trunk that terminates your carrier (or SBC). Match the
    trunk by the carrier's source IP or by the DID that it delivers. Set its
    inbound rule so that calls hand off to an agent or a flow, not to a
    rejection. See [Trunks](/admin/trunks) for every field. See
    [SIP trunking](/modalities/voice/transport-telephony/sip-trunking) for the
    addressing and codec setup.
  2. **Point the carrier at your SIP subdomain**
In your carrier's dashboard, route the DID's inbound calls to
    `<orgId>.sip.firstbyte.fast` (or to the trunk's advertised SIP IP). The
    engine matches trunk INVITEs by source IP, and they bypass the registrar
    ACL.
  3. **Import the number into the registry**
Register the E.164 number in the allocation registry. Set its `provider`
    to `manual` (a BYO import). Set a `trunk_id` so that inbound calls on the
    number resolve to that trunk. Inbound routing reads this record on every
    call.
  4. **Verify inbound routing**
Place a test call to the DID. The engine resolves the trunk by DID first,
    then by source IP. The engine then follows the trunk's inbound rule. Check
    that the call lands where you assigned it (see
    [Inbound calls](/modalities/voice/transport-telephony/inbound)).

A registry entry is one row, keyed uniquely per `(org, e164)`:

- **`e164`** (`string`, required) — The number in E.164 form, e.g. `+15551234567`. Unique within your org.
- **`provider`** (`'twilio' | 'telnyx' | 'manual'`) — The source of the number. `manual` = a bring-your-own DID that you imported. The managed catalog sets `twilio` / `telnyx` when that catalog ships.
- **`number_type`** (`string`) — The classification (e.g. local, toll-free, mobile). The system carries it for reporting and compliance, not for routing.
- **`country`** (`string`) — The ISO country of the number.
- **`trunk_id`** (`string`) — The trunk that this number routes over. Set it for BYO DIDs so that inbound calls resolve to your carrier trunk.
- **`agent_id`** (`string`) — Optional. Bind the number directly to an AI agent. A call to the number starts that agent with no intermediate flow.
- **`vdn_id`** (`string`) — Optional. Route the number into a **VDN** (a routing flow / IVR entry point) instead of straight to an agent. The usual choice is to set exactly one of `agent_id` / `vdn_id`.
- **`status`** (`string`) — The lifecycle state of the allocation (active, released, …).

## Buy from the managed catalog

This is the eventual one-click path. You search available numbers by country
and type, and you purchase one. The system then provisions the DID onto a
managed trunk automatically.

> **WARNING:**
> **This is a preview.** The number-search endpoint
> (`telephony.searchAvailableNumbers`) is wired end to end. The catalog
> behind it is a **stub**: it returns a fixed demo set (India-only, a
> placeholder catalog provider), not live carrier inventory. Treat search
> results as sample data. The purchase-and-provision leg against a real carrier
> (Twilio / Telnyx / Bandwidth) is not shipped yet. Everything *downstream* of
> allocation — the registry row, assignment, and inbound routing — is real and
> identical to the BYO path. Your integration code will not change when live
> inventory lands.

When the catalog goes live, it will populate the same registry record shown
above, with `provider` set to the upstream carrier. Build against that shape
now.

## Assign a number

Assignment makes a number *do* something. Every allocated number
points at exactly one destination. Pick the destination that matches how much
routing logic you want in front of the caller:

  
    Set `trunk_id`. The engine delivers inbound calls on the number over that
    trunk. The calls follow the trunk's own inbound rule. This is the baseline
    for a BYO DID: the number is reachable and lands on your carrier edge, and
    the trunk decides the rest.
  
  
    Set `agent_id`. A call to the number starts that AI agent immediately,
    with no menu and no queue. This is best for a single-purpose line (one
    bot, one number). The server resolves the bound agent DAG. See
    [Build voice agents](/modalities/voice/build/voice-agents).
  
  
    Set `vdn_id`. The number enters a **VDN** — a routing flow that can play
    announcements, collect digits, and queue to a skill before the engine
    bridges in anyone (bot or human). Use this when a number fronts a menu or
    a contact-center queue. See
    [PBX & ACD](/modalities/voice/transport-telephony/pbx-acd).
  

The registry is **default-private control-plane state**. Manage it from the
Contact Center console at `agent.firstbyte.fast`, or from the control-plane API. Do not
manage it from the data-plane Voice SDK. The SDK's `Voice` client places and
controls calls. It does not buy or assign numbers. The system hydrates
assignments to the engine, so a change takes effect on the next inbound call
without a redeploy.

> **NOTE:**
> **One number, one primary destination.** If you set both `agent_id` and
> `vdn_id`, the result is ambiguous. Choose the level of indirection that you
> want (straight-to-agent or flow-first) and set one. `trunk_id` governs *how
> the call arrives*. `agent_id` / `vdn_id` govern *what happens after it
> arrives*.

## Honest status

> **NOTE:**
> - **Per-tenant SIP subdomain provisioning** — shipped. The system creates it
>   automatically at org onboarding. The engine routes by the leftmost DNS label.
> - **Bring-your-own DID** — shipped. Import into the allocation registry with
>   `provider: "manual"` and a `trunk_id`. Inbound routing reads it live.
> - **Assign to trunk / agent / flow** — shipped. The registry is real, and so
>   is the inbound resolution that reads it.
> - **Managed buy-a-number catalog** — preview. Search works against a
>   **stub** (India-only demo inventory). Live carrier purchase-and-provision is
>   not yet built. Do not ship a self-serve "buy a number" flow on it.

## Related

  - **[SIP Trunking](/modalities/voice/transport-telephony/sip-trunking)** — Bring your own carrier or a managed trunk — addressing and codecs.
  - **[Trunks (control plane)](/admin/trunks)** — Every trunk field, including inbound rules and AI handoff.
  - **[Inbound Calls](/modalities/voice/transport-telephony/inbound)** — How the engine receives and routes a call on your number.
  - **[PBX & ACD](/modalities/voice/transport-telephony/pbx-acd)** — Front a number with a VDN, IVR, and skill-queue routing.
  - **[Build voice agents](/modalities/voice/build/voice-agents)** — Bind a number straight to an AI agent.
  - **[Telephony overview](/modalities/voice/transport-telephony/overview)** — How the phone network bridges into the voice stack.