Add an Extension

Add and configure a SIP extension.

Request URL

POST {base_url}/{api_path}/extension/create?access_token={access_token}

Request parameters

Parameter Required Type Description
type Yes String Extension type.

Valid value: SIP
avatar No String The file ID of the extension's avatar.
Note:
  • You need to first upload the avatar file to the PBX, then pass the returned file ID in this parameter.
  • If this parameter is omitted, the extension will use the system default avatar.
first_name No String First name.
last_name No String Last name.
email_addr No String Email address.
Note: This parameter is required when vm_new_email_notify is set to 1 and vm_send_to is set to user_email.
mobile_number No String Mobile number.
Note: This parameter is required when vm_new_sms_notify is set to 1 and vm_sms_recipient_type is set to ext_mobile.
user_password Yes String User password.
Note:
  • Must contain numbers, uppercase, and lowercase letters.
  • Do not allow four consecutive digits, four same digits, extension number, first name, or last name.
role_id No Integer The ID of a user role.
Note: You can query user role's ID using Get Menu Options.
organization_list No Array <Organization_Info> The organization(s) to which the extension belongs.
Note: This parameter is required if the Organization Management feature is enabled.
title No String The job title of the extension user.
email_language No Striing The language of email notifications for the extension.

Valid value:

  • follow_system: The default system email language.
  • zh-cn: 简体中文 (Chinese Simplified)
  • en: English
  • ru: Pусский (Russian)
  • de: Deutsch (German)
  • fr: Française (French)
  • bp: Português Brasil (Portuguese Brazil)
  • it: Italiano (Italian)
  • tr: Türkçe (Turkish)
user_lang No String The language of the system prompts heard by the extension during a call.
Valid value: follow_system or one of the prompt language existed in PBX System Prompt (e.g. German).
Note: You can query the available system prompts using Get Menu Options.
vm_lang No String The language of the system prompts heard by caller when they access the extension's voicemail box.

Valid value: follow_system or one of the prompt language existed in PBX System Prompt (e.g. German).

Note: You can query the available system prompts using Get Menu Options.
number Yes String Extension number.
Note:
  • Only numbers are allowed.
  • The maximum character length is 11.
caller_id No String Caller ID.
Note:
  • Numbers, letters, and special characters ( ) . - + * # are allowed.
  • The maximum character length is 31.
reg_name Yes String Registration name.
Note: The maximum character length is 63.
reg_password Yes String Registration password.
Note:
  • Must contain numbers, uppercase, and lowercase letters.
  • Do not allow four consecutive digits, four same digits, extension number, first name, or last name.
concurrent_registrations Yes Integer IP phone concurrent registrations.
Valid value:
  • 1 (default)
  • 2
  • 3
  • 4
  • 5

emergency_caller_id

No

String

Emergency Outbound Caller ID.

enb_set_dod

No

Integer

Whether to allow the extension to select a specific DOD number and its corresponding trunk for outgoing calls.

Valid value:
  • 0: Disabled
  • 1: Enabled
presence_status Yes String The current presence status of the extension.

Valid value:

  • available: Available
  • away: Away
  • business_trip: Business Trip
  • do_not_disturb: Do Not Disturb (DND)
  • lunch: Lunch Break
  • off_work: Off Work
presence_list No Array <Presence_Setting> The list of the presence settings.
presence_mobile_prefix No String The dial-out prefix of the mobile number for the "Ring the Mobile Number Simultaneously" feature.
agent_id No String

The agent ID that will be announced in the greeting prompt to callers when their inbound calls are answered by queue agent.

By default, the extension number will be announced.

Note: Agent ID will be announced when Agent ID Announcement is enabled for queues on PBX web portal (Path: Call Features > Queue > Preferences > Announcement).
enb_vm No Integer Whether to enable the voicemail.

Valid value:

  • 0: Disable
  • 1: Enable
enb_vm_pin No Integer Whether to enable the voicemail PIN authentication.

Valid value:

  • 0: Disable
  • 1: Enable
vm_pin No String The PIN code to access voicemail.
new_vm_notification No String Whether the extension user will be notified when receiving a new voicemail message email, and how to notify.

Valid value:

  • no: Do not send email notifications.
  • with_attach: Send a notification email with the new voicemail message attached as a .wav file.
  • without_attach: Send a notification email without attaching the new voicemail message.
vm_new_email_notify No Integer Whether to enable the new voicemail email notification.

Valid value:

  • 0: Disable
  • 1: Enable
vm_send_to No String The type of target email address for new voicemail email notification.

Valid value:

  • user_email: Extension email address
  • custom_email: Custom email address
voice_email_addr No String The custom email address for new voicemail email notification.
Note: This parameter is required when vm_new_email_notify is set to 1 and vm_send_to is set to custom_email.
vm_email_with_audio No Integer Whether to attach the .wav audio file converted from the voicemail to the new voicemail email notification.

Valid value:

  • 0: No
  • 1: Yes
vm_new_sms_notify No Integer Whether to enable the new voicemail SMS notification.

Valid value:

  • 0: Disable
  • 1: Enable
vm_sms_with_audio No Integer Whether to attach the .wav audio file converted from the voicemail to the new voicemail SMS notification.

Valid value:

  • 0: No
  • 1: Yes
vm_sms_recipient_type No String The type of the recipient number.

Valid value:

  • ext_mobile: Extension mobile number
  • custom: Custom number
vm_sms_country_code No String The country/region code of the custom recipient number for new voicemail SMS notification.
Format
{code}-{country}
Example
86-cn
Note:
  • This parameter is required when vm_new_sms_notify is set to 1 and vm_sms_recipient_type is set to custom.
  • You can query the country name and code using Get Menu Options (menu = countrycode).
vm_sms_number No String The custom recipient number for new voicemail SMS notification.
Note:
  • This parameter is required when vm_new_sms_notify is set to 1 and vm_sms_recipient_type is set to custom.
  • The maximum character length is 31.
vm_sms_content_type No String The type of the content for new voicemail SMS notification.

Valid value:

  • default
  • custom
vm_sms_custom_content No String The custom content for new voicemail SMS notification.
Note:
  • This parameter is required when vm_new_sms_notify is set to 1 and vm_sms_recipient_type is set to custom.
  • The maximum character length is 1600.
vm_sms_loop_enb No Integer Whether to enable the repeat reminder for new voicemail SMS notification.

