API : PBX : APP: Employees List

Introduction

This request will return the list of all employees on a customer, with presence, extensions and extension state.

This API is for use in apps that shows employees and their state on the hosted PBX platform.

For realtime notifications on employee and state changes - see realtime api. This API is only for the initial load.

Request

URL	https://api.telecomx.dk/pbx/app/employees
Method	GET, POST
Access level	PERSONAL, VIEWER, MANAGER, OWNER, RESELLER, ADMIN.
Query/Body	ids	`[Optional]` Array of employee Ids - if you only want to lookup specific employees.
	calls	`[Optional]` True to include list of current calls on the members extensions. But only if the user is permitted to see them via the group permission viewOtherParty.
	standalone	`[Optional]` True to also include extensions which are not linked to an employee.

Query example - GET

https://api.telecomx.dk/pbx/app/employees
https://api.telecomx.dk/pbx/app/employees?ids=12345678901234567890ABCD
https://api.telecomx.dk/pbx/app/employees?ids=12345678901234567890ABCD&ids=12345678901234567890AAAA
https://api.telecomx.dk/pbx/app/employees?standalone=true

Query example - POST

{
  [
    '12345678901234567890ABCD',
    '12345678901234567890AAAA'
  ]
}

Response

JSON object
_id	Id	Unique id of employee or extension (if standalone=true).
type	String	Type of record: EMPLOYEE or EXTENSION.
name	String	employee name or extension name.
title	String	The employees title (type EMPLOYEE only).
department	String	The employees department/section/group (type EMPLOYEE only).
emailAddress	String	E-mail address (also used for login) (type EMPLOYEE only).
birthdate	Date	Date of birth, null if not set (type EMPLOYEE only).
picture	Id	Id of a picture of the employee, null if no picture is set (type EMPLOYEE only).
viewOtherPartyOverride	String	Override for PBX group access to see who the employee is talking to (type EMPLOYEE only): NONE - no override HIDE - Always hidden HIDE_PERSONAL_PHONEBOOK - hide if number is in personal phonebook HIDE_OFF_WORK - hide when presence is OFF_WORK or HOLIDAY HIDE_PERSONAL_PHONEBOOK_AND_OFF_WORK - hide if number is in personal phonebook or presence is OFF_WORK or HOLIDAY
address	Object	Address data (type EMPLOYEE only).
address._id	Id	Id of address.
address.primary	Boolean	True if this address is the primary customer address.
address.address	String	Street.
address.zip	String	Zip code.
address.city	String	City.
address.country	String	ISO3166-2 country code.
address.municipalityCode	Number	Municipality code.
address.alternativeName	String	Alternative name for the address.
presence	Presence settings (type EMPLOYEE only)
presence.state	String	The employees presence: AVAILABLE - free to accept calls BUSY - do not disturb OUT_OF_OFFICE - When not in the office (out) OFF_WORK - not working HOLIDAY - away for an extended period
presence.location	String	If location is available this will have a location string saying where the employee is, e.g. “På kontoret”, “I bilen”, “På lageret”. (this is setup on the smartphone app).
presence.message	String	A freetext message to display to others, e.g. “Til møde indtil kl. 15.00”
presence.expire	Date	If the current presence expires at some point in the future this is that time, and the presence will return to AVAILABLE and the expire and message will be deleted.
presence.overrides	Array	List of currently active overrides to the current state.
presence.overrides[].id	String	Id of the entity that owns the override.
presence.overrides[].source	String	Source of the override: MS365_CALENDAR, MS365_TEAMS.
presence.overrides[].state	String	The state to override with: AVAILABLE - free to accept calls BUSY - do not disturb OUT_OF_OFFICE - When not in the office (out) OFF_WORK - not working HOLIDAY - away for an extended period.
presence.originalState	String	If an override is in effect, this is the state that the presence will revert to when the override ends.
presence.originalMessage	String	If an override is in effect, this is the message that the presence will revert to when the override ends.
extensions	Array	List of extensions. For type EXTENSION this always holds 1 item.
extensions[]._id	Id	Id of extension.
extensions[].number	String	Extensions local number.
extensions[].direct	String	Direct phone number.
extensions[].mobile	Array	List of mobile phone numbers that belongs to this extension. E.164 format.
extensions[].primary	Boolean	True if this is the primary extension for the employee.
extensions[].state	String	Current state of the extension: IDLE, RINGING, BUSY.
extensions[].redirect	String	Number to redirect to when extension is called. Used to quickly circumvent the extension.
extensions[].calls	Array	List of calls the extension currently has.
extensions[].calls[]._id	String	Unique ID of the call - <pbx-hostname>:<channel-id>.
extensions[].calls[].customer	Id	Id of customer.
extensions[].calls[].extension	Id	Id of extension the call belongs to.
extensions[].calls[].state	String	Call state: CALL_START, CALL_RING, CALL_ANSWER, CALL_HOLD.
extensions[].calls[].started	Date	When the call started.
extensions[].calls[].ringing	Date	When the call started ringing.
extensions[].calls[].answered	Date	When the call was answered.
extensions[].calls[].caller	Object	Caller data.
extensions[].calls[].caller.number	String	Callers phone number.
extensions[].calls[].caller.name	String	Callers name, if available.
extensions[].calls[].caller.secret	Boolean	True if caller has secret number.
extensions[].calls[].caller.queueId	ObjectId	Id of queue, if call was initiated by a queue.
extensions[].calls[].caller.queueName	String	Name of queue, if call was initiated by a queue.
extensions[].calls[].callee	Object	Callee data.
extensions[].calls[].callee.number	String	Callee phone number.
extensions[].calls[].callee.name	String	Calle name, if available.
extensions[].calls[].sessionId	String	Session ID for the call (to match up inbound and outbound legs of the same call).
extensions[].calls[].channel	String	Unique channel ID for this call leg.
extensions[].calls[].callId	String	SIP call ID, if available.
extensions[].calls[].direction	String	I for inbound call received from the outside, O for outbound to the outside.
extensions[].calls[].leg	String	I for inbound towards the PBX, O outbound from the PBX.
extensions[].calls[].originator	String	Type of call originator: SIPPHONE, MOBILE, EXTERNAL, SYSTEM.
extensions[].calls[].device	Id	Id of the device that the extension is using, if available.
extensions[].calls[].pbx	String	Hostname of the PBX server handling the call.
extensions[].calls[].callerChannelId	String	Unique channel ID of caller when call is received.
extensions[].phones	Array	List of phones - only populated if the employee is the requesting user (e.g. you can see your own phones).
extensions[].phones[]._id	Id	Id of the phone.
extensions[].phones[].type	String	Type of phone: SIPPHONE, MOBILE or EXTERNAL.
extensions[].phones[].name	String	Name of the phone (SIPPHONE) or number (MOBILE/EXTERNAL).
extensions[].phones[].model	String	Phone model - if available.
extensions[].phones[].modelId	Id	Phone model Id - if available.
extensions[].phones[].dnd	Boolean	True if DND is enabled on the phone.
calendar	Array	List of calendar events
calendar[]._id	Id	Id of event.
calendar[].subject	String	Subject for event, null if event is private or confidential and user is not the employee.
calendar[].start	Datetime	Date/time when event starts.
calendar[].end	Datetime	Date/time when event ends.
calendar[].isAllDay	Boolean	True if event is an all day event.
calendar[].type	String	Type of event: singleInstance, occurrence, exception or seriesMaster.
calendar[].showAs	String	How to show: unknown, free, tentative, busy, oof or workingElsewhere.
calendar[].sensitivity	String	Sensitivity: normal - all may view, personal - non-work visible to owner only, private - non-work visible to owner only, confidential - work, visible to owner only.
calendar[].isOrganizer	Boolean	True if the employee the event belongs to is the one who created the event.
calendar[].organizer.emailAddress	String	Email address of the person who created the event.
calendar[].organizer.name	String	Name of the person who created the event.
calendar[].isOnlineMeeting	Boolean	True if this is an online meeting.
calendar[].onlineMeetingJoinUrl	String	Url to invoke, in order to join the meeting. Only available if the event belongs to the user calling this API.

