WIKI

User Tools

Site Tools

You are here: start » api » employee » list
api:employee:list

Table of Contents

API : Employee List

Introduction

This request will return the list of employees on a customer.

Request

URL https://api.telecomx.dk/employee
Method GET
Access level VIEWER, MANAGER or OWNER if user belongs to the customer.
RESELLER if customer belongs to the reseller or a sub reseller.
RESELLER_ADMIN or ADMIN.
Query customer [optional] Id of the customer the employees belongs to, defaults to users own customer.
offset [optional] Index of the first employee to return, default 0.
limit [optional] The number of employees to return, default 100, min 1, max 500.
includeDeleted [optional] If true, also deleted employees are returned.
filter [optional] To filter the employees, this can be used. Common fields of the employees will be searched.
full [optional] If true, complete employee object will be returned instead of the condensed version.
includeMvnoAccounts [optional] If true a condensed list of MVNO accounts that belongs to each employee is included.

Query examples

https://api.telecomx.dk/employee?customer=1234567890ABCDEF12345678
https://api.telecomx.dk/employee?customer=1234567890ABCDEF12345678&filter=abc&offset=10&limit=25&full=true

Response

Property Type Description
offset Number Index of the first employee returned.
limit Number Number of employees to return. Note that the actual number of employees returned may be lower.
total Number Number of employees that can be returned when offset and limit is not considered. This is to be used for paging through the data.
employees Array Array of employees, see definition below.

Employee - normal

Properties Type Description
_id Id Unique employee id.
accessLevel String Access level: NO_LOGIN, PERSONAL, VIEWER, MANAGER, OWNER, RESELLER, RESELLER_ADMIN or ADMIN - see more info.
state Enum State of the employee: ENABLED, DISABLED (cannot login), DELETED.
presenceState String If customer has PBX, then this is the current presence state of the employee: AVAILABLE, BUSY, OUT_OF_OFFICE, OFF_WORK, HOLIDAY.
name String employee name.
title String The employees title.
department String The employees department/section/group.
address Id Id of the address the employee belongs to, null if the same as the customer. (get the full address from the customer object).
emailAddress String E-mail address (also used for login).
primaryContact Boolean True if this employee is the primary contact person at the customer.
picture Id Id of a picture of the employee, null if no picture is set.
smsNumber String Number to send SMS validation to.
smsValidation Boolean True if SMS validation is required.
authenticatorValidation Boolean True if authenticator validation is required.
features Array List of features the employee has access to:
PLAYMAKERSTATUS - access to PlayMaker status site.
DASHBOARD_EDITOR - permission to edit own PBX dashboards.
HUMAN_TASK - can be assigned tasks (only ADMIN).
PORTING - access core porting (only RESELLER_ADMIN and up).
TELE - access core tele (only RESELLER_ADMIN and up).
FINANCE - access core finance (only RESELLER_ADMIN and up).
TV - access core TV and flexcare (only RESELLER_ADMIN and up).
HELPCENTER - Access to Help Center (Only RESELLER_ADMIN and up).
FLEXCARESWAP - Access to swapping FlexCare devices
billingCustomer ObjectID Alternate customer to bill this employee's expenses to.
extensions Array List of extensions the employee has (only if customer has feature PBX).
extensions._id Id Id of extension.
extensions.number String Local extension number.
extensions.redirect String Phone number the extension has been redirected to in E.164 format. Null if not in use.
extensions.direct String Direct phone number for calling the extension, in E.164 format. Null if not in use.
extensions.primary Boolean True if this is the employees primary extension.
product ObjectId Id of PBX user product for this user
newProduct ObjectId PBX_USER product use from the first of next month. Only available for customers with the PBX feature.
deleteDate Date Date this employee will be deleted. Null if not determined
mvnoAccounts Array List of minified MVNO accounts, which belong to this employee, if includedMvnoAccounts = true
mvnoAccounts[]._id Id Id of the MVNO account
mvnoAccounts[].number String Phone number of the MVNO account in E.164 format
mvnoAccounts[].numberState String State of the phone number:
IN_USE - in normal use
PORTING_IN - is currently being ported in
PORTING_OUT - is currently being ported out
mvnoAccounts[].state String The state of the MVNO account. Allowed values are ACTIVE, CREATING, DELETING, BLOCKED. If state is BLOCKED, then the account cannot handle calls/sms/mms/data. If in state DELETING, it is currently under deletion.
mvnoAccounts[].pbx Number Which PBX the MVNO account belongs to. Null or 0 for standalone MVNO accounts.
m2mOnly Boolean True if user may not login, but only use persistent tokens (employee is an M2M account).

