API : PBX : SIP Phone list

Introduction

This request will return the list of SIP phones that belongs to a customer.

Request

URL	https://api.telecomx.dk/pbx/sipphone
Method	GET
Access level	VIEWER, MANAGE, OWNER, RESELLER or ADMIN.
Query	offset	`[optional]` Index of the first item to return, default 0.
	limit	`[optional]` The number of items to return, default 50, min 1, max 1000.
	filter	`[optional]` Search query that will match against macAddress, ip.address, handsetAddress, extension number, direct number, employee name and notes.
	full	`[optional]` True to include all settings.
	available	`[optional]` True to only include SIP phones that are not assigned to an extension.
	customer	`[optional]` Id of customer to show SIP phones for. Defaults to the users own customer if not specified.

Query examples

https://api.telecomx.dk/pbx/sipphone
https://api.telecomx.dk/pbx/sipphone?customer=123458789012457890ABCD
https://api.telecomx.dk/pbx/sipphone?filter=donald%20duck
https://api.telecomx.dk/pbx/sipphone?customer=12345678901234567890ABCD&full=true

Response

JSON object
offset	Index of the first SIP phone returned.
limit	Number of SIP phone to return. Note that the actual number of returned items may be lower.
total	Number of SIP phone that can be returned when offset and limit is not considered. This is to be used for paging through the data.
sipPhones	Array of SIP phones, see definition below.

SIP phone object (normal)
_id	Id	Unique ID of the SIP phone.
macAddress	String	Phone MAC address.
handsetIndex	Number	If the SIP phone supports multiple handsets (like a DECT base), this is the handsets 0-based position in the list of handsets.
handsetAddress	String	If the SIP phone supports multiple handsets (like a DECT base) this is the handsets individual ID, similar to a MAC address - if applicable.
sipPhoneModel	Object	SIP phone model data.
sipPhoneModel._id	Id	Id of the model of this phone.
sipPhoneModel.brand	String	Type of brand: SNOM, MITEL, GIGASET, LG, CISCO, YEALINK, GENERIC.
sipPhoneModel.brandName	String	Human friendly brand name.
sipPhoneModel.model	String	Model name, e.g. 370, PAP2-T etc.
sipPhoneModel.picture	Id	Id of a 200×200 pixels image of the phone model.
extension._id	Id	Id of the extension this SIP phone belongs to (if any).
extension.number	String	Extension number (if any).
extension.direct	String	Direct public phone number (if any).
employee._id	Id	Id of employee the phone belongs to (if any).
employee.name	String	Name of the employee the phone belongs to (if any).
ip.mode	String	IP restriction mode: OPEN - Phone can connect from any IP address. After initial connection (get config, registration or call) mode is changed to LOCKED and IP address is set. LOCKED - Phone can only connect from the IP address in ip.address. ROAMING - Phone can only connect from IP addresses in the countries listed in ip.countries.
ip.countries	String	Comma list of ISO3166-2 2-char country codes for countries the phone can connect from if ip.mode is ROAMING.
ip.address	String	IP address the phone can connect from if ip.mode is LOCKED.
notes	String	Notes about the SIP phone.
online	Boolean	True if the phone is online.