Valid value:

  • 0: Disable
  • 1: Enable
vm_sms_loop_interval No Integer The retry interval in minutes to send new voicemail SMS notification repeatedly.
Note:
  • This parameter is required when vm_new_sms_notify is set to 1 and vm_sms_loop_enb is set to 1.
  • An integer greater than or equal to 0 is allowed.
vm_sms_loop_max_times No Integer The maximum repeat count to send new voicemail SMS notification.
Note:
  • This parameter is required when vm_new_sms_notify is set to 1 and vm_sms_loop_enb is set to 1.
  • An integer from 0 to 30 is allowed.
vm_after_notification No String How to deal with the voicemail message after sending an email or a SMS message to notify the recipient.

Valid value:

  • no: Keep the voicemail message as unread.
  • mark_read: Mark the voicemail message as read.
  • delete: Delete the voicemail message.
    Note: This value is available only when at least one of the vm_email_with_audio and vm_sms_with_audio is set to 1.
enb_vm_play_datetime No Integer Whether to announce the message arrival time before playing the voicemail message.
  • 0: Disable
  • 1: Enable
vm_play_time_format No String Specify the time format for announcing the message arrival time.

Valid value:

  • follow_system: Follow the system setting (Set on System > Date and Time > Display Format > Time Display Format)
  • 12-hour: 12-hour format
  • 24-hour: 24-hour format
enb_missed_call_auto_reply No Integer Whether to enable the Auto-Reply Message for Missed Calls feature for the extension.

Valid value:

  • 0: Disable
  • 1: Enable
missed_call_auto_reply No Object <Missed_Call_Auto_Reply> The configuration for auto-reply messages on missed inbound extension calls.
Note: This parameter is required when enb_missed_call_auto_reply is set to 1.
enb_all_busy_mode_for_endpoints No Integer

Whether to forward new incoming calls to the Busy destination when any endpoint registered to the extension is busy on a call.

Valid value:

  • 0: Disabled
  • 1: Enabled
enb_all_reject_mode_for_endpoints No Integer Whether to stop ringing other endpoints when an incoming call is rejected on one of the endpoints (with the extension registered).

Valid value:

  • 0: Disable. When an incoming call is rejected on one endpoint, other endpoints still ring.
  • 1: Enable. When an incoming call is rejected on one endpoint, other endpoints stop ringing.
dtmf_mode No String DTMF mode.

Valid value:

  • rfc4733: RFC4733 (RFC2833)
  • info: Info
  • inband: Inband
  • auto: Auto
transport No String Transport protocol(s).

Valid value:

  • udp: UDP protocol
  • tcp: TCP protocol
  • tls: TLS protocol
Note:
  • Use commas to separate multiple protocols. For example, udp,tcp,tls; if this parameter is omitted, the default protocol is udp.
  • tcp is available only when the SIP TCP Port is enabled (Path: PBX Settings > SIP Settings > General > Basic); while tls is available only when the TLS is enabled (Path: PBX Settings > SIP Settings > TLS).
  • When multiple protocols are selected, the following priority rules are applied:
    • Linkus UC Clients / Auto-provisioned IP phones: TLS > TCP > UDP
    • Manually registered IP phones: Uses the phone's specified protocol if available; if not specified, follows the default priority (TLS > TCP > UDP).
enb_qualify No Integer Whether to enable Qualify.

Valid value:

  • 0: Disable
  • 1: Enable
enb_t38_support No Integer Whether to support T.38 fax.

Valid value:

  • 0: Disable
  • 1: Enable
enb_srtp No Integer Whether to enable SRTP.

Valid value:

  • 0: Disable
  • 1: Enable
enb_monitor_call_quality No Integer Whether to enable call quality monitoring.

Valid value:

  • 0: Disable
  • 1: Enable
monitoring_end_timestamp No Integer

The timestamp (in seconds) when call quality monitoring should end.

Note: This parameter is REQUIRED when enb_monitor_call_quality is set to 1.
disable_outb_call No Integer Whether to restrict the extension from making outbound calls.

Valid value:

  • 0: Allow to make outbound calls.
  • 1: NOT allowed to make outbound calls.
disable_outb_call_outside_business_hours No Integer Whether to restrict the extension from making outbound calls outside Business Hours.

Valid value:

  • 0: Allow to make outbound calls outside Business Hours.
  • 1: NOT allowed to make outbound calls outside Business Hours.
disable_international_call No Integer Whether to restrict the extension from making international calls.

Valid value:

  • 0: Allow to make international calls.
  • 1: NOT allowed to make international calls.
max_outb_call_duration No Integer Specify the maximum call duration of an outbound call made from the extension.

Valid value:

  • -1: Follow system setting (Set on PBX Settings > Preferences > Max Call Duration (s)).
  • 0: Unlimited.
  • Other value: The maximum call duration in seconds (1 - 9999999).
outbound_route_permission No Array <Integer> The unique ID(s) of outbound route(s) that the extension is allowed to use.
Note:
permitted_tfa_method No String

The verification methods available to the extension user when enabling 2FA.

Valid value:

  • all: Allow the extension user to use an authenticator application or email for verification.
  • validator: Allow the extension user to use an authenticator application only.
  • email: Allow the extension user to use email only.
make_tfa_mandatory No Integer Whether to require the extension user to use 2FA.

Valid value:

  • 0: Disable
  • 1: Enable
enb_mobile_client No Integer Whether to enable Linkus Mobile Client.

Valid value:

  • 0: Disable
  • 1: Enable
enb_desktop_client No Integer Whether to enable Linkus Desktop Client.

Valid value:

  • 0: Disable
  • 1: Enable
enb_web_client No Integer Whether to enable Linkus Web Client.

Valid value:

  • 0: Disable
  • 1: Enable
enb_pad_client No Integer Whether to enable Linkus Pad Client (SDK).

Valid value:

  • 0: Disable
  • 1: Enable
Note: This option takes effect ONLY when you have integrated the Linkus SDK for Android or Linkus SDK for iOS.
linkus_mobile_codec No String

Set codec for Linkus Mobile Client.

Valid value:

  • ulaw
  • alaw
  • ilbc
  • g722
  • g729
  • opus
client_conf_list No Array <Linkus_Clients_Setting> The list of the Linkus Clients settings.
moh No String

The music to be played to the caller when the extension user places a call on hold.