Employee - full=true

Property Type Description
_id Id Unique employee id.
customer Id Id of the customer the employee belongs to.
accessLevel String Access level: NO_LOGIN, PERSONAL, VIEWER, MANAGER, OWNER, RESELLER, RESELLER_ADMIN or ADMIN - see more info.
state Enum State of the employee: ENABLED, DISABLED (cannot login), DELETED.
name String employee name.
title String The employees title.
department String The employees department/section/group.
address Id Id of the address the employee belongs to, null if the same as the customer. (get the full address from the customer object).
language String The preferred language: da or en.
primaryContact Boolean True if this employee is the primary contact person at the customer.
Authentication
emailAddress String E-mail address (also used for login).
noEmail Boolean True if employee has no email address and emailAddress is a username instead (min 8 chars).
smsValidation Boolean True if SMS validation is required during login.
smsNumber String Number to send SMS validation to.
authenticatorValidation Boolean True if login requires the use of an authenticator app with a time based token
ipRestriction String If set, one or multiple (comma separated) IP address that the employee may login from.
organizationResellers Array List of ids of resellers this employee may manage when customer has ORGANIZATION feature.
Notifications
notifyOnGeneralUsageLimit Boolean True if the employee wants to be notified by e-mail when an MVNO or SIP accounts is about to reach or has reached its usage limit.
notifyOnGeneralUsageLimitReseller Boolean True if the employee wants to be notified by e-mail when an MVNO or SIP account that belongs to the resellers customer is about to reach or has reached its usage limit (RESELLER and up).
notifyOnAccountErrorByEmail Boolean True to be notified by e-mail when a SIP, DSL or Fiber account is down (disconnected/offline/blocked).
notifyOnAccountErrorBySms Boolean True to be notified by SMS when a SIP, DSL or Fiber account is down (disconnected/offline/blocked).
notifyOnNewMvnoAccountReseller Boolean True to be notified by e-mail when a new MVNO account has been created on one of the reseller's customers
notifyOnNewSipAccountReseller Boolean True to be notified by e-mail when a new SIP account has been created on one of the reseller's customers
notifyOnNewPortingReseller Boolean True to be notified by e-mail when a new porting has been has been created or is being on one of the reseller's customers
subscriptions Array Array of Ids of notification subscription (newsletters, warnings etc.).
presence Object Presence settings (requires PBX)
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.
autoPresence Array List of automated presence changes to perform. Is not performed if current state is “HOLIDAY”
autoPresence[].weekDays Array List of week days this item shall be active. 0=sunday, 1=monday … 6=saturday.
autoPresence[].timeOfDay String Time of day this item shall be executed. ex: 16:00.
autoPresence[].state String State to set: AVAILABLE, BUSY, OUT_OF_OFFICE, OFF_WORK.
voicemail Object Voicemail settings (requires PBX)
voicemail.notification.email Boolean True to receive notification via e-mail.
voicemail.notification.sms Boolean True to receive notification via SMS.
voicemail.requiresPinCode Boolean True if it always requires a pin code to access voicemail.
voicemail.greetingOnly Boolean True if voicemail shall only play greeting.
voicemail.defaultGreeting Id Id of default greeting.
voicemail.offWorkGreeting Id Id of greeting to use when off work. Fallback to default greeting.
voicemail.holidayGreeting Id Id of greeting to use when on holiday. Fallback to default greeting.
recording Object Recording settings (requires PBX)
recording.mode String When to record calls: ALWAYS - all calls are recorded, DEMAND - only record when requested, NEVER - cannot record.
recording.quality String Quality of call recordings:
NORMAL - 8Khz MP3 mono.
COMPACT - xKhz MP3 mono.
HIGH - 16Khz MP3 stereo (each part in separate channels).
recording.retension Number Number of days to store recording: 1, 3, 7, 14 or 30 days. For COMPACT quality 90, 180, 365 & 730 days are also available.
recording.notification.email Boolean True to receive notification when a recording has completed.
recording.notification.attach Boolean True to attach the recording to the e-mail, false to include a download link.
recording.notification.maxSize Number Maximum size of recording in bytes. If this is exceeded a download link will be included instead.
Misc
notes String Notes about the employee, only visible to RESELLERs and ADMINs.
birthdate Date The employees birthdate.
picture Id Id of a picture of the employee, null if not set.
pinCode String 4-10 digit pin code that can be used for voicemail, listening in, hotdesking etc.
custom Object Custom data, max. 4Kb.
persistentTokens Array List of tokens for M2M communication with the same rights as the employee.
mayImpersonate Boolean True if current user may impersonate this employee. Only employees of sub-resellers may be impersonated by employees of a parent reseller.
viewOtherPartyOverride String Override for PBX group access to see who the employee is talking to:
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
billingCustomer Id Alternate customer to bill this employee's expenses to.
deleteDate Date Date this employee will be deleted. Null if not set.
deleteExtensions Boolean Determines whether the user's extensions will also be deleted when the user is deleted. Only used if the user is set to be deleted (requires PBX).
features Array List of features the employee has access to:
PLAYMAKERSTATUS - access to PlayMaker status site.
DASHBOARD_EDITOR - permission to edit own PBX dashboards.
HUMAN_TASK - can be assigned tasks (only ADMIN).
PORTING - access core porting (only RESELLER_ADMIN and up).
TELE - access core tele (only RESELLER_ADMIN and up).
FINANCE - access core finance (only RESELLER_ADMIN and up).
TV - access core TV and flexcare (only RESELLER_ADMIN and up).
HELPCENTER - Access to Help Center (Only RESELLER_ADMIN and up).
FLEXCARESWAP - Access to swapping FlexCare devices
apiAccessFilter Array Optional list of API endpoints this employee may only access.
apiAccessFilter[].endpoint String Permitted endpoint as string path including * wildcard at the end or RegExp.
apiAccessFilter[].type String Type of endpoint filter: STRING or REGEXP.
m2mOnly Boolean True if user may not login, but only use persistent tokens (employee is an M2M account).
webauthnOnly Boolean True if user may only login using webauthn (higher security, blocks addition of new tokens and use of password).
shortcuts Array Array of shortcuts as used in the web UI, see definition below. Only visible if employee is the user herself.
shortcuts[].index Integer Index of the item in the list of items.
shortcuts[].url String URL in the API for accessing the data.
shortcuts[].label String Label to show in the API. Special labels: '—' and no url = horizontal line and a label without a url is a section header.
product Object PBX User product (requires PBX)
product._id Id Product id
product.start Date The date from which the product can be assigned.
product.end Date The date on which the product can not be assigned anymore.
product.type String Type of product: see below.
product.productCode String Id to use when adding a product and for syncing with accounting system when doing invoicing.
product.name String Name of the product.
product.unitType String Type of units: MIN, MB, UNITS, HOURS, KM, MONTHS.
product.recurrence String Type of recurrence: NONE, MONTHLY, QUARTERLY, YEARLY
product.cost Number Cost of the product for one month (if recurring) or one unit (RESELLER_ADMIN or ADMIN).
product.wholesale Number Resellers cost for one month (if recurring) or one unit (only RESELLER and up).
product.price Number Customer price for one month (if recurring) or one unit.
product.inheritFromReseller Id Id of reseller product that this product inherits.
product.includedProducts Array List of products that are included in this PBX user product
product.includedProducts[]._id Id Id of the included product
product.includedProducts[].amount Number The amount of this product that is included
newProduct Id PBX_USER product use from the first of next month. Only available for customers with the PBX feature.
addonProducts Array Extra ad hoc products added to an employee, ie. renting busy light etc.
addonProducts[]._id Id Id making each addition to the list unique
addonProducts[].product Id Product id
addonProducts[].name String Name override of the addon product
addonProducts[].description String Description
addonProducts[].invoicedUntil Date Date of when this product is invoiced until.
addonProducts[].unitPrice Number Customer price override for this product, can be used for discount purposes
addonProducts[].units Number Amount of the given product that is added to the employee
addonProducts[].start Date Date of when this product should be billed from
addonProducts[].terminate Date Date of when the product should stop be terminated
ms365 Object Integration settings, if PBX and Microsoft 365 integration is enabled on the customer, else null.
ms365.id String If employee is paired with a user on MS365, this is the user id on MS365, otherwise null.
ms365.calendarSetsPresence Boolean True if an ongoing calendar event will mark the employee as busy/out_of_office during the event.
ms365.teamsSetsPresence Boolean If true, employees presence will be set to busy when employee is in a teams meeting or call.
ms365.presenceSync Boolean If true, then setting presence in MS365 will also set presence on the PBX.
ms365.doNotSyncContacts Boolean True if contacts may not be sync'ed for this employee.
ms365.doNotSyncCalendar Boolean True if calendar may not be sync'ed for this employee.

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