SIP phone object (full=true)
_id	Id	Unique id of the SIP phone.
pbxCluster	Number	Id of the PBX cluster the phone is on 1 - Production (default) 2 - Development
sipPhoneModel	Id	The model of SIP phone (from SipPhoneModels).
extension	Id	The extension the SIP phone belongs to, null if not yet assigned.
customer	Id	Id of customer the phone belongs to.
macAddress	String	12-char MAC address of the SIP phone.
serial	String	Serial number, required for Grandstream devices.
handsetIndex	Number	If the SIP phone supports multiple handsets (like a DECT base), this is the handsets position in the list of handsets. This is auto assigned when created and cannot be changed.
handsetAddress	String	If the SIP phone supports multiple handsets (like a DECT base) this is the handsets individual ID, similar to a MAC address - if applicable.
callWaiting	Boolean	True if call waiting is enabled, null if model does not support it (not used).
sidePanel	String	If the phone model supports side panels, this is the model that is used. Null if no side panels are used.
sidePanelCount	Number	If the phone model supports side panels, this is the number of panels that are attached to the phone.
softkeyConfigurationOnDevice	Boolean	True if soft keys are configured individual on the device, false if soft keys are configured on the user.
softkeyBlfBlindTransfer	Boolean	True if BLF type soft keys performs blind transfer instead of attended transfer (default).
headsetButton	String	If headset button is supported, this configures it: speaker - activates the handsfree speaker headset - activates the headset speaker-headset - activates speaker and toggles between speaker and headset headset-speaker - activates headset and toggles between headset and speaker.
dhsg	Boolean	True if the phone uses a DHSG headset.
displayBrightness	Number	Display brightness 0-15.
displayBrightnessIdle	Number	Display brightness when idle 0-15.
displayBackground	String	URL to fetch a picture to display in the background on supported phones.
displayFontColor	String	Font color on Mitel phones: LIGHT or DARK.
customConfig	String	Custom configuration data. For insertion into the generated configuration file for the phone. Do not use unless absolutely needed.
notes	String	Notes about the SIP phone.
Security settings
ip.mode	String	IP restriction mode: OPEN - Phone can connect from any IP address. After initial connection (get config, registration or call) mode is changed to LOCKED and IP address is set. LOCKED - Phone can only connect from the IP address in ip.address. ROAMING - Phone can only connect from IP addresses in the countries listed in ip.countries.
ip.countries	String	If ip.mode is ROAMING, this is a comma list of ISO3166-2 country codes of countries where the SIP phone may connect from.
ip.address	String	The IP address the SIP phone may register/make calls/fetch config from, if mode is LOCKED.
username	String	Username for SIP authentication, auto-generated 32-char string.
password	String	Password for SIP authentication, auto-generated 32-char string.
instanceId	String	Optional ID of WebRTC instance (e.g. Communicator Desktop) that this phone belongs to.
Volume settings
ringer.volume	Number	Ringtone volume (if supported by model).
ringer.tone	String	Id of ringtone. If a built-in ringtone is used this is the index number of the tone. If a custom ringtone is used, this is the ID of the ringtone.
volume.handset.mic	Number	Handset microphone level (if supported by model).
volume.handset.speaker	Number	Handset speaker level (if supported by model).
volume.headset.mic	Number	Headset microphone level (if supported by model).
volume.headset.speaker	Number	Headset speaker level (if supported by model).
volume.handsfree.mic	Number	Handsfree microphone level (if supported by model).
volume.handsfree.speaker	Number	Handsfree speaker level (if supported by model).
Softkey settings
softkeys	Array	List of configured softkeys (if supported by model).
softkeys[].index	Number	Position of the softkey, 0-based.
softkeys[].function	String	Type of function the softkey performs: SPEEDDIAL - Dial a number BLF - Dial a co-worker and show busy status LINE - Line key DND - Enable/disable do-not-disturb DNDOTHER - Enable/disable do-not-disturb on specific device ADDRESSBOOK - Access the phones address book REDIAL - Re-dials the last called number VOICEMAIL - Calls voicemail TRANSFER - Tranfer call URL - Invokes a URL, possible returning an XML menu HOLD - Puts the current call on hold RECORD - Starts recording the call MENU - Shows the phones menu PICKUP - Pickup a ringing phone the group the phone belongs to PICKUPGROUP - Pickup a ringing phone from a specific group QUEUE - Join/leave a specific queue SWITCH - a named on/off switch PRESENCE - set presence state
softkeys[].value	String	Settings for the selected function: SPEEDDIAL - phone number to call BLF - if of extension to monitor/call URL - URL to invoke (http://.…) PICKUPGROUP - id of group to pickup call from QUEUE - if of queue SWITCH - name of the switch DNDOTHER - id of device to toggle DND for
softkeys[].label	String	Text label to display next to the softkey (if supported by model).
Codec settings
codec.hdAudio	Boolean	True to allow HD audio codecs.
codec.video	Boolean	True to allow video codecs.
Network settings
network.dhcp	Boolean	True to assign IP address using DHCP (if supported by model).
network.ipAddress	String	IP address of SIP phone (if not using DHCP, and supported by model).
network.subnet	String	IP subnet mask (if not using DHCP, and supported by model).
network.gateway	String	IP address of default gateway (if not using DHCP, and supported by model).
network.dns1	String	Primary DNS server (if not using DHCP, and supported by model).
network.dns2	String	Secondary DNS server (if not using DHCP, and supported by model).
network.vlanId	Number	Vlan ID 0-4094, default 0 (not used).
network.vlanPriority	Number	Vlan priority 0-7, default 0 (not used).
Purchase Info
orderId	String	Order ID of the SIP Phone, references to external economic system
date	Date	Date the phone was purchased
paymentOption	String	How the phone is purchased or financed: NONE, BOUGHT, RENTED or SELF_OWNED
purchaseInfo.sidePanels	Array	List of sidepanels, and their financial information.
purchaseInfo.sidePanels[].serial	String	Serial number of side panel, must be unique across all SIP phones
purchaseInfo.sidePanels[].paymentOption	String	How the sidepanel is purchased or financed: NONE, BOUGHT, RENTED or SELF_OWNED
purchaseInfo.sidePanels[].orderId	String	Date the sidepanel was bought
purchaseInfo.sidePanels[].date	Date	When the sidepanel was bought/rented, etc.
Status (read-only)
status.configLoaded	Date	Date and time the configuration was most recently fetched (if supported by model).
status.configSaved	Date	Date and time the configuration was last updated.
status.online	Boolean	True if the phone is online.
status.expires	Number	Number of seconds until the phones registration expires, -1 if not online.
status.localIpAddress	String	Local IP address that phone is currently at (if available).
status.publicIpAddress	String	Public IP address that the phone is currently at (if available).
status.userAgent	String	The user agent string as presented by the phone.

Example - normal

{
  offset: 0,
  limit: 50,
  total: 25,
  sipPhones: [
    {
      _id: '1234567890123457890ABCD',
      macAddress: '4EE8A34B56F3',
      sipPhoneModel: {
        _id: '123456789012345678910AAAA',
        brand: 'Snom',
        model: '370',
        picture: '1234567890123457890BBBB'
      },
      extension: {
        _id: '1234567890124567890CCCC',
        number: '592',
        direct: '+4570305050'
      },
      employee: {
        _id: '12345678901234567890DDDD',
        name: 'Donald Duck'
      },
      ip: {
        mode: 'LOCKED',
        countries: '',
        address: '213.83.176.134'
      },
      notes: 'A note about the phone',
      online: true
    },
    {
      ...
    }
  ]

Example - full=true

{
  offset: 0,
  limit: 50,
  total: 25,
  sipPhones: [
    {
      _id: '12345678901234567890ABCD',
      pbxCluster: 1,
      sipPhoneModel: '1234567890123457890AAAA',
      extension: '123457890123457890BBBB',
      customer: '1234567890123456780CCCC',
      macAddress: '4EE8A34B56F3',
      handsetAddress: null,
      handsetIndex: null,
      callWaiting: true,
      softkeyConfigurationOnDevice: true,
      softkeyBlfBlindTransfer: false,
      notes: 'A note about the phone',
      ip: {
        mode: 'LOCKED',
        countries: '',
        address: '213.83.176.134'
      },
      username: '2yu9hjfy23iuhdwg9ewhufghuiweghui',
      password: 'g9ewhufg2yu9hjfy2whuiweghui3iuhd',
      instanceId: null,
      ringer: {
        volume: 4,
        tone: 2
      },
      volume: {
        handset: { mic: 5, speaker: 7 },
        headset: { mic: 5, speaker: 7 },
        handsfree: { mic: 3, speaker: 4 }
      },
      softkeys: [
        { index: 0, function: 'SPEEDDIAL', value: '112', label: 'Emergency' },
        { index: 1, function: 'BLF', value: '1234567890123457890FFFF', label: 'Hans Christian Anderson' }
      ],
      codec: { hdAudio: true, video: false },
      network: {
        dhcp: false,
        ipAddress: '192.168.1.10',
        subnet: '255.255.255.0',
        gateway: '192.168.1.1',
        dns1: '192.168.1.1',
        dns2: '8.8.8.8',
        vlanId: 0,
        vlanPriority: 5
      },
      status: {
        configLoaded: '2015-01-01T00:00:00Z',
        configSaved: '214-01-01T00:00:00Z',
        online: true,
        expires: 2543,
        localIpAddress: '192.168.1.10',
        publicIpAddress: '213.83.176.134',
        userAgent: 'snom370/8.7.3.25'
      },
      purchaseInfo: {
         orderId: '7213',
         date: '2020-01-01T00:00:00Z',
         paymentOption: 'RENTED'
      }
 
    },
    {
      ...
    }
  ]

Errors

Error code	Message	Description
403	access_denied	Insufficient access level
500	internal_error	<Unspecified>

WIKI

Table of Contents

API : PBX : SIP Phone list

Introduction

Request

Query examples

Response

Example - normal

Example - full=true

Errors