Valid value:

  • follow_system: Follow system setting (Set on PBX Settings > Voice Prompt > Prompt Preferences > Music on Hold).
  • Empty string: No music played.

  • Other value: The name of the MoH (Music on Hold) playlist.

    Note: You can query the name of MoH playlists using Query MoH Playlists.
call_forward_moh No String

The music to be played to the caller when the call is forwarded to another destination.

Valid value:

  • follow_system: Follow system setting (Set on PBX Settings > Voice Prompt > Prompt Preferences > Music on Hold for Call Forwarding).
  • Empty string: No music played.

  • Other value: The name of the MoH (Music on Hold) playlist.

    Note: You can query the name of MoH playlists using Query MoH Playlists.
ringback_tone_moh No String

The prompt to be played to the caller before the extension user answers the call.

Valid value:

  • follow_system: Follow system setting.
  • Empty string: Continue to play the previous stage's prompt; if no prompt exists, play the caller's own ring tone (beep sound).

  • Other value: The filename of custom prompt (e.g. demo.wav).

    Note: You can query the available custom prompts using Get Menu Options ("menu":"custom_prompt").
outbound_recording_prompt No String The prompt to be played to notify both call participants of an outbound call that the call is being recorded before recording starts.
Valid value:
  • none: No prompt is played.
  • follow_system: Follow system setting (configured on Call Features > Recording > Recording Tones > Outbound Call Being Recorded Prompt).

  • Other value: The filename of custom prompt (e.g. demo.wav).

    Note: You can query the available custom prompts using Get Menu Options ("menu":"custom_prompt").

timezone_id

No

Integer
The ID of the time zone used by the extension.
Note: You can obtain the ID using the Query Time Zone List interface.

office_time_type

No

String

Business hours type.

Valid value:

  • timezone: Use business hours configured for this time zone.
  • custom: Use custom business hours.

office_time_list

No

 Array<Custom_Business_Hours>

The extension's custom business hours.

Note: Required when office_time_type is custom.

presence_office_time_switch

No

String

The presence status to switch to automatically during business hours.

Valid value:

  • available
  • away
  • do_not_disturb
  • lunch
  • business_trip
  • off_work

presence_break_time_switch

No

String

The presence status to switch to automatically during break hours.

Valid value:

  • available
  • away
  • do_not_disturb
  • lunch
  • business_trip
  • off_work

presence_holiday_switch

No

String

The presence status to switch to automatically during holidays.

Valid value:

  • available
  • away
  • do_not_disturb
  • lunch
  • business_trip
  • off_work

presence_other_time_switch

No

String

The presence status to switch to automatically outside business hours.

Valid value:

  • available
  • away
  • do_not_disturb
  • lunch
  • business_trip
  • off_work

allow_reg_remotely

 No Integer

Whether to allow users to register a SIP extension on the PBX remotely.

Valid value:

  • 0: Disabled
  • 1: Enabled

enb_user_agent_ident

No

Integer

Whether to restrict extension registration based on user agent.

Valid value:

  • 0: Disabled
  • 1: Enabled

user_agent_ident_list

No

 Array<User_Agent>
The list of user agents.
Note: Required when enb_user_agent_ident is 1.

enb_ip_rstr

No

Integer

Whether to restrict extension registration based on IP address.

Valid value:

  • 0: Disabled
  • 1: Enabled

ip_rstr_list

No

 Array<IP_List>
The list of IP addresses.
Note: Required when enb_ip_rstr is 1.
vm_greeting No String

The default greeting to be played to the callers before they record voicemail messages.

Valid value:

  • follow_system: Follow system setting (Set on Call feature > Voicemail > Voicemail Settings > Greeting Options > Global Voicemail Greeting).
  • no_greeting: No greeting played.
  • Other value: The filename of the voicemail greeting to use (e.g. demo.wav).
    Note: You can query the filename of voicemail greetings using Query Extension Voicemail Greeting List.
Organization_Info
Parameter Required Type Description
value Yes String The unique ID of an organization.
Note: You can query organization's ID using Get Menu Options.
Presence_Setting
Parameter Required Type Description
status Yes String Extension presence.

Valid value:

  • available: Available
  • away: Away
  • business_trip: Business Trip
  • do_not_disturb: Do Not Disturb (DND)
  • lunch: Lunch Break
  • off_work: Off Work
enb_in_always_forward No Integer Whether to always forward internal incoming calls to a specific destination (Always condition).

Valid value:

  • 0: Disable
  • 1: Enable
in_always_forward_dest No String The destination type for internal call forwarding in Always condition.

Valid value:

  • extension: Extension
  • ext_vm: Extension Voicemail
  • ivr: IVR
  • call_flow: Call Flow
  • ring_group: Ring Group
  • queue: Queue
  • group_vm: Group Voicemail
  • mobile_number: Mobile Number
  • external_num: External Number
  • play_greeting: Play Greeting then Hang up
  • end_call: Hang Up the call with a SIP 480 response.
  • send_busy: Hang Up the call with a SIP 486 response.
Note: When the destination type is ext_vm or mobile_number, the system will automatically retrieve the corresponding destination value from the extension information.
in_always_forward_prefix No String The parameter defines different settings depending on the destination type for internal call forwarding in Always condition.
  • When the destination type is mobile_number or external_num, the parameter defines the dial-out prefix of the external destination number.
  • When the destination type is play_greeting, the parameter defines the play count of the greeting. The valid value is 1 - 5.
in_always_forward_value No String The destination for internal call forwarding in Always condition.

This parameter is REQUIRED for the following destination types:

  • When the destination type is play_greeting, this parameter defines the custom prompt file name. E.g. demo.wav.
  • When the destination type is extension, ivr, ring_group, queue, or group_vm, this parameter should be the unique ID of the destination.
    For example, the destination is the extension 2002, then this parameter should be set to the extension's ID 2.
    Note:
in_always_forward_num No String The external number of the external_num destination for internal call forwarding in Always condition.
in_always_forward_call_confirm No Integer Whether call confirmation is enabled for internal calls forwarded under Always condition.
Note: This setting takes effect only when the forwarding destination is set to mobile_number or external_num.
Valid value:
  • 0: Disable.
  • 1: Enable. The external recipient will be required to press a key to confirm acceptance before the call is connected, preventing the call from being answered by voicemail or automated systems.
enb_in_no_answer_forward No Integer Whether to forward internal calls to a specific destination when the calls are not answered (No Answer condition).

