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

# Extensions API — Manage SIP User Accounts Per Tenant

> Manage SIP extensions via REST API. Create, list, update, and delete extensions assigned to tenants in the LaraCopilot cloud platform.

Extensions represent individual SIP user accounts within a tenant. Each extension has a unique `extension_number` scoped to its tenant, a SIP `secret` used for device registration, and an optional voicemail mailbox. All endpoints require an active admin session. The list endpoint accepts an optional `search` parameter that matches against `extension_number`, `display_name`, and `email`. List responses include the associated `tenant` and registered `devices` objects. The show endpoint additionally loads `queueAgents` and `cdrs` relations.

***

## GET /api/extensions

Returns all extensions ordered by creation date descending.

**Query parameters**

<ParamField query="search" type="string">
  Optional. Filters extensions whose `extension_number`, `display_name`, or `email` contains the given string (case-insensitive).
</ParamField>

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

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

  <Expandable title="extension 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 extension belongs to.
    </ResponseField>

    <ResponseField name="data[].extension_number" type="string">
      The dialable extension number, e.g. `"1001"`.
    </ResponseField>

    <ResponseField name="data[].display_name" type="string">
      Human-readable label for the extension, e.g. `"Alice Smith"`.
    </ResponseField>

    <ResponseField name="data[].email" type="string|null">
      Email address associated with this extension. Used for voicemail-to-email delivery.
    </ResponseField>

    <ResponseField name="data[].secret" type="string">
      SIP registration secret (password). Treat this value as sensitive.
    </ResponseField>

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

    <ResponseField name="data[].voicemail_enabled" type="boolean">
      Whether voicemail is enabled for this extension.
    </ResponseField>

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

    <ResponseField name="data[].devices" type="array">
      Array of registered device objects for this extension.
    </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/extensions \
    -H "Accept: application/json" \
    -b cookies.txt
  ```

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

  ```json 200 Response theme={null}
  {
    "message": "Extensions fetched successfully.",
    "data": [
      {
        "id": 1,
        "tenant_id": 1,
        "extension_number": "1001",
        "display_name": "Alice Smith",
        "email": "alice@acme.com",
        "secret": "s3cr3tpass",
        "status": "active",
        "voicemail_enabled": true,
        "tenant": { "id": 1, "name": "Acme Corp" },
        "devices": [],
        "created_at": "2025-02-01T08:00:00.000000Z",
        "updated_at": "2025-02-01T08:00:00.000000Z"
      }
    ]
  }
  ```
</CodeGroup>

***

## POST /api/extensions

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

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

<ParamField body="extension_number" type="string" required>
  The dialable extension number, e.g. `"1001"`. Maximum 20 characters.
</ParamField>

<ParamField body="display_name" type="string" required>
  Human-readable label for the extension. Maximum 255 characters.
</ParamField>

<ParamField body="email" type="string">
  Optional. Valid email address for voicemail-to-email. Maximum 255 characters.
</ParamField>

<ParamField body="secret" type="string" required>
  SIP registration password used by devices to authenticate. Maximum 255 characters.
</ParamField>

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

<ParamField body="voicemail_enabled" type="boolean">
  Optional. Whether voicemail is enabled. Coerced to a boolean; defaults to `false` when omitted.
</ParamField>

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

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

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST https://your-instance.laracopilot.com/api/extensions \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -b cookies.txt \
    -d '{
      "tenant_id": 1,
      "extension_number": "1002",
      "display_name": "Bob Jones",
      "email": "bob@acme.com",
      "secret": "p@ssw0rd99",
      "status": "active",
      "voicemail_enabled": true
    }'
  ```

  ```json 201 Response theme={null}
  {
    "message": "Extension created successfully.",
    "data": {
      "id": 2,
      "tenant_id": 1,
      "extension_number": "1002",
      "display_name": "Bob Jones",
      "email": "bob@acme.com",
      "secret": "p@ssw0rd99",
      "status": "active",
      "voicemail_enabled": true,
      "created_at": "2025-04-22T10:15:00.000000Z",
      "updated_at": "2025-04-22T10:15:00.000000Z"
    }
  }
  ```
</CodeGroup>

***

## GET /api/extensions/{extension}

Fetches a single extension by its ID. The response includes the `tenant`, `devices`, `queueAgents`, and `cdrs` relations.

**Path parameters**

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

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

<ResponseField name="data" type="object">
  The extension record with `tenant`, `devices`, `queueAgents`, and `cdrs` arrays included.
</ResponseField>

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

  ```json 200 Response theme={null}
  {
    "message": "Extension loaded successfully.",
    "data": {
      "id": 2,
      "tenant_id": 1,
      "extension_number": "1002",
      "display_name": "Bob Jones",
      "email": "bob@acme.com",
      "secret": "p@ssw0rd99",
      "status": "active",
      "voicemail_enabled": true,
      "tenant": { "id": 1, "name": "Acme Corp" },
      "devices": [],
      "queueAgents": [],
      "cdrs": [],
      "created_at": "2025-04-22T10:15:00.000000Z",
      "updated_at": "2025-04-22T10:15:00.000000Z"
    }
  }
  ```
</CodeGroup>

***

## PUT /api/extensions/{extension}

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

**Path parameters**

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

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

<ParamField body="extension_number" type="string" required>
  Maximum 20 characters.
</ParamField>

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

<ParamField body="email" type="string">
  Optional. Valid email address. Maximum 255 characters.
</ParamField>

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

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

<ParamField body="voicemail_enabled" type="boolean">
  Optional. Coerced to boolean.
</ParamField>

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

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

<CodeGroup>
  ```bash Request theme={null}
  curl -X PUT https://your-instance.laracopilot.com/api/extensions/2 \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -b cookies.txt \
    -d '{
      "tenant_id": 1,
      "extension_number": "1002",
      "display_name": "Bob Jones",
      "email": "bob@acme.com",
      "secret": "newP@ss999",
      "status": "disabled",
      "voicemail_enabled": false
    }'
  ```

  ```json 200 Response theme={null}
  {
    "message": "Extension updated successfully.",
    "data": {
      "id": 2,
      "tenant_id": 1,
      "extension_number": "1002",
      "display_name": "Bob Jones",
      "email": "bob@acme.com",
      "secret": "newP@ss999",
      "status": "disabled",
      "voicemail_enabled": false,
      "created_at": "2025-04-22T10:15:00.000000Z",
      "updated_at": "2025-04-22T11:00:00.000000Z"
    }
  }
  ```
</CodeGroup>

***

## DELETE /api/extensions/{extension}

Permanently deletes the specified extension.

**Path parameters**

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

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

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

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