How to update or delete a phone with the API

Once a phone exists, the update_phone function both edits it and deletes it. It is one call on the same endpoint as add_phone, and a single flag decides whether you are changing fields or removing the entry. Like the rest of the Non-agent API, it runs over a plain HTTP request to non_agent_api.php.

As with adding, the API (application programming interface) user needs user_level 8 or higher and "ast admin access" enabled, or the call returns a permission error.

Identifying the phone

update_phone needs only two required fields to find the entry: extension and server_ip. The Extension tells it which phone, the server_ip tells it which box. If the pair does not match an existing entry you get PHONE DOES NOT EXIST ON THIS SERVER.

Everything else is an editable field you only send when you want to change it. That includes dialplan_number, phone_login, phone_pass, protocol, registration_password, phone_full_name, outbound_cid, phone_context, email, and phone_ring_timeout, among others. Send only the fields you are changing — if you send nothing editable, the call returns NO UPDATES DEFINED.

This partial-update behavior is the useful part. You can flip a single phone to a new outbound_cid, bump its ring timeout, or rename it without touching anything else on the entry. Each editable field is validated on its own, so a bad value in one field is rejected with a specific error while the call leaves the rest of the phone untouched.

Deleting instead of editing

To delete a phone, send the same call with delete_phone=Y. You still need extension and server_ip so it knows which entry to remove. The default is N, so a normal edit never deletes by accident.

flowchart TD
  A[Call update_phone] --> B[Send extension and server_ip]
  B --> C{delete_phone equals Y}
  C -->|Yes| D[Phone removed]
  C -->|No| E{Any editable field sent}
  E -->|No| F[No updates defined]
  E -->|Yes| G[Fields validated]
  G --> H[Phone updated]

Deleting a phone over the API is a permission of its own. If the user is allowed to update but not delete, you get NOTICE: USER DOES NOT HAVE PERMISSION TO DELETE PHONES and the entry stays. That is a useful guard for accounts that should edit but never remove SIP peer entries.

Reading the response

An edit returns SUCCESS: update_phone PHONE HAS BEEN UPDATED, a delete returns PHONE HAS BEEN DELETED. Validation errors are specific — an invalid dialplan number, a bad timezone, or a ring timeout outside the 2 to 180 second range each come back as their own plain line, so a script can tell exactly what was rejected. To do the same job from the admin screen, see how to modify a phone, and for the wider picture read the phones and aliases guide.

VICIfast keeps the dialer and its API running for you — see pricing.