API : PBX : SIP phone Admin list

Introduction

This request will return SIP phones across all customers. It is intended for the admin section, where a RESELLER_ADMIN or ADMIN can see which SIP phones are in use, filtered by model, by User-Agent string and by online/offline status.

Online status and User-Agent are read live from Redis, as reported by the PBX registration servers. Mitel DECT bases never register themselves and are always reported as online. Softphones (auto-created for Communicator Desktop/WebRTC) are excluded unless includeSoftphones is set to true.

Request

URL	https://api.telecomx.dk/pbx/sipphone/admin
Method	GET
Access level	RESELLER_ADMIN (requires the TELE employee feature), ADMIN.
Query	offset	Number	Index of the first item to return. Optional, default 0.
	limit	Number	Maximum number of items to return (1-500). Optional, default 100.
	model	String	Id of a SIP phone model, to only return phones of that model. Optional.
	userAgent	String	Case-insensitive substring matched against the phones User-Agent string. Optional.
	status	String	`online` or `offline` to only return phones with that status. Optional, omit for all.
	groupBy	String	`customer` to sort the result by customer name, for grouped display. Optional.
	includeSoftphones	Boolean	True to include auto-created softphones. Optional, default false.

Query example

https://api.telecomx.dk/pbx/sipphone/admin?status=offline&userAgent=snom&limit=100

Response

JSON object
offset	Number	Index of the first returned item.
limit	Number	Maximum number of returned items.
total	Number	Total number of SIP phones matching all filters.
sipPhones	Array	List of matching SIP phones (see below).

sipPhones[] object
_id	String	Id of the SIP phone.
customer	String	Id of the customer owning the phone.
customerName	String	Name of the customer.
resellerName	String	Name of the customers reseller. Null for top level customers.
name	String	Name/location of the phone, if set.
macAddress	String	MAC address of the phone (12 hex chars, no separators).
handsetIndex	Number	DECT handset index, 0 = DECT base. Null for regular phones.
handsetAddress	String	DECT handsets individual id, if applicable.
sipPhoneModel	Object	The phones model: _id, brand, brandName, model, picture. Null if the model no longer exists.
extension	Object	The extension the phone is assigned to: _id, number, direct. Null if not assigned.
employee	Object	Employee using the phone: _id, name. Null if none.
online	Boolean	True if the phone is currently registered. Mitel DECT bases are always reported online.
userAgent	String	User-Agent string as last received from the phone. Null if unknown.
publicIpAddress	String	Public IP address the phone registered from. Null if unknown.

Example

{
  "offset": 0,
  "limit": 100,
  "total": 1,
  "sipPhones": [
    {
      "_id": "1234567890ABCDEF12345678",
      "customer": "234567890ABCDEF123456789",
      "customerName": "Example Company A/S",
      "resellerName": "Example Reseller A/S",
      "name": "Reception",
      "macAddress": "000413794A43",
      "handsetIndex": null,
      "handsetAddress": null,
      "sipPhoneModel": {
        "_id": "34567890ABCDEF1234567890",
        "brand": "SNOM",
        "brandName": "Snom",
        "model": "D745",
        "picture": "4567890ABCDEF12345678901"
      },
      "extension": {
        "_id": "567890ABCDEF123456789012",
        "number": "101",
        "direct": "70123456"
      },
      "employee": {
        "_id": "67890ABCDEF1234567890123",
        "name": "Jane Doe"
      },
      "online": true,
      "userAgent": "Mozilla/4.0 (compatible; snomD745-SIP 10.1.57.14)",
      "publicIpAddress": "213.83.176.134"
    }
  ]
}

Errors

Error code	Message	Description
400	bad_request	Invalid query parameters
401	unauthorized	Missing or invalid token
403	access_denied	Insufficient access level or missing TELE employee feature
500	internal_error	<Unspecified>

Notes

Online status and User-Agent only exist in Redis, not in MongoDB. The endpoint therefore loads all candidate phones, hydrates their live status from Redis, applies the status/userAgent filters, and computes total after filtering. Pagination (offset/limit) is applied to the filtered, sorted result.

WIKI

Table of Contents