Valid value:

  • 0: Disable
  • 1: Enable
in_no_answer_forward_dest No String The destination type for internal call forwarding in No Answer condition.

Valid value:

  • extension: Extension
  • ext_vm: Extension Voicemail
  • ivr: IVR
  • call_flow: Call Flow
  • ring_group: Ring Group
  • queue: Queue
  • group_vm: Group Voicemail
  • mobile_number: Mobile Number
  • external_num: External Number
  • play_greeting: Play Greeting then Hang up
  • end_call: Hang Up the call with a SIP 480 response.
  • send_busy: Hang Up the call with a SIP 486 response.
Note: When the destination type is ext_vm or mobile_number, the system will automatically retrieve the corresponding destination value from the extension information.
in_no_answer_forward_prefix No String The parameter defines different settings depending on the destination type for internal call forwarding in No Answer condition.
  • When the destination type is mobile_number or external_num, the parameter defines the dial-out prefix of the external destination number.
  • When the destination type is play_greeting, the parameter defines the play count of the greeting. The valid value is 1 - 5.
in_no_answer_forward_value No String The destination for internal call forwarding in No Answer condition.

This parameter is REQUIRED for the following destination types:

  • When the destination type is play_greeting, this parameter defines the custom prompt file name. E.g. demo.wav.
  • When the destination type is extension, ivr, ring_group, queue, or group_vm, this parameter should be the unique ID of the destination.
    For example, the destination is the extension 2002, then this parameter should be set to the extension's ID 2.
    Note:
in_no_answer_forward_num No String The external number of the external_num destination for internal call forwarding in No Answer condition.
in_no_answer_forward_call_confirm No Integer Whether call confirmation is enabled for internal calls forwarded under No Answer condition.
Note: This setting takes effect only when the forwarding destination is set to mobile_number or external_num.
Valid value:
  • 0: Disable.
  • 1: Enable. The external recipient will be required to press a key to confirm acceptance before the call is connected, preventing the call from being answered by voicemail or automated systems.
enb_in_busy_forward No Integer Whether to forward internal calls to a specific destination when the extension is busy (When Busy condition).

Valid value:

  • 0: Disable
  • 1: Enable
in_busy_forward_dest No String The destination type for internal call forwarding in When Busy condition.

Valid value:

  • extension: Extension
  • ext_vm: Extension Voicemail
  • ivr: IVR
  • call_flow: Call Flow
  • ring_group: Ring Group
  • queue: Queue
  • group_vm: Group Voicemail
  • mobile_number: Mobile Number
  • external_num: External Number
  • play_greeting: Play Greeting then Hang up
  • end_call: Hang Up the call with a SIP 480 response.
  • send_busy: Hang Up the call with a SIP 486 response.
Note: When the destination type is ext_vm or mobile_number, the system will automatically retrieve the corresponding destination value from the extension information.
in_busy_forward_prefix No String The parameter defines different settings depending on the destination type for internal call forwarding in When Busy condition.
  • When the destination type is mobile_number or external_num, the parameter defines the dial-out prefix of the external destination number.
  • When the destination type is play_greeting, the parameter defines the play count of the greeting. The valid value is 1 - 5.
in_busy_forward_value No String The destination for internal call forwarding in When Busy condition.

This parameter is REQUIRED for the following destination types:

  • When the destination type is play_greeting, this parameter defines the custom prompt file name. E.g. demo.wav.
  • When the destination type is extension, ivr, ring_group, queue, or group_vm, this parameter should be the unique ID of the destination.
    For example, the destination is the extension 2002, then this parameter should be set to the extension's ID 2.
    Note:
in_busy_forward_num No String The external number of the external_num destination for internal call forwarding in When Busy condition.
in_busy_forward_call_confirm No Integer Whether call confirmation is enabled for internal calls forwarded under When Busy condition.
Note: This setting takes effect only when the forwarding destination is set to mobile_number or external_num.
Valid value:
  • 0: Disable.
  • 1: Enable. The external recipient will be required to press a key to confirm acceptance before the call is connected, preventing the call from being answered by voicemail or automated systems.
enb_ex_always_forward No Integer Whether to always forward external calls to a specific destination (Always condition).

Valid value:

  • 0: Disable
  • 1: Enable
ex_always_forward_dest No String The destination type for external call forwarding in Always condition.

Valid value:

  • extension: Extension
  • ext_vm: Extension Voicemail
  • ivr: IVR
  • call_flow: Call Flow
  • ring_group: Ring Group
  • queue: Queue
  • group_vm: Group Voicemail
  • mobile_number: Mobile Number
  • external_num: External Number
  • play_greeting: Play Greeting then Hang up
  • end_call: Hang Up the call with a SIP 480 response.
  • send_busy: Hang Up the call with a SIP 486 response.
Note: When the destination type is ext_vm or mobile_number, the system will automatically retrieve the corresponding destination value from the extension information.
ex_always_forward_prefix No String The parameter defines different settings depending on the destination type for external call forwarding in Always condition.
  • When the destination type is mobile_number or external_num, the parameter defines the dial-out prefix of the external destination number.
  • When the destination type is play_greeting, the parameter defines the play count of the greeting. The valid value is 1 - 5.
ex_always_forward_value No String The destination for external call forwarding in Always condition.

This parameter is REQUIRED for the following destination types:

  • When the destination type is play_greeting, this parameter defines the custom prompt file name. E.g. demo.wav.
  • When the destination type is extension, ivr, ring_group, queue, or group_vm, this parameter should be the unique ID of the destination.
    For example, the destination is the extension 2002, then this parameter should be set to the extension's ID 2.
    Note:
ex_always_forward_num No String The external number of the external_num destination for external call forwarding in Always condition.
ex_always_forward_call_confirm No Integer Whether call confirmation is enabled for external calls forwarded under Always condition.
Note: This setting takes effect only when the forwarding destination is set to mobile_number or external_num.
Valid value:
  • 0: Disable.
  • 1: Enable. The external recipient will be required to press a key to confirm acceptance before the call is connected, preventing the call from being answered by voicemail or automated systems.
enb_ex_no_answer_forward No Integer Whether to forward external calls to a specific destination when the calls are not answered (No Answer condition).

Valid value:

  • 0: Disable
  • 1: Enable
ex_no_answer_forward_dest No String The destination type for external call forwarding in No Answer condition.

