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

# Direct Inward Dialing (DID) Numbers

> DID numbers are inbound phone numbers assigned to your tenant that route calls to extensions, queues, or IVR menus in LaraCopilot.

A **DID (Direct Inward Dialing) number** is a public telephone number that the PSTN can deliver calls to. In LaraCopilot, DIDs are provisioned against a tenant and act as the entry point for all inbound traffic. When a caller dials a DID, LaraCopilot looks up the associated `DidRoute` records to decide where the call should go — an extension, a call queue, or an IVR menu. Each DID is sourced from a carrier or VoIP provider and carries a `status` that controls whether it is actively accepting calls.

## Key fields

| Field         | Type    | Description                                                                      |
| ------------- | ------- | -------------------------------------------------------------------------------- |
| `tenant_id`   | integer | The tenant this DID is assigned to. Required.                                    |
| `number`      | string  | The E.164 or local-format phone number (e.g. `+12125550100`). Max 50 characters. |
| `provider`    | string  | The carrier or SIP trunk supplying this number (e.g. `Twilio`, `Vonage`).        |
| `description` | string  | Optional free-text label to identify the number's purpose.                       |
| `status`      | string  | Operational state (e.g. `active`, `inactive`). Inactive DIDs do not route calls. |

## How DID routing works

Each DID can have one or more `DidRoute` records attached to it. Routes define the destination — an extension or a queue — and any conditions that govern when that destination applies (time of day, day of week, etc.). When an inbound call arrives, LaraCopilot evaluates the routes in order and forwards the call to the first matching destination.

<Note>
  A DID with no active routes will fail to connect inbound calls. Always configure at least one route before setting a DID's `status` to `active`.
</Note>

## API examples

### Create a DID

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://your-instance/api/dids \
    -H "Content-Type: application/json" \
    -d '{
      "tenant_id": 1,
      "number": "+12125550100",
      "provider": "Twilio",
      "description": "Main inbound line",
      "status": "active"
    }'
  ```

  ```json Response (201) theme={null}
  {
    "message": "DID created successfully.",
    "data": {
      "id": 10,
      "tenant_id": 1,
      "number": "+12125550100",
      "provider": "Twilio",
      "description": "Main inbound line",
      "status": "active",
      "created_at": "2026-04-22T10:10:00Z",
      "updated_at": "2026-04-22T10:10:00Z"
    }
  }
  ```
</CodeGroup>

### Retrieve a DID with its routes

<CodeGroup>
  ```bash cURL theme={null}
  curl https://your-instance/api/dids/10
  ```

  ```json Response (200) theme={null}
  {
    "message": "DID loaded successfully.",
    "data": {
      "id": 10,
      "tenant_id": 1,
      "number": "+12125550100",
      "provider": "Twilio",
      "description": "Main inbound line",
      "status": "active",
      "tenant": { "id": 1, "name": "Acme Corp" },
      "routes": []
    }
  }
  ```
</CodeGroup>

## Routing DIDs to extensions vs. queues

<CardGroup cols={2}>
  <Card title="Route to an extension" icon="user">
    Best for dedicated lines — a direct number that always rings a specific person's extension, such as an executive or a department head.
  </Card>

  <Card title="Route to a queue" icon="list">
    Best for shared lines — a support or sales number that distributes calls across a pool of available agents using the queue's configured strategy.
  </Card>
</CardGroup>

<Tip>
  Point high-volume inbound DIDs at a call queue rather than a single extension. Queues provide hold music, overflow handling, and agent-level reporting that a direct extension cannot.
</Tip>