Example - normal

{
  offset: 10,
  limit: 25,
  total: 243,
  employees:
  [
    {
      _id: '52f4fd7734697b28ccafeeff',
      accessLevel: 'OWNER',
      state: 'ENABLED',
      presenceState: 'AVAILABLE',
      name: 'Donald Duck',
      address: '52f4fd7734697b2800000001',
      title: 'Managing director',
      department: 'Apples Inc',
      emailAddress: 'donald@duck.com',
      fixedNumber: '12345678',
      mobileNumber: '87654321',
      smsValidation: false,
      authenticatorValidation: true,
      primaryContact: true,
      m2mOnly: false
    },
    {
      _id: '52f4fd7734697325ccaeeed0',
      accessLevel: 'VIEWER',
      state: 'ENABLED',
      presenceState: 'OFF_WORK',
      name: 'Emmet Brown',
      address: null,
      title: 'Head of research',
      department: 'Innovation',
      emailAddress: 'emmet@duck.com',
      smsNumber: '+4571919999',
      smsValidation: false,
      authenticatorValidation: true,
      extensions: [
        {
          _id: '1234578901234567890ABCD',
          number: '200',
          redirect: null,
          direct: '+4570305050'
        }
      ],
      product: '1234578901234567890ABCD',
      newProduct: '4234567890ABCD1234567890',
      deleteDate: '2024-06-28T20:00:00.000Z'
    },
    m2mOnly: false
  ]
}