Valid value:

  • extension: Extension
  • ext_vm: Extension Voicemail
  • ivr: IVR
  • call_flow: Call Flow
  • ring_group: Ring Group
  • queue: Queue
  • group_vm: Group Voicemail
  • mobile_number: Mobile Number
  • external_num: External Number
  • play_greeting: Play Greeting then Hang up
  • end_call: Hang Up the call with a SIP 480 response.
  • send_busy: Hang Up the call with a SIP 486 response.
Note: When the destination type is ext_vm or mobile_number, the system will automatically retrieve the corresponding destination value from the extension information.
ex_no_answer_forward_prefix No String The parameter defines different settings depending on the destination type for external call forwarding in No Answer condition.
  • When the destination type is mobile_number or external_num, the parameter defines the dial-out prefix of the external destination number.
  • When the destination type is play_greeting, the parameter defines the play count of the greeting. The valid value is 1 - 5.
ex_no_answer_forward_value No String The destination for external call forwarding in No Answer condition.

This parameter is REQUIRED for the following destination types:

  • When the destination type is play_greeting, this parameter defines the custom prompt file name. E.g. demo.wav.
  • When the destination type is extension, ivr, ring_group, queue, or group_vm, this parameter should be the unique ID of the destination.
    For example, the destination is the extension 2002, then this parameter should be set to the extension's ID 2.
    Note:
ex_no_answer_forward_num No String The external number of the external_num destination for external call forwarding in No Answer condition.
ex_no_answer_forward_call_confirm No Integer Whether call confirmation is enabled for external calls forwarded under No Answer condition.
Note: This setting takes effect only when the forwarding destination is set to mobile_number or external_num.
Valid value:
  • 0: Disable.
  • 1: Enable. The external recipient will be required to press a key to confirm acceptance before the call is connected, preventing the call from being answered by voicemail or automated systems.
enb_ex_busy_forward No Integer Whether to forward external calls to a specific destination when the extension is busy (When Busy condition).

Valid value:

  • 0: Disable
  • 1: Enable
ex_busy_forward_dest No String The destination type for external call forwarding in When Busy condition.

Valid value:

  • extension: Extension
  • ext_vm: Extension Voicemail
  • ivr: IVR
  • call_flow: Call Flow
  • ring_group: Ring Group
  • queue: Queue
  • group_vm: Group Voicemail
  • mobile_number: Mobile Number
  • external_num: External Number
  • play_greeting: Play Greeting then Hang up
  • end_call: Hang Up the call with a SIP 480 response.
  • send_busy: Hang Up the call with a SIP 486 response.
Note: When the destination type is ext_vm or mobile_number, the system will automatically retrieve the corresponding destination value from the extension information.
ex_busy_forward_prefix No String The parameter defines different settings depending on the destination type for external call forwarding in When Busy condition.
  • When the destination type is mobile_number or external_num, the parameter defines the dial-out prefix of the external destination number.
  • When the destination type is play_greeting, the parameter defines the play count of the greeting. The valid value is 1 - 5.
ex_busy_forward_value No String The destination for external call forwarding in When Busy condition.

This parameter is REQUIRED for the following destination types:

  • When the destination type is play_greeting, this parameter defines the custom prompt file name. E.g. demo.wav.
  • When the destination type is extension, ivr, ring_group, queue, or group_vm, this parameter should be the unique ID of the destination.
    For example, the destination is the extension 2002, then this parameter should be set to the extension's ID 2.
    Note:
ex_busy_forward_num No String The external number of the external_num destination for external call forwarding in When Busy condition.
ex_busy_forward_call_confirm No Integer Whether call confirmation is enabled for external calls forwarded under When Busy condition.
Note: This setting takes effect only when the forwarding destination is set to mobile_number or external_num.
Valid value:
  • 0: Disable.
  • 1: Enable. The external recipient will be required to press a key to confirm acceptance before the call is connected, preventing the call from being answered by voicemail or automated systems.
ring_timeout Yes Integer The ringing timeout for incoming calls (Unit: Second).

Valid value: 5 - 300
enb_ring_mobile No Integer Whether the mobile phone will ring simultaneously when the extension rings.

Valid value:

  • 0: Disable
  • 1: Enable
mobile_call_confirm No Integer Whether call confirmation is enabled for the calls simultaneously ringing on the extension's mobile number.
Note: This setting takes effect only when enb_ring_mobile is set to 1.
Valid value:
  • 0: Disable.
  • 1: Enable. The external recipient will be required to press a key to confirm acceptance before the call is connected, preventing the call from being answered by voicemail or automated systems.
enb_accept_call_from_rg No Integer

Whether to accept incoming calls from ring group when the extension is in specific presence status.

Valid value:

  • 0: Disable
  • 1: Enable
vm_greeting No String

The presence greeting to be played to the callers before they record voicemail messages.

Valid value:

  • no_greeting: No greeting played.
  • Empty string: Follow the default extension voicemail greeting (Set on Extension and Trunk > Extension > Voicemail > Voicemail Greeting > Default Greeting ).
  • Other value: The filename of the voicemail greeting to use (e.g. demo.wav).
    Note: You can query the filename of voicemail greetings using Query Extension Voicemail Greeting List.
Custom_Business_Hours
Parameter Required Type Description
months No String The months during which the business hour applies.
Note:
  • This parameter takes effect only when the advanced time condition is enabled (time_condition_switch is 1).
  • Separate multiple months by spaces.

Valid value:

  • all: Every month.
  • jan: January.
  • feb: February.
  • mar: March.
  • apr: April.
  • may: May.
  • jun: June.
  • jul: July.
  • aug: August.
  • sep: September.
  • oct: October.
  • nov: November.
  • dec: December.
days_of_week No String The days of the week on which the business hour applies.
Note:
  • Required when time_condition_switch is 0.
  • Separate multiple values by spaces.

Valid value:

  • all: Every day.
  • sun: Sunday.
  • mon: Monday.
  • tue: Tuesday.
  • wed: Wednesday.
  • thu: Thursday.
  • fri: Friday.
  • sat: Saturday.
days No String The days of the month on which the business hour applies.
Note: This parameter takes effect only when the advanced time condition is enabled (time_condition_switch is 1).

Valid value:

  • all: Every day.
  • 1 - 31

office_times

No

 Array<Time_Period> The list of office time periods.

reset_times

