---
title: "Add a desk phone by MAC address: creates its line, registers the phone, and seats it in the team ring group so it rings with the team and unanswered calls reach Kai. Refused (409 e911_address_required) until the office address is validated. Owner role (session) or numbers:write."
method: POST
path: "/v1/phone-system/desk-phones"
---

# Add a desk phone by MAC address: creates its line, registers the phone, and seats it in the team ring group so it rings with the team and unanswered calls reach Kai. Refused (409 e911_address_required) until the office address is validated. Owner role (session) or numbers:write.

`POST /v1/phone-system/desk-phones`

## Request

- Base URL: `https://www.kaicalls.com/api`
- URL: `https://www.kaicalls.com/api/v1/phone-system/desk-phones`
- Auth: HTTP bearer

## Request body

- object
  - `business_id` string, required
  - `mac_address` string
  - `name` string
  - `action` 'refresh' | 'attach_emergency_location', required: Send 'refresh' with device_id to reload settings. Send 'attach_emergency_location' to attach the provisioned main office location only when the phone has no location; existing locations are preserved. Both require owner role or numbers:write.
  - `device_id` string, required

## Response `200`

Phone added, settings reload requested, or emergency location verified by readback

## Other responses

- `400`: Invalid MAC address or missing name
- `409`: Duplicate phone, phone system not set up, or address not validated

---

[API](https://skmtc.dev/kaicalls/apis/kaicalls-public-api.md) · [All operations](https://skmtc.dev/kaicalls/apis/kaicalls-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kaicalls/apis/kaicalls-public-api/revisions/e607fc6cf36e?raw)