Note that properties holding no value may be omitted from the object.

Example

[
  {
    "_id": "12345678901234567890ABCD",
    "type": "EMPLOYEE",
    "name": "Donald Duck",
    "title": "Master of coin",
    "department": "Finance",
    "viewOtherPartyOverride": "NONE",
    "address": {
      "_id": "12345678901234567890AAAA",
      "primary": true,
      "address": "Quackstreet 27",
      "zip": "2600",
      "city": "Glostrup",
      "country": "DK",
      "municipalityCode": 153
    },
    "emailAddress": "donald@duck.dk",
    "birthdate": "1973-09-26T23:00:00.000Z",
    "picture": "12345678901234567890BBBB",
    "presence": {
      "state": "BUSY",
      "location": "Glostrup office",
      "gps": [],
      "message": "[Teams] meeting",
      "expire": null,
      "overrides": [
        {
          "id": "uidfh489hfinon24infip2einefipe2npife",
          "source": "MS365_TEAMS",
          "state": "BUSY"
        }
      ],
      "originalState": "AVAILABLE",
      "originalMessage": "Now taking calls"
    },
    "extensions": [
      {
        "_id": "12345678901234567890EEEE",
        "number": "102",
        "direct": "+4570305051",
        "mobile": [ "+4571919999" ],
        "primary": true,
        "state": "IDLE",
        "redirect": null,
        "calls": [],
        "phones": [
          {
            "_id": "1234567890123457890BBCC",
            "type": "SIPPHONE",
            "name": "Office",
            "model": "Mitel 6869i",
            "modelId": "12345678901234567890ABFD",
            "dnd": true,
          },
          {
            "_id": "1234567890123457890CCDD",
            "type": "MOBILE",
            "name": "+4571919999",
            "model": "iPhone 11 Pro",
            "dnd": false
          }
        ],
      }
    ],
    "calendar": [
      {
        "_id": "12345678901234567890ABCD",
        "subject": "Important meeting",
        "start": "2025-01-01T00:00:00.000Z",
        "end": "2025-01-01T00:00:00.000Z",
        "isAllDay": false,
        "type": "singleInstance",
        "showAs": "busy",
        "sensitivity": "normal",
        "isOrganizer": false,
        "organizer": {
          "emailAddress": "somebody@somewhere.com",
          "name": "Some Body"
        },
        "isOnlineMeeting": true,
        "onlineMeetingJoinUrl": "https://link-to-meeting.com/meeting-id"
      },
      { ... }
    ]
  },
  { ... }
]

Errors

Error code	Message	Description
403	access_denied	Insufficient access level - no access to the customer.
500	internal_error	<Unspecified>

WIKI

Table of Contents