No

 Array<Time_Period> The list of break time periods.
time_condition_switch No Integer Whether to enable the advanced time condition.

Valid value:

  • 0: Disabled.
  • 1: Enabled.
    Note: If enabled, the months and days parameters take effect.
Time_Period
Parameter Type Description
value String The time period in the format HH:MM-HH:MM.
Note: The end time must be later than the start time.
User_Agent
Parameter Required Type Description

user_agent

No

String

 The User-Agent string used to identify the device.
IP_List
Parameter Required Type Description

permitted_ip

No

String

The permitted IP address.

netmask

No

String

The subnet mask.
Linkus_Clients_Setting
Parameter Required Type Description
client Yes String The type of Linkus Client for which you want to configure features such as call waiting, auto-answer for paging/intercom calls, or auto-answer for non-paging/intercom calls.

Valid value:

  • linkusmobile: Linkus Mobile Client
  • linkusdesktop: Linkus Desktop Client
  • linkusweb: Linkus Web Client
enb_call_waiting No Integer Whether to allow the extension to receive another call while already on the phone.

Valid value:

  • 0: Disabled
  • 1: Enabled
enb_auto_answer No Integer

Whether to automatically answer non-paging/intercom calls.

Valid value:

  • 0: Disabled
  • 1: Enabled
auto_answer_delay_time No Integer

The delay time before automatically answering non-paging/intercom calls (Unit: Second).

Valid value: 0 - 60
Note: 0 indicates that incoming non-paging/intercom calls will be auto-answered immediately.
enb_auto_answer_tone No Integer

Whether to alert the extension with a tone when a non-paging/intercom call is automatically answered.

Valid value:

  • 0: Disabled
  • 1: Enabled
enb_auto_answer_paging No Integer Whether to automatically answer paging/intercom calls.

Valid value:

  • 0: Disabled
  • 1: Enabled
enb_auto_answer_paging_barge No Integer Whether to automatically answer paging/intercom calls during an active call.

Valid value:

  • 0: Disabled
  • 1: Enabled
enb_auto_answer_paging_tone No Integer Whether to alert the extension with a tone when a paging/intercom call is automatically answered.

Valid value:

  • 0: Disabled
  • 1: Enabled
max_clients Yes Integer The maximum number of Linkus Clients that can be simultaneously logged in to the extension.
Valid value:
  • 1
  • 2
  • 3
Missed_Call_Auto_Reply
Parameter Required Type Description
call_status_list Yes Array<String> The missed call status that triggers the automatic message reply.

Valid value:

  • caller_abort: The caller hangs up actively while the inbound call is ringing.
  • voicemail: The call is forwarded to the extension voicemail.
  • group_vm: The call is forwarded to a group voicemail.
  • play_greeting_hangup: The system plays greeting for the caller and hangs up the call.
  • busy: The extension is busy.
  • hangup: The extension user hangs up the call.
enb_send_sms No Integer Whether to enable auto-reply messages via SMS messaging channel.
Note: This parameter is required when enb_send_whatsapp is not set or set to 0.

Valid value:

  • 0: Disable
  • 1: Enable
enb_send_whatsapp No Integer Whether to enable auto-reply messages via WhatsApp messaging channel.
Note: This parameter is required when enb_send_sms is not set or set to 0.

Valid value:

  • 0: Disable
  • 1: Enable
sms_config No Object <SMS_Channel_Auto_Reply> The configuration for auto-reply SMS messages.
Note: This parameter is required when enb_send_sms is set to 1.
whatsapp_config No Object <WhatsApp_Channel_Auto_Reply> The configuration for auto-reply WhatsApp messages.
Note: This parameter is required when enb_send_whatsapp is set to 1.

SMS_Channel_Auto_Reply

Parameter Required Type Description
content Yes String The content to be sent.
Note: The maximum character length is 1600.
did_id Yes Integer The DID number of SMS messaging channel.
Note:
  • You can query the available DID number of SMS messaging channel using Get Menu Options ("menu":"message_channel").
  • This parameter must be the DID number associated with the channel that the extension is allowed to use to create messaging sessions.
msg_type No Integer The type of the SMS message.

Valid value:

  • 1: Text.

WhatsApp_Channel_Auto_Reply

Parameter Required Type Description
did_id Yes Integer The DID number of WhatsApp messaging channel.
Note:
  • You can query the available DID number of WhatsApp messaging channel using Get Menu Options ("menu":"message_channel").
  • This parameter must be the DID number associated with the channel that the extension is allowed to use to create messaging sessions.
template_params Yes String The JSON content of WhatsApp message templates.
Note: You can query the complete JSON content using Get WhatsApp Message Templates.

Response parameters

Parameter Type Description
errcode Integer Returned error code.
  • 0: Succeed.
  • Non-zero value: Failed.
Note: You can check the error code and error message in Error Code and Error Message.
errmsg String Returned message.
  • SUCCESS: Succeed.
  • FAILURE: Failed.
id Integer The unique ID of the extension.

Examples

Request example

POST /openapi/v1.0/extension/create?access_token=q0GyBcsgO8FsXWxPpzAJVW33vd0OpnUz 

Host: yeastardocs.example.yeastarcloud.com
Content-Type: application/json
{
    "type": "SIP", 
    "avatar":"myYtwrWoRmxBeyGrd0ff1e60-2b53-4d17-8a13-736923dab108",
    "first_name": "Terrell",
    "last_name": "Smith",
    "email_addr": "terrell@sample.com",
    "mobile_number": "15880987652",
    "user_password": "Userpwd1011",
    "organization_list":[{"value":"1"},{"value":"2"}],
    "role_id": 1,
    "email_language":"en",
    "user_lang": "sound-en",
    "vm_lang":"follow_system",
    "number": "1000",
    "caller_id": "5503301",
    "reg_name": "Yeastar_ext",
    "reg_password": "Regpwd1011",
    "concurrent_registrations": 1,
    "presence_status": "available",
    "enb_all_reject_mode_for_endpoints":1,
    "dtmf_mode": "rfc4733",
    "transport": "udp",
    
    "enb_monitor_call_quality": 1,
    "monitoring_end_timestamp": 1780271999,
    "agent_id":"5630",
    "enb_vm":1,
    "enb_vm_pin":1,
    "vm_pin":"8573",
    "enb_vm_play_datetime": 0,
    "vm_play_time_format": "follow_system",
    "enb_all_busy_mode_for_endpoints": 1,
    "enb_all_reject_mode_for_endpoints":0,
    "disable_international_call":1,
    "disable_outb_call_outside_business_hours":1,
    "disable_outb_call":0,
    "max_outb_call_duration": -1,
    "outbound_route_permission":[69],
    "enb_mobile_client":1,
    "enb_desktop_client":1,
    "enb_web_client":1,
    "enb_pad_client": 1,
    "linkus_mobile_codec": "g729",
   
    "presence_mobile_prefix": "86",
    "presence_list": [
            {
                "status": "available",
                "enb_in_always_forward": 0,
                "in_always_forward_dest": "ext_vm",
                "in_always_forward_prefix": "",
                "in_always_forward_value": "",
                "in_always_forward_num": "",
                "in_always_forward_call_confirm":0,
                "enb_in_no_answer_forward": 1,
                "in_no_answer_forward_dest": "external_num",
                "in_no_answer_forward_prefix": "",
                "in_no_answer_forward_value": "",
                "in_no_answer_forward_num": "123123",
                "in_no_answer_forward_call_confirm":1,
                "enb_in_busy_forward": 1,
                "in_busy_forward_dest": "ext_vm",
                "in_busy_forward_prefix": "",
                "in_busy_forward_value": "",
                "in_busy_forward_num": "",
                "in_busy_forward_call_confirm":0,
                "enb_ex_always_forward": 0,
                "ex_always_forward_dest": "ext_vm",
                "ex_always_forward_prefix": "",
                "ex_always_forward_value": "",
                "ex_always_forward_num": "",
                "ex_always_forward_call_confirm":0,
                "enb_ex_no_answer_forward": 1,
                "ex_no_answer_forward_dest": "ivr",
                "ex_no_answer_forward_prefix": "",
                "ex_no_answer_forward_value": "1",
                "ex_no_answer_forward_num": "",
                "ex_no_answer_forward_call_confirm":0,
                "enb_ex_busy_forward": 1,
                "ex_busy_forward_dest": "end_call",
                "ex_busy_forward_prefix": "",
                "ex_busy_forward_value": "",
                "ex_busy_forward_num": "",
                "ex_busy_forward_call_confirm":0,
                "enb_ring_mobile": 1,
                "mobile_call_confirm":1,                
                "ring_timeout": 30,
                "enb_accept_call_from_rg": 1
            },
            {
                "status": "away",
                "enb_in_always_forward": 0,
                "in_always_forward_dest": "ext_vm",
                "in_always_forward_prefix": "",
                "in_always_forward_value": "",
                "in_always_forward_num": "",
                "in_always_forward_call_confirm":0,
                "enb_in_no_answer_forward": 1,
                "in_no_answer_forward_dest": "ring_group",
                "in_no_answer_forward_prefix": "",
                "in_no_answer_forward_value": "1",
                "in_no_answer_forward_num": "",
                "in_no_answer_forward_call_confirm":0,
                "enb_in_busy_forward": 1,
                "in_busy_forward_dest": "queue",
                "in_busy_forward_prefix": "",
                "in_busy_forward_value": "1",
                "in_busy_forward_num": "",
                "in_busy_forward_call_confirm":0,
                "enb_ex_always_forward": 0,
                "ex_always_forward_dest": "ext_vm",
                "ex_always_forward_prefix": "",
                "ex_always_forward_value": "",
                "ex_always_forward_num": "",
                "ex_always_forward_call_confirm":0,
                "enb_ex_no_answer_forward": 1,
                "ex_no_answer_forward_dest": "group_vm",
                "ex_no_answer_forward_prefix": "",
                "ex_no_answer_forward_value": "1",
                "ex_no_answer_forward_num": "",
                "ex_no_answer_forward_call_confirm":0,
                "enb_ex_busy_forward": 1,
                "ex_busy_forward_dest": "play_greeting",
                "ex_busy_forward_prefix": "1",
                "ex_busy_forward_value": "demo.wav",
                "ex_busy_forward_num": "",
                "ex_busy_forward_call_confirm":0,
                "enb_ring_mobile": 0,   
                "mobile_call_confirm":0,                 
                "ring_timeout": 30,
                "enb_accept_call_from_rg": 0
            },
            {
                "status": "business_trip",
                "enb_in_always_forward": 0,
                "in_always_forward_dest": "ext_vm",
                "in_always_forward_prefix": "",
                "in_always_forward_value": "",
                "in_always_forward_num": "",
                "in_always_forward_call_confirm":0,
                "enb_in_no_answer_forward": 1,
                "in_no_answer_forward_dest": "mobile_number",
                "in_no_answer_forward_prefix": "123",
                "in_no_answer_forward_value": "",
                "in_no_answer_forward_num": "",
                "in_no_answer_forward_call_confirm":1,
                "enb_in_busy_forward": 1,
                "in_busy_forward_dest": "external_num",
                "in_busy_forward_prefix": "543",
                "in_busy_forward_value": "",
                "in_busy_forward_num": "5235235235",
                "in_busy_forward_call_confirm":0,
                "enb_ex_always_forward": 0,
                "ex_always_forward_dest": "ext_vm",
                "ex_always_forward_prefix": "",
                "ex_always_forward_value": "",
                "ex_always_forward_num": "",
                "ex_always_forward_call_confirm":0,
                "enb_ex_no_answer_forward": 1,
                "ex_no_answer_forward_dest": "ext_vm",
                "ex_no_answer_forward_prefix": "",
                "ex_no_answer_forward_value": "",
                "ex_no_answer_forward_num": "",
                "ex_no_answer_forward_call_confirm":0,
                "enb_ex_busy_forward": 1,
                "ex_busy_forward_dest": "group_vm",
                "ex_busy_forward_prefix": "",
                "ex_busy_forward_value": "1",
                "ex_busy_forward_num": "",
                "ex_busy_forward_call_confirm":0,
                "enb_ring_mobile": 0, 
                "mobile_call_confirm":0,                 
                "ring_timeout": 30,
                "enb_accept_call_from_rg": 0
            },
            {
                "status": "do_not_disturb",
                "enb_in_always_forward": 1,
                "in_always_forward_dest": "ext_vm",
                "in_always_forward_prefix": "",
                "in_always_forward_value": "",
                "in_always_forward_num": "",
                "in_always_forward_call_confirm":0,
                "enb_in_no_answer_forward": 1,
                "in_no_answer_forward_dest": "ext_vm",
                "in_no_answer_forward_prefix": "",
                "in_no_answer_forward_value": "",
                "in_no_answer_forward_num": "",
                "in_no_answer_forward_call_confirm":0,
                "enb_in_busy_forward": 1,
                "in_busy_forward_dest": "ext_vm",
                "in_busy_forward_prefix": "",
                "in_busy_forward_value": "",
                "in_busy_forward_num": "",
                "in_busy_forward_call_confirm":0,
                "enb_ex_always_forward": 1,
                "ex_always_forward_dest": "ext_vm",
                "ex_always_forward_prefix": "",
                "ex_always_forward_value": "",
                "ex_always_forward_num": "",
                "ex_always_forward_call_confirm":0,
                "enb_ex_no_answer_forward": 1,
                "ex_no_answer_forward_dest": "ext_vm",
                "ex_no_answer_forward_prefix": "",
                "ex_no_answer_forward_value": "",
                "ex_no_answer_forward_num": "",
                "ex_no_answer_forward_call_confirm":0,
                "enb_ex_busy_forward": 1,
                "ex_busy_forward_dest": "ext_vm",
                "ex_busy_forward_prefix": "",
                "ex_busy_forward_value": "",
                "ex_busy_forward_num": "",
                "ex_busy_forward_call_confirm":0,
                "enb_ring_mobile": 0,   
                "mobile_call_confirm":0,                
                "ring_timeout": 30,
                "enb_accept_call_from_rg": 0
            },
            {
                "status": "lunch",
                "enb_in_always_forward": 0,
                "in_always_forward_dest": "ext_vm",
                "in_always_forward_prefix": "",
                "in_always_forward_value": "",
                "in_always_forward_num": "",
                "in_always_forward_call_confirm":0,
                "enb_in_no_answer_forward": 1,
                "in_no_answer_forward_dest": "ext_vm",
                "in_no_answer_forward_prefix": "",
                "in_no_answer_forward_value": "",
                "in_no_answer_forward_num": "",
                "in_no_answer_forward_call_confirm":0,
                "enb_in_busy_forward": 1,
                "in_busy_forward_dest": "ext_vm",
                "in_busy_forward_prefix": "",
                "in_busy_forward_value": "",
                "in_busy_forward_num": "",
                "in_busy_forward_call_confirm":0,
                "enb_ex_always_forward": 0,
                "ex_always_forward_dest": "ext_vm",
                "ex_always_forward_prefix": "",
                "ex_always_forward_value": "",
                "ex_always_forward_num": "",
                "ex_always_forward_call_confirm":0,
                "enb_ex_no_answer_forward": 1,
                "ex_no_answer_forward_dest": "ext_vm",
                "ex_no_answer_forward_prefix": "",
                "ex_no_answer_forward_value": "",
                "ex_no_answer_forward_num": "",
                "ex_no_answer_forward_call_confirm":0,
                "enb_ex_busy_forward": 1,
                "ex_busy_forward_dest": "ext_vm",
                "ex_busy_forward_prefix": "",
                "ex_busy_forward_value": "",
                "ex_busy_forward_num": "",
                "ex_busy_forward_call_confirm":0,
                "enb_ring_mobile": 1,
                "mobile_call_confirm":1,                 
                "ring_timeout": 30,
                "enb_accept_call_from_rg": 0
            },
            {
                "status": "off_work",
                "enb_in_always_forward": 0,
                "in_always_forward_dest": "ext_vm",
                "in_always_forward_prefix": "",
                "in_always_forward_value": "",
                "in_always_forward_num": "",
                "in_always_forward_call_confirm":0,
                "enb_in_no_answer_forward": 1,
                "in_no_answer_forward_dest": "ext_vm",
                "in_no_answer_forward_prefix": "",
                "in_no_answer_forward_value": "",
                "in_no_answer_forward_num": "",
                "in_no_answer_forward_call_confirm":0,
                "enb_in_busy_forward": 1,
                "in_busy_forward_dest": "ext_vm",
                "in_busy_forward_prefix": "",
                "in_busy_forward_value": "",
                "in_busy_forward_num": "",
                "in_busy_forward_call_confirm":0,
                "enb_ex_always_forward": 0,
                "ex_always_forward_dest": "ext_vm",
                "ex_always_forward_prefix": "",
                "ex_always_forward_value": "",
                "ex_always_forward_num": "",
                "ex_always_forward_call_confirm":0,
                "enb_ex_no_answer_forward": 1,
                "ex_no_answer_forward_dest": "ext_vm",
                "ex_no_answer_forward_prefix": "",
                "ex_no_answer_forward_value": "",
                "ex_no_answer_forward_num": "",
                "ex_no_answer_forward_call_confirm":0,
                "enb_ex_busy_forward": 1,
                "ex_busy_forward_dest": "ext_vm",
                "ex_busy_forward_prefix": "",
                "ex_busy_forward_value": "",
                "ex_busy_forward_num": "",
                "ex_busy_forward_call_confirm":0,
                "enb_ring_mobile": 0,  
                "mobile_call_confirm":0,                
                "ring_timeout": 30,
                "enb_accept_call_from_rg": 0
            }
        ],
        "client_conf_list": [
            {
                "client": "linkusweb",
                "enb_call_waiting": 1,
                "enb_auto_answer": 0,
                "enb_auto_answer_paging": 1,
                "enb_auto_answer_paging_barge": 0,
                "enb_auto_answer_paging_tone": 1,
                "max_clients": 2
            },
            {
                "client": "linkusdesktop",
                "enb_call_waiting": 1,
                "enb_auto_answer": 1,
                "auto_answer_delay_time": 10,
                "enb_auto_answer_tone": 1,
                "enb_auto_answer_paging": 0,
                "enb_auto_answer_paging_barge": 0,
                "enb_auto_answer_paging_tone": 1,
                "max_clients": 2
            },
            {
                "client": "linkusmobile",
                "enb_call_waiting": 0,
                "enb_auto_answer": 1,
                "auto_answer_delay_time": 5,
                "enb_auto_answer_tone": 1,
                "enb_auto_answer_paging": 1,
                "enb_auto_answer_paging_barge": 1,
                "enb_auto_answer_paging_tone": 1,
                "max_clients": 3
            }
        ]
}

Response example

HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "id": 233
}