---
title: "Update a phone"
method: PATCH
path: "/phones/{phone_id}"
tags: ["Phones"]
---

# Update a phone

`PATCH /phones/{phone_id}`

## Request

- Base URL: `https://api.axilio.ai/api/v1`
- URL: `https://api.axilio.ai/api/v1/phones/{phone_id}`
- Auth: API key in header `X-Axilio-Api-Key`
- TypeScript: <https://skmtc.dev/axilioai/apis/axilio-api-2/docs/phones/:phone_id/patch.ts> (a function with typed inputs; its response is checked against the schema)

Changes the fields a customer may set on a dedicated phone the caller's org owns: its nickname. Returns the updated phone.

## Path parameters

- `phone_id` string, required: device identifier

## Request body

- PhoneUpdatePhoneRequest: The fields to change on a dedicated phone.
  - `nickname` string, required: New display name for the phone.

## Response `200`

OK

- PhoneSummary: A phone in the fleet: display identity, status, and current allocation.
  - `created_at` string, date-time, required: When the phone record was created.
  - `current_session_id` string, nullable, required: Session currently holding the phone, if allocated.
  - `last_heartbeat_at` string, date-time, nullable, required: Time of the phone's most recent heartbeat.
  - `last_interaction_at` string, date-time, nullable, required: Time of the most recent interaction on the phone.
  - `location` string, nullable, required: Physical hosting location of the phone.
  - `messaging` PhoneMessaging: Whether a dedicated phone can send and receive texts, and whether the SIM it texts from is on the network, as the phone last reported.
    - `checked_at` string, date-time, nullable, required: When the phone last reported its state. Null when it never has.
    - `receiving` 'on' | 'off' | 'unknown', required: Whether texts the phone receives reach you. unknown until the phone reports its policy. Treat a value you don't recognize as unknown.
    - `sending` 'on' | 'off' | 'unknown', required: Whether the phone may send texts. unknown until the phone reports its policy. Treat a value you don't recognize as unknown.
    - `service` 'in_service' | 'no_service' | 'radio_off' | 'no_sim' | 'unknown', required: Whether the SIM the phone texts from is on the network. no_service covers out of service and emergency calls only; unknown until the phone reports it. Treat a value you don't recognize as unknown.
  - `model_id` string, nullable, required: Hardware model identifier.
  - `model_name` string, nullable, required: Hardware model name.
  - `nickname` string, nullable, required: User-assigned nickname.
  - `owner_organization_id` string, nullable, required: Owning organization, for private phones.
  - `ownership_type` 'shared' | 'private', required: 'shared' for pool phones, 'private' for dedicated rentals.
  - `phone_id` string, required: Phone identifier used by allocate and the phone APIs.
  - `phone_name` string, nullable, required: Display name of the phone.
  - `phone_number` string, nullable, required: The phone's own number in E.164, for a dedicated phone your organization rents: what its SIM reports, or else the number its latest received text was sent to. Null when neither is known, and for shared phones.
  - `phone_type` 'android' | 'iphone' | 'unknown', nullable, required: Platform of the phone.
  - `rental_expires_at` string, date-time, nullable, required: When the current rental ends, for rented phones.
  - `status` 'active' | 'inactive' | 'maintenance' | 'suspended' | 'recovering' | 'out_of_service', required: Fleet status of the phone. Only active is allocatable. inactive: unreachable, back on its next heartbeat. maintenance: planned work that releases itself. suspended: an administrative hold. recovering: being repaired automatically. out_of_service: needs a repair at the rack. Treat unknown values as unavailable.
  - `updated_at` string, date-time, required: When the phone record was last updated.

## Other responses

- `404`: Not Found
- `422`: Unprocessable Entity
- `500`: Internal Server Error

## Changes

- **2026-10-24** `ecca093572e0`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/axilioai/apis/axilio-api-2/changes/phones/:phone_id/patch.md)

---

[API](https://skmtc.dev/axilioai/apis/axilio-api-2.md) - [All operations](https://skmtc.dev/axilioai/apis/axilio-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/axilioai/apis/axilio-api-2/revisions/62aa324803a7?raw)