Example - full=true

{
  offset: 10,
  limit: 10,
  total: 23,
  employees:
  [
    {
      _id: '52f4fd7734697b28ccafeeff',
      accessLevel: 'OWNER',
      state: 'ENABLED',
      name: 'Donald Duck',
      address: '52f4fd7734697b2800000001',
      title: 'Managing director',
      department: 'Apples Inc',
      emailAddress: 'donald@duck.com',
      noEmail: false,
      ipRestriction: '87.234.55.240',
      language: 'da',
      notes: 'Don\'t quack around with him',
      primaryContact: true,
      smsValidation: false,
      smsNumber: '',
      authenticatorValidation: true,
      subscriptions: [ '1234567890ABCDEF12345678', 'ABCDEF123456789012345678' ],
      birthdate: '2015-01-01T00:00:00.000Z',
      picture: '12345878901234567890ABCD',
      pinCode: '5678',
      apiAccessFilter: [],
      m2mOnly: false,
      webauthnOnly: false,
      organizationResellers: null,
      presence: {
        state: 'BUSY',
        location: 'CPH office',
        message: 'In a meeting until 15.00',
        expire: '2015-07-23T15:00:00.000Z'
      },
      presence: {
        state: 'BUSY',
        location: 'Copenhagen office',
        gps: [],
        message: 'In a meeting',
        expire: ISODate('2018-01-01T13:00:00Z')
      },
      autoPresence: [
        {
          weekDays: [ 1,2,3,4,5 ],
          timeOfDay: '08:00',
          state: 'AVAILABLE'
        },
        {
          weekDays: [ 1,2,3,4 ],
          timeOfDay: '16:00',
          state: 'OFF_WORK'
        },
        {
          weekDays: [ 5 ],
          timeOfDay: '15:30',
          state: 'OFF_WORK'
        }
      ],
      voicemail: {
        notification: {
          email: false,
          sms: true
        },
        requiresPinCode: true,
        greetingOnly: false,
        defaultGreeting: '12345678901234567890AACC',
        offWorkGreeting: '12345678901234567890AADD',
        holidayGreeting: '12345678901234567890AAEE'
      },
      recording: {
        mode: 'DEMAND',
        quality: 'NORMAL',
        retension: 7,
        notification: {
          email: true,
          attach: true,
          maxSize: 10485760
        }
      },
      custom: {
        exchangeGuid: '1234-123456-1234-1234-123456',
        domainUsername: 'donald'
      },
      viewOtherPartyOverride: 'NONE',
      product: {
        _id: '1234578901234567890ABCD',
        name: 'DK budget mobileplan',
        type: 'MVNO_RATEPLAN',
        productCode: '02031',
        wholesale: 20,
        price: 49,
        start: 2015-01-01T00:00:00.000Z,
        end: null,
        recurrence: 'MONTHLY',
        unitType: 'MONTH',
        inheritFromReseller: '8234578901234567890ABCD',
        includedProducts: [
          {
            _id: '4234578901234567890ABCD',
            amount: 3
          },
          {
            _id: '9144578901234567890ABCD',
            amount: 1
          }
        ]
      },
      ms365: {
        id: '348t5758tguh48tguh3f8ghb4e8vhe38vhe8rbvueinv',
        calendarSetsPresence: true,
        teamsSetsPresence: true,
        presenceSync: false,
        doNotSyncContacts: false,
        doNotSyncCalendar: false
    },
    {
      _id: '52f4fd7734697325ccaeeed0',
      accessLevel: 'VIEWER',
      state: 'ENABLED',
      name: 'Emmet Brown',
      address: null,
      title: 'Head of research',
      department: 'Innovation',
      emailAddress: 'emmet@duck.com',
      ipRestriction: '87.234.55.240',
      language: 'da',
      notes: 'He is going back to the future',
      primaryContact: false,
      smsValidation: true,
      subscriptions: [ 'ABCDEF123456789012345678' ],
      birthdate: '2015-01-01T00:00:00.000Z',
      picture: '12345878901234567890ABCD',
      pinCode: '5678',
      presence: {
        state: 'BUSY',
        location: 'CPH office',
        gps: [],
        message: 'In a meeting until 15.00',
        expire: '2015-07-23T15:00:00.000Z'
      },
      voicemailNotification: { email: true, sms: false },
      voicemailRequiresPinCode: true,
      recordingQuality: 'NORMAL',
      recordingRetension: 7,
      recordingMode: 'ALWAYS',
      viewOtherPartyOverride: 'NONE'
    },
    apiAccessFilter: [],
    m2mOnly: false,
    webauthnOnly: false
  ]
}

Errors

Error code Message Description
400 customer Customer not found in arguments
403 access_denied Insufficient access level - no access to the customer.
500 internal_error <Unspecified>
api/employee/list.txt · Last modified: 2025/11/10 08:35 by Per Møller
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki