> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone Numbers (DIDs)

> Buy, port, and configure Direct Inward Dialing numbers

DIDs (Direct Inward Dialing numbers) are the actual phone numbers your business uses — what customers dial to reach you and what you display on outbound caller ID. Hiveku provides DIDs in 60+ countries through Telnyx, supports porting in your existing numbers, and gives you fine-grained routing and SMS control on each number.

Manage DIDs in `/dashboard/communications/` under the **Numbers** tab.

## Buying numbers

<Steps>
  <Step title="Pick country and region">
    United States, Canada, UK, Australia, Germany, and 60+ more. Pricing varies by country.
  </Step>

  <Step title="Pick number type">
    Local, toll-free, or international. See the comparison below.
  </Step>

  <Step title="Search">
    By area code (415, 212, 888), by digit pattern (`*555*`), or by vanity word (`1-800-FLOWERS`).
  </Step>

  <Step title="Verify E911 address">
    Required before activation. See [Compliance](/communications/compliance#e911).
  </Step>

  <Step title="Configure routing">
    Pick what happens when this number rings — extension, ring group, IVR, queue, or AI agent.
  </Step>
</Steps>

## Number types

<Tabs>
  <Tab title="Local">
    Geographic numbers — area code 415, 212, 312, etc. Customers see a local presence. Lowest monthly cost. Both voice and SMS available on most local DIDs in the US and Canada.

    Best for: regional sales teams, support hotlines for a specific city, businesses where location matters.
  </Tab>

  <Tab title="Toll-free">
    1-800, 1-888, 1-877, 1-866, 1-855, 1-844, 1-833 prefixes. Higher monthly cost; per-minute inbound is paid by the business, not the caller. SMS-capable but requires 10DLC-equivalent toll-free verification (auto-handled by Hiveku).

    Best for: national businesses, customer service hotlines, brands that want a polished look.
  </Tab>

  <Tab title="International">
    UK 020, German 030, Australian 02, etc. Local presence in foreign markets without opening a foreign office. Some countries require a local registered address — Hiveku will prompt during purchase.

    Best for: businesses serving multiple countries.
  </Tab>

  <Tab title="Vanity">
    Numbers spelling words on a phone keypad — 1-800-FLOWERS, 1-866-MY-LAWYER. Searchable by typing a word in the search field. Premium pricing.

    Best for: memorable brand numbers, billboard advertising, radio spots.
  </Tab>
</Tabs>

## Number capabilities

Each DID supports a subset of capabilities depending on country and provisioning:

| Capability | Description                             |
| ---------- | --------------------------------------- |
| Voice      | Inbound and outbound calls              |
| SMS        | Send and receive text messages          |
| MMS        | Send and receive picture/video messages |
| Fax        | Inbound fax (T.38) — older lines only   |

The Numbers tab shows a capability badge on each DID. SMS on US/Canada local numbers requires 10DLC registration — handled automatically when you buy the number, but final approval can take 1-3 days.

<Warning>
  Until 10DLC approval completes, SMS on a new US local number is rate-limited to about 1 message per second and may be filtered by carriers. Toll-free SMS goes through a separate verification flow.
</Warning>

## Porting in existing numbers

Bring your current business number into Hiveku without losing it.

<Steps>
  <Step title="Start the port">
    From the Numbers tab, click **Port a number**. Enter the number, your current carrier, and account info.
  </Step>

  <Step title="Submit LOA">
    Letter of Authorization — Hiveku generates a pre-filled PDF. Sign and upload.
  </Step>

  <Step title="Wait for carrier approval">
    Typically 5-10 business days for US/Canada, longer for some international. Status visible in the Numbers tab.
  </Step>

  <Step title="Cutover">
    On the scheduled date, the number activates on Hiveku. Set up routing **before** the cutover so calls have somewhere to go.
  </Step>
</Steps>

<Tip>
  Don't cancel your current carrier until **after** the port completes. Canceling early is the most common cause of port failures.
</Tip>

## Routing a DID

Each number routes inbound calls to one destination. From the number's detail page, pick:

<CardGroup cols={2}>
  <Card title="Extension" icon="phone-office">
    Direct to one user's desk phone, mobile, or browser softphone. Best for personal lines and small teams.
  </Card>

  <Card title="Ring group" icon="users">
    Multiple extensions ring (sequential, simultaneous, round-robin). See [Ring Groups](/communications/ring-groups).
  </Card>

  <Card title="IVR menu" icon="list-tree">
    "Press 1 for sales" auto-attendant. See [IVRs](/communications/ivr).
  </Card>

  <Card title="Queue" icon="users-line">
    Caller waits with hold music until an agent is free. See [Queues](/communications/queues).
  </Card>

  <Card title="AI agent" icon="microphone">
    The AI answers and handles the conversation. See [AI Voice Agent](/communications/voice-ai-agent).
  </Card>

  <Card title="Forward externally" icon="arrow-right-from-bracket">
    Forward to another number — your cell, an answering service, or a third-party carrier.
  </Card>
</CardGroup>

## Failover

Set a fallback for what happens when the primary route fails or doesn't answer in N seconds:

```
Primary: Ring Group "Sales" (30 sec timeout)
Failover 1: Queue "Sales Hold"
Failover 2: Forward to +1-555-after-hours
```

Common pattern: ring group → queue → voicemail.

## Number pools

A DID pool is a group of outbound numbers used in rotation to mitigate spam labels. Carriers and call-blocking services flag numbers that make too many outbound calls in a short window — rotation across a pool keeps each number under the threshold.

<Steps>
  <Step title="Add multiple DIDs">
    Buy 5-10 local numbers in the same area code as your team's outbound dialing target.
  </Step>

  <Step title="Create a pool">
    From the **Pools** tab, create a pool and add the DIDs.
  </Step>

  <Step title="Assign to outbound">
    Configure your outbound calling profile (per-extension or per-team) to use the pool. Calls rotate automatically.
  </Step>
</Steps>

<Info>
  Spam mitigation is most useful for outbound sales teams making 50+ calls/day per rep. For low-volume use, a single DID is fine.
</Info>

## Forwarding and failover

Forward a DID to an external number when:

* You're transitioning between providers
* After-hours calls go to an answering service
* A specific number always rings to a cell

Forwarded calls use Hiveku's outbound trunk, so per-minute charges apply on top of inbound. Set a forwarding caller-ID to either the original caller or your own DID.

## API

```bash theme={null}
# Search available numbers
curl -X POST https://api.hiveku.com/api/communications/numbers/search \
  -H "Authorization: Bearer hk_live_xxx" \
  -d '{"country": "US", "area_code": "415", "type": "local"}'

# Buy a number
curl -X POST https://api.hiveku.com/api/communications/numbers \
  -H "Authorization: Bearer hk_live_xxx" \
  -d '{"phone_number": "+14155551234", "e911_address_id": "addr_01HQ"}'

# List your numbers
curl https://api.hiveku.com/api/communications/numbers \
  -H "Authorization: Bearer hk_live_xxx"
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="My new number isn't receiving calls">
    Check that E911 verification completed and a route is configured. Newly purchased numbers can take up to 15 minutes to fully activate on the carrier network.
  </Accordion>

  <Accordion title="Outbound calls show as 'Spam Likely'">
    Use a number pool for high-volume outbound, register your business with the FCC's STIR/SHAKEN attestation (auto-handled), and avoid making calls flagged by call-blocking apps.
  </Accordion>

  <Accordion title="Port is stuck in 'pending carrier'">
    Most ports complete in 5-10 business days. If it's been longer, the most common cause is a mismatch on the LOA — name on the account, billing address, or PIN doesn't match the losing carrier's records exactly. Contact support to review.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Buy and configure" icon="rocket" href="/how-tos/buy-phone-number">
    Walkthrough for first-time number setup.
  </Card>

  <Card title="Extensions" icon="phone-office" href="/communications/extensions">
    Connect a phone to take calls.
  </Card>
</CardGroup>