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

# DID Numbers API — Assign and Manage DID Phone Numbers

> Manage Direct Inward Dialing (DID) phone numbers via REST API. Assign, update, and remove numbers from your tenants in LaraCopilot today.

DID numbers (Direct Inward Dialing) are publicly routable phone numbers assigned to a tenant. Each DID tracks the originating carrier or `provider`, an optional human-readable `description`, and a `status` indicating whether it is active and accepting inbound calls. All endpoints require an active admin session. The list endpoint supports an optional `search` parameter that filters across `number`, `provider`, and `description`. List and show responses include the parent `tenant` object and any configured `routes`.

***

## GET /api/dids

Returns all DID numbers ordered by creation date descending, with `tenant` and `routes` relations included.

**Query parameters**

<ParamField query="search" type="string">
  Optional. Filters DIDs whose `number`, `provider`, or `description` contains the given string (case-insensitive).
</ParamField>

<ResponseField name="message" type="string">
  Value is `"DIDs fetched successfully."`.
</ResponseField>

<ResponseField name="data" type="array">
  Array of DID objects.

  <Expandable title="DID object fields">
    <ResponseField name="data[].id" type="integer">
      Auto-incremented primary key.
    </ResponseField>

    <ResponseField name="data[].tenant_id" type="integer">
      ID of the tenant this DID is assigned to.
    </ResponseField>

    <ResponseField name="data[].number" type="string">
      The E.164-formatted phone number, e.g. `"+12125551234"`.
    </ResponseField>

    <ResponseField name="data[].provider" type="string">
      Name of the originating carrier or SIP trunk provider.
    </ResponseField>

    <ResponseField name="data[].description" type="string|null">
      Optional human-readable note about the DID's purpose.
    </ResponseField>

    <ResponseField name="data[].status" type="string">
      Lifecycle status, e.g. `active` or `inactive`.
    </ResponseField>

    <ResponseField name="data[].tenant" type="object">
      The parent tenant object.
    </ResponseField>

    <ResponseField name="data[].routes" type="array">
      Array of routing rule objects associated with this DID.
    </ResponseField>

    <ResponseField name="data[].created_at" type="string">
      ISO 8601 creation timestamp.
    </ResponseField>

    <ResponseField name="data[].updated_at" type="string">
      ISO 8601 last-updated timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl https://your-instance.laracopilot.com/api/dids \
    -H "Accept: application/json" \
    -b cookies.txt
  ```

  ```bash Request (with search) theme={null}
  curl "https://your-instance.laracopilot.com/api/dids?search=Twilio" \
    -H "Accept: application/json" \
    -b cookies.txt
  ```

  ```json 200 Response theme={null}
  {
    "message": "DIDs fetched successfully.",
    "data": [
      {
        "id": 1,
        "tenant_id": 1,
        "number": "+12125551234",
        "provider": "Twilio",
        "description": "Main inbound line",
        "status": "active",
        "tenant": { "id": 1, "name": "Acme Corp" },
        "routes": [],
        "created_at": "2025-02-10T09:00:00.000000Z",
        "updated_at": "2025-02-10T09:00:00.000000Z"
      }
    ]
  }
  ```
</CodeGroup>

***

## POST /api/dids

Creates a new DID number and returns `201 Created` with the record.

<ParamField body="tenant_id" type="integer" required>
  ID of the tenant to assign this DID to. Must reference an existing tenant.
</ParamField>

<ParamField body="number" type="string" required>
  The phone number string, e.g. `"+12125551234"`. Maximum 50 characters.
</ParamField>

<ParamField body="provider" type="string" required>
  The carrier or SIP trunk name, e.g. `"Twilio"` or `"Bandwidth"`. Maximum 255 characters.
</ParamField>

<ParamField body="description" type="string">
  Optional. Free-text description of the DID's purpose. No length limit enforced at the API layer.
</ParamField>

<ParamField body="status" type="string" required>
  Lifecycle status, e.g. `active` or `inactive`. Maximum 50 characters.
</ParamField>

<ResponseField name="message" type="string">
  Value is `"DID created successfully."`.
</ResponseField>

<ResponseField name="data" type="object">
  The newly created DID record.
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST https://your-instance.laracopilot.com/api/dids \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -b cookies.txt \
    -d '{
      "tenant_id": 1,
      "number": "+13125559876",
      "provider": "Bandwidth",
      "description": "Chicago sales line",
      "status": "active"
    }'
  ```

  ```json 201 Response theme={null}
  {
    "message": "DID created successfully.",
    "data": {
      "id": 2,
      "tenant_id": 1,
      "number": "+13125559876",
      "provider": "Bandwidth",
      "description": "Chicago sales line",
      "status": "active",
      "created_at": "2025-04-22T10:30:00.000000Z",
      "updated_at": "2025-04-22T10:30:00.000000Z"
    }
  }
  ```
