Update an extension

patch

https://api.emaktalk.com/api/v1/extensions/{extensionId}

Updates an extension in place: only the keys you send are written, so anything you omit keeps its current value. Changing the caller-ID name propagates to the extension's own device line and to the BLF labels for it on other phones. Pass expect for a safe read-modify-write — if a guarded value has changed since you read it, nothing is written and the call returns 409. Voicemail, device and follow-me changes are applied after the extension itself is written. Identity fields are not settable here: the extension's account, its call-routing id, and the ids of its devices and follow-me record are always taken from the stored extension, so sending them has no effect. A device or device line that is not on this extension's account is rejected rather than silently skipped.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

extensionId

string

required

The extension's UUID.

Body Params

effective_caller_id_name

string

Caller-ID name shown on internal calls; non-empty when present. Renaming propagates to the extension's device line and to BLF labels on other phones.

effective_caller_id_number

string

Caller-ID number shown on internal calls; non-empty when present.

outbound_caller_id_name

string | null

Caller-ID name presented on outbound calls. An empty string is stored as null.

outbound_caller_id_number

string

Caller-ID number presented on outbound calls; non-empty when present.

directory_first_name

string | null

Given name used in the dial-by-name directory.

directory_last_name

string | null

Family name used in the dial-by-name directory.

directory_visible

boolean

Whether the extension appears in the dial-by-name directory.

directory_exten_visible

boolean

Whether the extension's number is shown in the directory.

missed_call_app

string | null

Missed-call notifier; setting it requires missed_call_data.

missed_call_data

string | null

Where the missed-call notice goes, such as an email address.

toll_allow

string | null

Calling permissions. Requires an API key with the Admin role; it is ignored otherwise.

call_timeout

number | null

Seconds the extension rings before the call stops ringing.

call_group

string | null

Call group the extension belongs to.

call_screen_enabled

boolean

Whether callers are screened before the extension rings.

user_record

string | null

Call recording mode. Requires an API key with the Admin role.

hold_music

string | null

Hold music source used when this extension puts a caller on hold.

mwi_account

string | null

Account the message-waiting indicator follows.

do_not_disturb

boolean

Whether the extension is in do-not-disturb.

forward_all_enabled / forward_all_destination

string

Whether every call is forwarded, and where it goes.

forward_busy_enabled / forward_busy_destination

string

Whether calls are forwarded when the extension is busy, and where they go.

forward_no_answer_enabled / forward_no_answer_destination

string

Whether calls are forwarded when nobody answers, and where they go.

forward_user_not_registered_enabled / forward_user_not_registered_destination

string

Whether calls are forwarded when no device is registered, and where they go.

follow_me_enabled / follow_me_uuid / follow_me_destinations / forward_caller_id_uuid

string

Follow-me configuration for the extension.

follow_me

object

Structured follow-me payload, written after the extension itself is updated.

enabled

boolean

Enables or disables the extension. Re-enabling a disabled extension consumes a licensed seat and is refused with 403 when none is left.

description

string | null

Free-text description.

type_of_extension

string

Extension type; stored as ext_type.

voicemail

object

Voicemail changes, applied after the extension itself is updated: enabled: false force-disables the mailbox and enabled: true re-enables it.

devices

string

Device and line changes. Requires an API key with the Admin role.

expect

object

Compare-and-set guard mapping updatable field names to the values you last read (scalars or null). The write happens only if they all still match, otherwise nothing is written and the call returns 409. Naming a field that cannot be patched, or guarding a body with no field changes, is 400 (code invalid_expect).

password

string

Not settable through this API; ignored if sent — rotating the SIP password would unregister the user's phones.

emergency_caller_id_name / emergency_caller_id_number

string

Not settable through this API; ignored if sent.

sip_bypass_media

string

Not settable through this API; ignored if sent.

Responses

401

Missing or invalid API key.

Language

Credentials

Bearer

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200The extension was updated; cache_flush reports whether the phone servers picked the change up immediately, and the change is saved either way.

400Bad UUID, an invalid expect, invalid field values, or the write failed.

403Your API key neither administers this extension's account nor owns the extension, or re-enabling it would exceed your licensed seats.

404No extension has that id.

409An expect value no longer matched, so nothing was written; details.mismatched names the fields that changed.

500The license check failed.