</CodeGroup>

***

## GET /api/dids/{did}

Fetches a single DID by its ID. Includes the parent `tenant` and any configured `routes`.

**Path parameters**

<ParamField path="did" type="integer" required>
  The numeric ID of the DID to retrieve.
</ParamField>

<ResponseField name="message" type="string">
  Value is `"DID loaded successfully."`.
</ResponseField>

<ResponseField name="data" type="object">
  The DID record with `tenant` and `routes` relations included.
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl https://your-instance.laracopilot.com/api/dids/2 \
    -H "Accept: application/json" \
    -b cookies.txt
  ```

  ```json 200 Response theme={null}
  {
    "message": "DID loaded successfully.",
    "data": {
      "id": 2,
      "tenant_id": 1,
      "number": "+13125559876",
      "provider": "Bandwidth",
      "description": "Chicago sales line",
      "status": "active",
      "tenant": { "id": 1, "name": "Acme Corp" },
      "routes": [],
      "created_at": "2025-04-22T10:30:00.000000Z",
      "updated_at": "2025-04-22T10:30:00.000000Z"
    }
  }
  ```
</CodeGroup>

***

## PUT /api/dids/{did}

Replaces all fields on an existing DID. `PATCH /api/dids/{did}` is also accepted and uses the same handler.

**Path parameters**

<ParamField path="did" type="integer" required>
  The numeric ID of the DID to update.
</ParamField>

<ParamField body="tenant_id" type="integer" required>
  Must reference an existing tenant.
</ParamField>

<ParamField body="number" type="string" required>
  Maximum 50 characters.
</ParamField>

<ParamField body="provider" type="string" required>
  Maximum 255 characters.
</ParamField>

<ParamField body="description" type="string">
  Optional. Free-text description.
</ParamField>

<ParamField body="status" type="string" required>
  Maximum 50 characters.
</ParamField>

<ResponseField name="message" type="string">
  Value is `"DID updated successfully."`.
</ResponseField>

<ResponseField name="data" type="object">
  The updated DID record.
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl -X PUT https://your-instance.laracopilot.com/api/dids/2 \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -b cookies.txt \
    -d '{
      "tenant_id": 1,
      "number": "+13125559876",
      "provider": "Bandwidth",
      "description": "Chicago sales line — decommissioned",
      "status": "inactive"
    }'
  ```

  ```json 200 Response theme={null}
  {
    "message": "DID updated successfully.",
    "data": {
      "id": 2,
      "tenant_id": 1,
      "number": "+13125559876",
      "provider": "Bandwidth",
      "description": "Chicago sales line — decommissioned",
      "status": "inactive",
      "created_at": "2025-04-22T10:30:00.000000Z",
      "updated_at": "2025-04-22T11:45:00.000000Z"
    }
  }
  ```
</CodeGroup>

***

## DELETE /api/dids/{did}

Permanently deletes the specified DID number.

**Path parameters**

<ParamField path="did" type="integer" required>
  The numeric ID of the DID to delete.
</ParamField>

<ResponseField name="message" type="string">
  Value is `"DID deleted successfully."`.
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl -X DELETE https://your-instance.laracopilot.com/api/dids/2 \
    -H "Accept: application/json" \
    -b cookies.txt
  ```

  ```json 200 Response theme={null}
  {
    "message": "DID deleted successfully."
  }
  ```
</CodeGroup>